# Code Reference (/docs)



Welcome to the **Code Reference** docs — focused notes for everyday coding.

Each page covers overview, core concepts, examples, pitfalls, and related links.

## Topics [#topics]

<Cards>
  <Card title="Python" href="/docs/python" description="Language core, stdlib, tooling, examples" />

  <Card title="JavaScript" href="/docs/javascript" description="Language, async, modules, DOM" />

  <Card title="TypeScript" href="/docs/typescript" description="Types, generics, tooling" />

  <Card title="React" href="/docs/react" description="Components, hooks, patterns" />

  <Card title="React Native" href="/docs/react-native" description="Mobile UI, APIs, Expo" />

  <Card title="Next.js" href="/docs/nextjs" description="App Router, RSC, deployment" />

  <Card title="Node.js" href="/docs/node" description="Express, Fastify, HTTP servers" />

  <Card title="Zod" href="/docs/zod" description="Schema validation & TypeScript inference" />

  <Card title="Tailwind" href="/docs/tailwind" description="Utility-first CSS" />

  <Card title="CSS" href="/docs/css" description="Layout, cascade, modern CSS" />

  <Card title="HTML" href="/docs/html" description="Semantic markup, media, a11y" />

  <Card title="Django" href="/docs/django" description="ORM, views, auth, DRF" />

  <Card title="Docker" href="/docs/docker" description="Images, Compose, containers" />

  <Card title="Redis" href="/docs/redis" description="Cache, data structures, pub/sub" />

  <Card title="Postgres" href="/docs/postgres" description="Ops, indexes, backups, EXPLAIN" />

  <Card title="SQL" href="/docs/sql" description="Queries, schema, advanced SQL" />

  <Card title="Playwright" href="/docs/playwright" description="E2E browser testing" />

  <Card title="Pytest" href="/docs/pytest" description="Python testing framework" />

  <Card title="Jest" href="/docs/jest" description="JavaScript testing framework" />

  <Card title="Bash" href="/docs/bash" description="Shell scripting essentials" />

  <Card title="PowerShell" href="/docs/powershell" description="Windows shell & automation" />

  <Card title="GitHub Actions" href="/docs/github-actions" description="CI/CD workflows" />

  <Card title="Git" href="/docs/git" description="Everyday Git, recovery, GitHub CLI" />

  <Card title="Comparisons" href="/docs/comparisons" description="A vs B trade-offs" />
</Cards>

## How notes are structured [#how-notes-are-structured]

1. **Overview** — what and when
2. **Core concepts** — APIs / syntax
3. **Examples** — runnable snippets
4. **Pitfalls** — mistakes to avoid
5. **Related** — sibling notes

Built with [Fumadocs](https://www.fumadocs.dev/docs).


# Arrays (/docs/bash/arrays)



# Arrays [#arrays]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash has indexed arrays (`declare -a`) and associative arrays (`declare -A`, bash 4+). Always expand with `"$\{arr[@]\}"` to preserve elements. Arrays are the safe alternative to storing lists in a single string.

## 🔧 Core concepts [#-core-concepts]

| Syntax           | Meaning                                |
| ---------------- | -------------------------------------- |
| `arr=(a b c)`    | Indexed array                          |
| `arr[i]=val`     | Set element                            |
| `"$\{arr[@]\}"`  | All elements (separate words)          |
| `"$\{arr[*]\}"`  | Joined with first IFS char when quoted |
| `$\{#arr[@]\}`   | Length                                 |
| `$\{!arr[@]\}`   | Indices / keys                         |
| `arr+=(x)`       | Append                                 |
| `unset 'arr[i]'` | Remove element                         |
| `declare -A map` | Associative array                      |
| `map=([k]=v)`    | Assoc init                             |

Sparse indexed arrays keep original indices after `unset`. Iterate keys with `"$\{!arr[@]\}"`.

## 💡 Examples [#-examples]

**Indexed:**

```shellscript
files=("a b.txt" "c.txt")
files+=("d.txt")
echo "${#files[@]}"
for f in "${files[@]}"; do
  echo "$f"
done
echo "${files[0]}"
```

**Slice and copy:**

```shellscript
slice=("${files[@]:1:2}")     # 2 elems from index 1
copy=("${files[@]}")
```

**Associative:**

```shellscript
declare -A ports=([web]=80 [db]=5432)
ports[cache]=6379
for k in "${!ports[@]}"; do
  echo "$k -> ${ports[$k]}"
done
```

**From command (mapfile):**

```shellscript
mapfile -t lines < file.txt
mapfile -d '' -t paths < <(find . -print0)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `"$\{arr[@]\}"` vs `$\{arr[@]\}`: always quote.
* `"$\{arr[*]\}"` is one string when quoted—wrong for iterating items with spaces.
* Associative arrays need bash 4+; macOS system bash may be 3.2—use Homebrew bash or avoid.
* `arr=($string)` splits on IFS; prefer `read -a` or `mapfile`.
* `unset arr` removes whole array; `unset 'arr[0]'` one element.
* Indices are not re-packed after delete; don’t assume contiguous `0..n-1`.

## 🔗 Related [#-related]

* [variables.md](/docs/bash/variables)
* [quoting.md](/docs/bash/quoting)
* [loops.md](/docs/bash/loops)
* [string\_ops.md](/docs/bash/string-ops)
* [globbing.md](/docs/bash/globbing)


# Conditionals (/docs/bash/conditionals)



# Conditionals [#conditionals]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash branches with `if`/`elif`/`else`, `case`, and `[[ ]]` / `[ ]` / `(( ))` tests. Prefer `[[ ]]` for strings and files; `(( ))` for integers. Exit status `0` is true; non-zero is false.

## 🔧 Core concepts [#-core-concepts]

| Construct            | Use                                    |
| -------------------- | -------------------------------------- |
| `if cmd; then …; fi` | Branch on exit status                  |
| `[[ expr ]]`         | Bash test (safer, richer)              |
| `[ expr ]` / `test`  | POSIX test                             |
| `(( expr ))`         | Arithmetic; 0 → false, non-zero → true |
| `case $x in … esac`  | Pattern match                          |
| `&&` / `\|\|`        | Short-circuit                          |

**`[[ ]]` operators:** `-eq -ne -lt -le -gt -ge` (numbers as strings carefully), `=`, `==`, `!=`, `=~` regex, `-z` empty, `-n` non-empty, `-f -d -e -L -r -w -x` files, `-nt` / `-ot` newer/older.

## 💡 Examples [#-examples]

**File and string checks:**

```shellscript
if [[ -f "$config" && -r "$config" ]]; then
  source "$config"
elif [[ -z "${config:-}" ]]; then
  echo "No config" >&2
  exit 1
fi
```

**Numeric:**

```shellscript
if (( count > 10 )); then
  echo "too many"
fi

if [[ "$count" -gt 10 ]]; then …; fi   # integer compare in [[ ]]
```

**Regex and case:**

```shellscript
if [[ "$email" =~ ^[A-Za-z0-9._%+-]+@ ]]; then
  echo "looks like email"
fi

case "$1" in
  start|on)  start_svc ;;
  stop|off)  stop_svc ;;
  *)         echo "usage: $0 start|stop" >&2; exit 2 ;;
esac
```

**One-liners:**

```shellscript
[[ -d "$dir" ]] || mkdir -p "$dir"
command -v jq >/dev/null || { echo "jq required"; exit 1; }
```

## ⚠️ Pitfalls [#️-pitfalls]

* `[ $a = $b ]` breaks on empty/spaces; always quote: `[ "$a" = "$b" ]`.
* `==` inside `[ ]` is non-POSIX; use `=` or switch to `[[ ]]`.
* `(( ))` treats empty/unset as 0 with `set -u` risks—initialize first.
* `=~` right-hand side should be unquoted to be a regex; quoted = literal.
* Prefer `[[ ]]` over `[ ]` in bash scripts; keep `[ ]` for `sh` portability.
* `if cmd` tests exit code—not stdout. Capture output separately.

## 🔗 Related [#-related]

* [exit\_codes.md](/docs/bash/exit-codes)
* [loops.md](/docs/bash/loops)
* [quoting.md](/docs/bash/quoting)
* [variables.md](/docs/bash/variables)
* [debugging.md](/docs/bash/debugging)


# Cron (/docs/bash/cron)



# Cron [#cron]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Cron schedules recurring jobs via crontab entries. Each line is five time fields plus a command. Cron runs with a minimal environment—always set `PATH`, use absolute paths, and redirect logs. Prefer systemd timers on modern Linux when available.

## 🔧 Core concepts [#-core-concepts]

| Field  | Values          |
| ------ | --------------- |
| Minute | 0–59            |
| Hour   | 0–23            |
| Dom    | 1–31            |
| Month  | 1–12            |
| Dow    | 0–7 (0/7 = Sun) |
| `*`    | Any             |
| `*/n`  | Every n         |
| `a,b`  | List            |
| `a-b`  | Range           |

| Command        | Role                 |
| -------------- | -------------------- |
| `crontab -e`   | Edit user crontab    |
| `crontab -l`   | List                 |
| `crontab -r`   | Remove (dangerous)   |
| `/etc/cron.d/` | System drop-in files |

Special strings (Vixie): `@reboot`, `@daily`, `@hourly`, `@weekly`, `@monthly`.

## 💡 Examples [#-examples]

**User crontab entries:**

```cron
SHELL=/bin/bash
PATH=/usr/local/bin:/usr/bin:/bin
MAILTO=""

# Every day at 02:30
30 2 * * * /home/ada/bin/backup.sh >>/home/ada/logs/backup.log 2>&1

# Every 15 minutes
*/15 * * * * /usr/bin/curl -fsS https://example.com/health >/dev/null

@reboot /home/ada/bin/on-boot.sh
```

**Wrapper script:**

```shellscript
#!/usr/bin/env bash
set -euo pipefail
cd "$HOME/app"
/usr/bin/flock -n /tmp/app-cron.lock ./job.sh
```

**Systemd alternative (sketch):**

```ini
# app.timer + app.service with OnCalendar=*-*-* 02:30:00
```

## ⚠️ Pitfalls [#️-pitfalls]

* Cron’s `PATH` is short—commands that work interactively may “not be found”.
* `%` in commands is special in crontab (newline)—escape as `\%`.
* No TTY; don’t assume interactive prompts or ssh-agent unless configured.
* Overlapping runs: use `flock` to prevent pile-ups.
* Timezone is the system timezone unless you set `TZ=`.
* `crontab -r` deletes without confirmation on some systems.

## 🔗 Related [#-related]

* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [shebang.md](/docs/bash/shebang)
* [exit\_codes.md](/docs/bash/exit-codes)
* [debugging.md](/docs/bash/debugging)
* [ssh.md](/docs/bash/ssh)


# Debugging (/docs/bash/debugging)



# Debugging [#debugging]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Debug bash with tracing (`set -x`), verbose mode, ShellCheck, and strategic logging. Reproduce with the same options and environment as production. Prefer small reproducible snippets over editing large scripts blindly.

## 🔧 Core concepts [#-core-concepts]

| Tool                | Purpose                        |
| ------------------- | ------------------------------ |
| `set -x` / `set +x` | Trace expanded commands        |
| `set -v`            | Print input lines as read      |
| `PS4`               | Prefix for `set -x` traces     |
| `bash -n script`    | Syntax check only              |
| `bash -x script`    | Run with trace                 |
| `trap`              | Catch `ERR` / `DEBUG` / `EXIT` |
| ShellCheck          | Lint common bugs               |
| `printf '%q\n'`     | Show shell-escaped values      |

`ERR` trap runs when a command fails (with `set -e` nuances). `DEBUG` trap runs before each command.

## 💡 Examples [#-examples]

**Trace with context:**

```shellscript
export PS4='+${BASH_SOURCE}:${LINENO}:${FUNCNAME[0]}: '
set -x
# … suspect code …
set +x
```

**ERR trap:**

```shellscript
trap 'echo "ERR at ${BASH_SOURCE}:${LINENO}: $BASH_COMMAND" >&2' ERR
set -euo pipefail
```

**Inspect values:**

```shellscript
declare -p var
printf 'args:'; printf ' <%q>' "$@"; echo
type -a cmd
command -v cmd
```

**Dry syntax + lint:**

```shellscript
bash -n ./deploy.sh
shellcheck -x ./deploy.sh
```

**Conditional debug flag:**

```shellscript
debug() { [[ "${DEBUG:-}" == 1 ]] && printf '%s\n' "$*" >&2; }
debug "port=$port"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `set -x` prints secrets—disable around credential handling or redact.
* Tracing changes timing (Heisenbugs in races).
* `bash -n` does not catch runtime logic errors.
* Don’t leave `set -x` on in production cron output floods.
* Pipeline failures need `pipefail` to surface in traces meaningfully.
* Subshells complicate stack traces—note `(…)` boundaries.

## 🔗 Related [#-related]

* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [exit\_codes.md](/docs/bash/exit-codes)
* [shebang.md](/docs/bash/shebang)
* [variables.md](/docs/bash/variables)
* [pipes\_redirection.md](/docs/bash/pipes-redirection)


# Environment Basics (/docs/bash/environment-basics)



# Environment Basics [#environment-basics]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The **environment** is a set of key/value variables available to your shell and the programs it starts. Common ones: `PATH`, `HOME`, `USER`, `PWD`. Scripts often read `VAR=value` settings for configuration.

## 🔧 Core concepts [#-core-concepts]

| Idea                  | Meaning                                                    |
| --------------------- | ---------------------------------------------------------- |
| Environment variable  | Name → string value                                        |
| `export`              | Mark a variable for child processes                        |
| `PATH`                | Colon-separated list of directories to search for commands |
| `$VAR` / `"$\{VAR\}"` | Expand a variable                                          |
| `.env` files          | Convention for app config (not automatic in Bash)          |

Shell variables and environment variables are related; `export` promotes a shell variable into the environment.

## 💡 Examples [#-examples]

**Inspect common variables:**

```shellscript
echo "$HOME"
echo "$USER"
echo "$PWD"
echo "$PATH"
```

**Set for one command:**

```shellscript
LANG=C date
MESSAGE="hi" bash -c 'echo "$MESSAGE"'
```

**Export for the current session:**

```shellscript
export APP_ENV=development
echo "$APP_ENV"
env | grep APP_ENV
```

**Add a directory to PATH (session only):**

```shellscript
export PATH="$HOME/bin:$PATH"
which python || true
```

## ⚠️ Pitfalls [#️-pitfalls]

* Always quote expansions: `"$VAR"` — unquoted values with spaces break.
* `export FOO = bar` is wrong (spaces around `=`).
* Changing `PATH` incorrectly can make every command “not found.”
* Putting secrets in world-readable scripts or committing `.env` is unsafe.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/bash/getting-started)
* [navigation.md](/docs/bash/navigation)
* [variables.md](/docs/bash/variables)
* [permissions\_basics.md](/docs/bash/permissions-basics)


# Exit Codes (/docs/bash/exit-codes)



# Exit Codes [#exit-codes]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Every command returns an 8-bit exit status: `0` success, `1–255` failure. Scripts should exit with meaningful codes. `$?` holds the last foreground status; with `pipefail`, pipelines report the rightmost non-zero (or zero if all succeed).

## 🔧 Core concepts [#-core-concepts]

| Code    | Convention                                    |
| ------- | --------------------------------------------- |
| `0`     | Success                                       |
| `1`     | General error                                 |
| `2`     | Misuse of shell builtins / bad usage (common) |
| `126`   | Found but not executable                      |
| `127`   | Command not found                             |
| `128+N` | Fatal signal N (e.g. 130 = SIGINT)            |
| `255`   | Out-of-range `exit` (wrapped)                 |

| Tool              | Role                           |
| ----------------- | ------------------------------ |
| `exit N`          | End shell/script with status N |
| `return N`        | End function with status N     |
| `$?`              | Last status                    |
| `set -e`          | Exit on failure (with caveats) |
| `set -o pipefail` | Pipeline status                |

sysexits.h codes (`EX_USAGE=64`, etc.) appear in some tools but are optional for scripts.

## 💡 Examples [#-examples]

**Check and propagate:**

```shellscript
if ! git pull; then
  echo "pull failed: $?" >&2
  exit 1
fi
```

**Meaningful script exits:**

```shellscript
usage() { echo "usage: $0 <file>" >&2; exit 2; }
[[ $# -eq 1 ]] || usage
[[ -f "$1" ]] || { echo "missing file" >&2; exit 1; }
```

**Capture without losing status:**

```shellscript
output="$(cmd)" || status=$?
status=${status:-0}
```

**Pipeline:**

```shellscript
set -o pipefail
false | true     # status 1 with pipefail; 0 without
```

## ⚠️ Pitfalls [#️-pitfalls]

* `exit` with values outside 0–255 are truncated modulo 256.
* `cmd || true` swallows failures—use only when intentional.
* `set -e` is disabled in some contexts (`if`, `&&`, `||`, `!`)—know the rules.
* Assignments: `local x=$(false)` may not trigger `set -e` as expected.
* Background jobs: `wait $pid` yields that job’s status.
* Don’t parse `$?` after another command overwrote it—save immediately.

## 🔗 Related [#-related]

* [conditionals.md](/docs/bash/conditionals)
* [pipes\_redirection.md](/docs/bash/pipes-redirection)
* [debugging.md](/docs/bash/debugging)
* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [functions.md](/docs/bash/functions)


# Functions (/docs/bash/functions)



# Functions [#functions]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Functions group reusable commands. They share the shell’s process (unless you spawn a subshell). Arguments arrive as `$1`…`"$@"`. Prefer `local` for internals and explicit `return` status (0–255).

## 🔧 Core concepts [#-core-concepts]

| Topic        | Detail                                        |
| ------------ | --------------------------------------------- |
| Define       | `name() \{ …; \}` or `function name \{ …; \}` |
| Call         | `name arg1 arg2` (no parentheses)             |
| Args         | `$1`, `$2`, `"$@"`, `$#`                      |
| Locals       | `local var=value`                             |
| Return       | `return N` (exit status); stdout for data     |
| Scope        | Dynamic; locals shadow globals                |
| `declare -f` | List function bodies                          |

Functions cannot return structured data via `return`—print to stdout and capture with `$(...)`, or use namerefs (`declare -n`) / globals carefully.

## 💡 Examples [#-examples]

**Basic with locals:**

```shellscript
greet() {
  local who="${1:-world}"
  echo "Hello, $who"
}
greet "Ada"
```

**Return status vs output:**

```shellscript
is_dir() {
  [[ -d "$1" ]]
}

path_join() {
  local a="$1" b="$2"
  echo "${a%/}/$b"
}

if is_dir "/tmp"; then
  out="$(path_join "/var" "log")"
fi
```

**Nameref (bash 4.3+):**

```shellscript
append() {
  local -n _arr=$1
  shift
  _arr+=("$@")
}
list=()
append list a b
```

**Guard usage:**

```shellscript
usage() { echo "usage: $0 <file>" >&2; }

main() {
  [[ $# -ge 1 ]] || { usage; return 2; }
  …
}
main "$@"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `local var=$(cmd)` masks `cmd`’s exit status; split assign and check.
* Forgetting `local` leaks variables into the global scope.
* `return` outside a function exits the shell when sourced carefully—use only in functions.
* Recursion depth and performance: bash functions are not optimized like compiled code.
* Defining functions in a pipeline/subshell does not affect the parent shell.
* Name clashes with external commands: prefer project prefixes (`myapp_`).

## 🔗 Related [#-related]

* [variables.md](/docs/bash/variables)
* [exit\_codes.md](/docs/bash/exit-codes)
* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [subshells.md](/docs/bash/subshells)
* [getopts.md](/docs/bash/getopts)


# getopts (/docs/bash/getopts)



# getopts [#getopts]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`getopts` parses single-letter command-line options in a portable way. It handles clustered flags (`-abc`), optional/required arguments, and error reporting. For long options (`--verbose`), use a manual loop or external tools—not plain `getopts`.

## 🔧 Core concepts [#-core-concepts]

| Piece                    | Role                                               |
| ------------------------ | -------------------------------------------------- |
| `getopts optstring name` | Parse next option into `name`                      |
| `optstring`              | Letters; append `:` if option requires an argument |
| Leading `:` in optstring | Silent error mode (`?` / `:` in name)              |
| `$OPTARG`                | Argument value or bad option letter                |
| `$OPTIND`                | Next argv index to process                         |
| `--`                     | End of options (caller convention)                 |

After the loop, remaining operands are `"$@"` shifted with `shift $((OPTIND - 1))`.

## 💡 Examples [#-examples]

**Classic flags:**

```shellscript
#!/usr/bin/env bash
verbose=0
file=""

while getopts ':vf:' opt; do
  case "$opt" in
    v) verbose=1 ;;
    f) file="$OPTARG" ;;
    :) echo "option -$OPTARG requires an argument" >&2; exit 2 ;;
    ?) echo "unknown option -$OPTARG" >&2; exit 2 ;;
  esac
done
shift $((OPTIND - 1))

echo "verbose=$verbose file=$file args: $*"
```

**Usage pattern:**

```shellscript
usage() {
  cat <<'EOF' >&2
usage: tool [-v] [-f file] [args...]
EOF
  exit 2
}
```

**Reset for reuse (functions):**

```shellscript
OPTIND=1
```

## ⚠️ Pitfalls [#️-pitfalls]

* `getopts` does not parse `--long` options.
* Missing required args: with silent mode, `opt` is `:` and `OPTARG` is the option letter.
* Forgetting `shift $((OPTIND - 1))` leaves flags in `"$@"`.
* `OPTIND` is global—reset when calling `getopts` multiple times.
* Option arguments starting with `-` are still accepted as `OPTARG`.
* Prefer `getopts` over hand-rolled `$#` loops for short options.

## 🔗 Related [#-related]

* [functions.md](/docs/bash/functions)
* [variables.md](/docs/bash/variables)
* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [conditionals.md](/docs/bash/conditionals)
* [exit\_codes.md](/docs/bash/exit-codes)


# Getting Started with Bash (/docs/bash/getting-started)



# Getting Started with Bash [#getting-started-with-bash]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash (Bourne Again SHell) is a command-line shell and scripting language common on Linux and macOS. You type commands interactively or save them in a script (`*.sh`) starting with a shebang.

## 🔧 Core concepts [#-core-concepts]

| Idea        | Meaning                                           |
| ----------- | ------------------------------------------------- |
| Shell       | Program that reads commands and runs programs     |
| Prompt      | Where you type (`$` often means a normal user)    |
| Command     | Program name + arguments: `ls -la`                |
| Script      | File of commands executed in order                |
| Shebang     | `#!/usr/bin/env bash` on line 1 of scripts        |
| Exit status | `0` usually means success; non-zero means failure |

On Windows you can use Git Bash, WSL, or another Unix-like environment.

## 💡 Examples [#-examples]

**Who am I / where am I:**

```shellscript
whoami
pwd
echo "Hello from Bash"
```

**Check Bash version:**

```shellscript
bash --version
echo "$BASH_VERSION"
```

**Minimal script (`hello.sh`):**

```shellscript
#!/usr/bin/env bash
set -euo pipefail
echo "Hello, World!"
```

```shellscript
chmod +x hello.sh
./hello.sh
```

**Run a one-liner without a file:**

```shellscript
bash -c 'echo hi; pwd'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Spaces matter: `cd My Dir` fails; use `cd "My Dir"`.
* Your login shell might be zsh on macOS — scripts can still use Bash via shebang.
* Copying Windows paths (`C:\...`) into Bash needs `/c/...` or WSL paths.
* Forgetting `chmod +x` leads to “Permission denied” on `./script.sh`.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/bash/hello-world)
* [navigation.md](/docs/bash/navigation)
* [permissions\_basics.md](/docs/bash/permissions-basics)
* [environment\_basics.md](/docs/bash/environment-basics)


# Globbing (/docs/bash/globbing)



# Globbing [#globbing]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Globs (pathname expansion) match filenames with `*`, `?`, and `[]` before the command runs. Unlike regex, `*` never matches `/` across directories unless globstar is on. Quote patterns when you want literals; enable `nullglob` / `failglob` for safer scripts.

## 🔧 Core concepts [#-core-concepts]

| Pattern           | Matches                               |
| ----------------- | ------------------------------------- |
| `*`               | Any string except `/`                 |
| `?`               | Single character                      |
| `[abc]` / `[a-z]` | Character class                       |
| `[!a]` / `[^a]`   | Negated class                         |
| `**`              | Recursive (needs `shopt -s globstar`) |
| `*(pat)` etc.     | Extglob patterns (`shopt -s extglob`) |

| `shopt`      | Effect                 |
| ------------ | ---------------------- |
| `nullglob`   | Unmatched glob → empty |
| `failglob`   | Unmatched glob → error |
| `dotglob`    | Include `.hidden`      |
| `nocaseglob` | Case-insensitive       |
| `globstar`   | Enable `**`            |

## 💡 Examples [#-examples]

**Safe iteration:**

```shellscript
shopt -s nullglob
for f in *.log; do
  echo "$f"
done
```

**Extglob:**

```shellscript
shopt -s extglob
rm -- !(keep|also-keep).tmp
ls *.(jpg|png|gif)
```

**Globstar:**

```shellscript
shopt -s globstar nullglob
for f in **/*.py; do
  echo "$f"
done
```

**Disable expansion:**

```shellscript
echo "*.txt"           # literal
printf '%s\n' *.txt    # expanded list
```

## ⚠️ Pitfalls [#️-pitfalls]

* Default: unmatched `*.txt` stays as the literal string `*.txt`—dangerous in `rm`.
* Globs don’t sort the way you always expect across locales; sort explicitly if needed.
* `**` without `globstar` is just two `*` tokens in some contexts—enable the option.
* Brace expansion `\{a,b\}` is not globbing; it runs even if files don’t exist.
* Leading `.` files ignored unless `dotglob` or pattern starts with `.`.
* Never parse `ls`; use globs or `find`.

## 🔗 Related [#-related]

* [quoting.md](/docs/bash/quoting)
* [loops.md](/docs/bash/loops)
* [arrays.md](/docs/bash/arrays)
* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [string\_ops.md](/docs/bash/string-ops)


# Glossary (/docs/bash/glossary)



# Glossary [#glossary]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core Bash terms for shells, scripting, expansion, pipelines, and process control.

## 🔧 Core concepts [#-core-concepts]

| Term                 | Definition                                                                      |     |
| -------------------- | ------------------------------------------------------------------------------- | --- |
| Alias                | A short name that expands to a longer command string.                           |     |
| Argument             | A token passed to a command after its name.                                     |     |
| Array                | An indexed list of strings accessible as `$\{arr[i]\}`.                         |     |
| Brace expansion      | Generating multiple strings from patterns like `\{a,b\}` or `\{1..5\}`.         |     |
| Builtin              | A command implemented inside the shell, not as an external binary.              |     |
| Command substitution | Capturing a command’s output with `$(...)` or backticks.                        |     |
| Conditional          | An `if`/`[[ ]]`/`case` construct that branches on tests.                        |     |
| Exit code            | An integer status (`$?`) where `0` usually means success.                       |     |
| Expansion            | Transformations Bash applies before running a command (variables, globs, etc.). |     |
| Function             | A named compound command defined in the shell.                                  |     |
| Glob                 | A filename pattern using `*`, `?`, or `[]` that expands to matching paths.      |     |
| Here-doc             | A multiline string redirected into a command via `&lt;<EOF`.                    |     |
| IFS                  | Internal Field Separator used for word splitting and some expansions.           |     |
| Job                  | A pipeline managed by the shell’s job control (`fg`, `bg`, `jobs`).             |     |
| Loop                 | A `for`, `while`, or `until` construct that repeats commands.                   |     |
| Option               | A flag such as `-x` or `set -e` that changes shell behavior.                    |     |
| Pipe                 | Connecting one command’s stdout to another’s stdin with \`                      | \`. |
| Process substitution | Treating a command’s output as a file via `&lt;(...)` or `>(...)`.              |     |
| Quoting              | Rules (`'`, `"`, `\`) that control whether expansion occurs.                    |     |
| Redirection          | Sending stdin/stdout/stderr to files or other descriptors (`>`, `2>`, `&>`).    |     |
| Shebang              | The `#!/bin/bash` line that selects the interpreter for a script.               |     |
| Signal               | An OS notification such as `SIGINT` that processes can trap or ignore.          |     |
| Subshell             | A child shell environment created by `(...)` or some pipelines.                 |     |
| Trap                 | A handler that runs commands when a signal or exit occurs.                      |     |
| Variable             | A named string storage slot such as `NAME=value` and `$NAME`.                   |     |
| Word splitting       | Breaking unquoted expansions on `IFS` characters into multiple fields.          |     |

## 💡 Examples [#-examples]

**Variables, quoting, and exit codes:**

```shellscript
name="Ada Lovelace"
echo "Hello, $name"
grep -q pattern file.txt
echo $?
```

**Pipes and redirection:**

```shellscript
ps aux | grep nginx | awk '{print $2}' > pids.txt 2>/dev/null
```

**Arrays and globbing:**

```shellscript
files=(*.md)
echo "${#files[@]} files"
printf '%s\n' "${files[@]}"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **single quotes** (literal) with **double quotes** (allow `$` and `` ` `` expansion).
* Mixing **array** indexing with string variables — unquoted `$arr` is not safe iteration.
* Treating **exit code** `0` as false in `if` — in Bash, `0` is success/true.
* Equating a **subshell** `(cd /tmp; ...)` with changing the parent shell’s directory.
* Assuming **glob** failure always errors — unmatched globs may stay literal depending on options.

## 🔗 Related [#-related]

* [variables](/docs/bash/variables)
* [quoting](/docs/bash/quoting)
* [pipes\_redirection](/docs/bash/pipes-redirection)
* [arrays](/docs/bash/arrays)
* [functions](/docs/bash/functions)
* [exit\_codes](/docs/bash/exit-codes)


# Hello World (/docs/bash/hello-world)



# Hello World [#hello-world]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash Hello World prints a line to the terminal with `echo` (or `printf`). It confirms you can run commands and, optionally, execute a script file.

## 🔧 Core concepts [#-core-concepts]

| Piece          | Role                                    |
| -------------- | --------------------------------------- |
| `echo`         | Print arguments followed by a newline   |
| `printf`       | Formatted print (more predictable)      |
| Shebang        | Selects the interpreter for scripts     |
| `./file`       | Run a file in the current directory     |
| `bash file.sh` | Run a script without the executable bit |

Prefer `printf` when you care about exact formatting; `echo` is fine for learning.

## 💡 Examples [#-examples]

**Interactive:**

```shellscript
echo "Hello, World!"
printf '%s\n' "Hello, World!"
```

**Script file:**

```shellscript
#!/usr/bin/env bash
echo "Hello, World!"
```

```shellscript
bash hello.sh
```

**With a variable:**

```shellscript
#!/usr/bin/env bash
name="Ada"
echo "Hello, ${name}!"
```

**Show command success:**

```shellscript
echo "Hello, World!"
echo "exit status was $?"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `echo $name` without quotes breaks on spaces — prefer `"$name"`.
* Some `echo` flags differ across systems; `printf` is more portable.
* Running `sh hello.sh` may not be Bash if `sh` is dash.
* CRLF line endings from Windows editors can break shebang scripts.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/bash/getting-started)
* [navigation.md](/docs/bash/navigation)
* [variables.md](/docs/bash/variables)
* [shebang.md](/docs/bash/shebang)


# Bash (/docs/bash)



# Bash [#bash]

Shell scripting essentials.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Loops (/docs/bash/loops)



# Loops [#loops]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash offers `for`, `while`, `until`, and C-style `for (( ))`. Prefer iterating arrays or null-delimited streams over unquoted globs. Use `break` / `continue` to control flow; avoid parsing `ls`.

## 🔧 Core concepts [#-core-concepts]

| Loop                        | Typical use             |
| --------------------------- | ----------------------- |
| `for x in list; do …; done` | Fixed word list / array |
| `for ((i=0; i<n; i++)); do` | Numeric index           |
| `while cmd; do …; done`     | Until command fails     |
| `until cmd; do …; done`     | Until command succeeds  |
| `select`                    | Simple menus            |
| `break` / `continue`        | Exit / skip iteration   |
| `break n` / `continue n`    | Nested levels           |

Read lines safely with `while IFS= read -r line` (and `-d ''` for NUL). Process substitution or pipes run the loop in a subshell unless you use lastpipe / redirect.

## 💡 Examples [#-examples]

**Array and C-style:**

```shellscript
files=(*.txt)
for f in "${files[@]}"; do
  echo "file: $f"
done

for ((i = 0; i < 5; i++)); do
  echo "$i"
done
```

**Read file line by line:**

```shellscript
while IFS= read -r line || [[ -n "$line" ]]; do
  printf '%s\n' "$line"
done < "$input"
```

**Find with NUL (safe for spaces):**

```shellscript
while IFS= read -r -d '' path; do
  echo "$path"
done < <(find . -type f -print0)
```

**While with counter:**

```shellscript
n=0
while (( n < 3 )); do
  ((n++)) || true
  echo "$n"
done
```

## ⚠️ Pitfalls [#️-pitfalls]

* `for f in $(ls)` breaks on spaces/newlines—use globs or `find -print0`.
* Pipeline `cmd | while read` runs `while` in a subshell; variables won’t persist.
* Unquoted `for f in $list` word-splits; use arrays: `"$\{arr[@]\}"`.
* `for f in *.txt` leaves literal `*.txt` if no match unless `nullglob` is set.
* `((n++))` returns status 1 when expression is 0—watch with `set -e`.
* Infinite loops: ensure the condition or `break` can fire.

## 🔗 Related [#-related]

* [arrays.md](/docs/bash/arrays)
* [globbing.md](/docs/bash/globbing)
* [conditionals.md](/docs/bash/conditionals)
* [pipes\_redirection.md](/docs/bash/pipes-redirection)
* [subshells.md](/docs/bash/subshells)


# Navigation (/docs/bash/navigation)



# Navigation [#navigation]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Navigation means moving around the filesystem from the terminal: knowing where you are, listing contents, and changing directories. These commands are the foundation of everyday shell use.

## 🔧 Core concepts [#-core-concepts]

| Command    | Purpose                       |
| ---------- | ----------------------------- |
| `pwd`      | Print working directory       |
| `ls`       | List files and folders        |
| `cd`       | Change directory              |
| `~`        | Home directory                |
| `.` / `..` | Current / parent directory    |
| `/`        | Root of the filesystem (Unix) |

Paths can be **absolute** (`/home/sam/docs`) or **relative** (`./src`, `../other`).

## 💡 Examples [#-examples]

**Orient yourself:**

```shellscript
pwd
ls
ls -la
```

**Move around:**

```shellscript
cd ~
pwd
cd /tmp
pwd
cd -
pwd   # back to previous directory
```

**Relative paths:**

```shellscript
mkdir -p practice/sub
cd practice
pwd
cd sub
pwd
cd ..
ls
```

**Useful shortcuts:**

```shellscript
cd            # goes to $HOME
cd ~/Downloads
ls -lh        # human-readable sizes
```

## ⚠️ Pitfalls [#️-pitfalls]

* `cd` into a file fails; `cd` needs a directory.
* Unquoted spaces: `cd My Projects` → `cd "My Projects"`.
* `ls` output alone does not show hidden files — use `ls -a`.
* On Windows Git Bash, `C:` appears under `/c/` — not as `C:\`.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/bash/getting-started)
* [hello\_world.md](/docs/bash/hello-world)
* [permissions\_basics.md](/docs/bash/permissions-basics)
* [environment\_basics.md](/docs/bash/environment-basics)


# Permissions Basics (/docs/bash/permissions-basics)



# Permissions Basics [#permissions-basics]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Unix files have permission bits controlling who can read, write, or execute them. Understanding `ls -l`, `chmod`, and ownership prevents “Permission denied” confusion.

## 🔧 Core concepts [#-core-concepts]

| Symbol               | Meaning                              |
| -------------------- | ------------------------------------ |
| `r`                  | Read                                 |
| `w`                  | Write                                |
| `x`                  | Execute (run file / enter directory) |
| User / Group / Other | Three permission triples             |
| `chmod`              | Change mode bits                     |
| `chown`              | Change owner (often needs admin)     |

Example `ls -l` mode: `-rwxr-xr--` → file; owner `rwx`, group `r-x`, others `r--`.

## 💡 Examples [#-examples]

**Inspect permissions:**

```shellscript
ls -l hello.sh
# -rw-r--r-- 1 sam sam 40 Jul 10 09:00 hello.sh
```

**Make a script executable:**

```shellscript
chmod +x hello.sh
ls -l hello.sh
./hello.sh
```

**Numeric modes (common):**

```shellscript
chmod 644 notes.txt   # rw-r--r--
chmod 755 script.sh   # rwxr-xr-x
chmod 600 secret.env  # rw-------
```

**Directories need execute to enter:**

```shellscript
mkdir private
chmod 700 private
cd private
pwd
```

## ⚠️ Pitfalls [#️-pitfalls]

* Execute bit on a directory means “traverse,” not “run like a program.”
* `chmod -R` is powerful — easy to lock yourself out of a tree.
* Scripts need both read and execute for `./script`; `bash script` only needs read.
* On Windows filesystems mounted in WSL/Git Bash, permission bits may not behave like native Linux.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/bash/getting-started)
* [hello\_world.md](/docs/bash/hello-world)
* [navigation.md](/docs/bash/navigation)
* [environment\_basics.md](/docs/bash/environment-basics)


# Pipes & Redirection (/docs/bash/pipes-redirection)



# Pipes & Redirection [#pipes--redirection]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Redirection connects command stdin/stdout/stderr to files or other FDs. Pipes (`|`) connect stdout of one process to stdin of the next. Master these to build reliable pipelines and capture errors separately.

## 🔧 Core concepts [#-core-concepts]

| Operator           | Meaning                  |                    |
| ------------------ | ------------------------ | ------------------ |
| `>`                | Truncate/write stdout    |                    |
| `>>`               | Append stdout            |                    |
| `2>` / `2>>`       | stderr                   |                    |
| `&>` / `&>>`       | stdout+stderr (bash)     |                    |
| `>` / `2>&1`       | Merge stderr into stdout |                    |
| `&lt;`             | stdin from file          |                    |
| `&lt;<EOF`         | Here-document            |                    |
| `&lt;&lt;&lt;"$s"` | Here-string              |                    |
| `\|`               | Pipe stdout → next stdin |                    |
| \`                 | &\`                      | Pipe stdout+stderr |
| `n>&m`             | Dup FD n to m            |                    |
| `/dev/null`        | Discard                  |                    |

FD 0 stdin, 1 stdout, 2 stderr. Order matters: `cmd >out 2>&1` merges both into `out`; `cmd 2>&1 >out` leaves stderr on the terminal.

## 💡 Examples [#-examples]

**Capture and merge:**

```shellscript
make >build.log 2>&1
make 2>&1 | tee build.log
curl -fsS "$url" -o file || echo "failed" >&2
```

**Here-doc and here-string:**

```shellscript
ssh host bash <<'EOF'
  hostname
  uptime
EOF

grep -F <<<"$needle" file.txt
```

**Swap / silence:**

```shellscript
cmd 2>/dev/null
cmd >/dev/null 2>&1
cmd 3>&1 1>&2 2>&3 3>&-    # swap stdout/stderr (classic trick)
```

**Process with pipefail:**

```shellscript
set -o pipefail
curl -fsS "$url" | jq '.id'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Without `pipefail`, pipeline status is the last command only—failures earlier are hidden.
* `>` overwrites silently; prefer `set -o noclobber` (`>|` to force) for safety.
* `cmd > file 2>&1` vs `cmd 2>&1 > file`—order changes which FD lands where.
* Pipes introduce subshells; side effects (vars, `cd`) don’t affect the parent.
* Here-docs without quotes expand variables; use `&lt;&lt;'EOF'` for literals.
* Large pipes buffer; for huge data consider temp files or streaming tools.

## 🔗 Related [#-related]

* [exit\_codes.md](/docs/bash/exit-codes)
* [process\_substitution.md](/docs/bash/process-substitution)
* [subshells.md](/docs/bash/subshells)
* [debugging.md](/docs/bash/debugging)
* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)


# Process Substitution (/docs/bash/process-substitution)



# Process Substitution [#process-substitution]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Process substitution (`&lt;(…)` and `>(…)`) exposes a command’s output or input as a temporary filename (usually `/dev/fd/N`). It lets commands that expect files work with streams—and avoids pipeline subshell issues when reading into the current shell.

## 🔧 Core concepts [#-core-concepts]

| Form             | Meaning                                       |
| ---------------- | --------------------------------------------- |
| `&lt;(cmd)`      | Read from `cmd`’s stdout as a file            |
| `>(cmd)`         | Write to a file that pipes into `cmd`’s stdin |
| Diff two streams | `diff &lt;(cmd1) &lt;(cmd2)`                  |
| vs pipe          | Pipe connects stdin; process sub gives a path |

Requires bash/zsh/ksh support and `/dev/fd` (or named temps). Not POSIX `sh`.

## 💡 Examples [#-examples]

**Compare outputs:**

```shellscript
diff -u <(sort a.txt) <(sort b.txt)
comm <(ls dir1) <(ls dir2)
```

**Read in current shell:**

```shellscript
while IFS= read -r line; do
  echo "$line"
done < <(curl -fsS "$url")
```

**Multiple inputs:**

```shellscript
paste <(cut -f1 data.tsv) <(cut -f2 data.tsv)
```

**Tee-like with >():**

```shellscript
echo hello > >(tee saved.txt)
# or
cmd | tee >(sha256sum >&2) > out.bin
```

**mapfile:**

```shellscript
mapfile -t lines < <(grep -v '^#' config)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Not available in POSIX `sh` or some restricted environments.
* The path is ephemeral; don’t store it for later use after the command ends.
* `&lt;(cmd)` runs asynchronously; ensure consumers read fully.
* Combining with `sudo` may break `/dev/fd` visibility—run the whole pipeline elevated carefully.
* Prefer process substitution over `cmd >tmp && use tmp` for cleanliness, but temp files still win for huge reusable data.
* Quoting: `"&lt;(cmd)"` becomes a literal—don’t quote the substitution form.

## 🔗 Related [#-related]

* [pipes\_redirection.md](/docs/bash/pipes-redirection)
* [subshells.md](/docs/bash/subshells)
* [loops.md](/docs/bash/loops)
* [debugging.md](/docs/bash/debugging)
* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)


# Quoting (/docs/bash/quoting)



# Quoting [#quoting]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Quoting controls word-splitting, globbing, and expansion. Double quotes allow `$`, `` ` ``, and `\` escapes; single quotes are literal; `$''` enables ANSI-C escapes. Correct quoting prevents most bash bugs.

## 🔧 Core concepts [#-core-concepts]

| Form                | Behavior                                          |
| ------------------- | ------------------------------------------------- |
| `"..."`             | Expand `$var`, `$(...)`, `` `...` ``; keep spaces |
| `'...'`             | Fully literal (no expansions)                     |
| `$'...'`            | ANSI-C: `\n`, `\t`, `\xHH`, `\uXXXX`              |
| `$"..."`            | Locale translation (gettext)                      |
| `\`                 | Escape next character outside quotes              |
| `$'...'` vs `"..."` | Prefer `$'\n'` for real newlines in strings       |

Word-splitting uses `IFS` (default space/tab/newline) on unquoted expansions. Globbing (`*`, `?`, `[]`) also applies only when unquoted.

## 💡 Examples [#-examples]

**Preserve spaces:**

```shellscript
file="my document.txt"
rm -- "$file"          # good
# rm -- $file          # bad: two words
```

**Literal vs expanded:**

```shellscript
echo 'Home is $HOME'   # Home is $HOME
echo "Home is $HOME"   # Home is /home/you
```

**ANSI-C quotes:**

```shellscript
printf '%s\n' $'line1\nline2'
path=$'C:\\Users\\name'   # backslashes as written
```

**Nested / mixed:**

```shellscript
sql="SELECT * FROM users WHERE name='${name//\'/\'\'}'"
msg="He said \"hello\""
```

**Here-docs:**

```shellscript
cat <<'EOF'
No expansion: $HOME stays literal
EOF

cat <<EOF
Expanded: $HOME
EOF
```

## ⚠️ Pitfalls [#️-pitfalls]

* `"$@"` keeps args separate; `"$*"` joins with first IFS char.
* Empty `"$var"` is one empty argument; unquoted `$var` vanishes.
* Globs inside quotes are literal: `"*.txt"` is not a pattern.
* Backticks nest poorly; prefer `$(...)`.
* JSON/YAML in scripts: prefer single quotes or heredocs to avoid escape hell.
* `echo` + escapes is non-portable; use `printf`.

## 🔗 Related [#-related]

* [variables.md](/docs/bash/variables)
* [globbing.md](/docs/bash/globbing)
* [string\_ops.md](/docs/bash/string-ops)
* [arrays.md](/docs/bash/arrays)
* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)


# Scripts Best Practices (/docs/bash/scripts-best-practices)



# Scripts Best Practices [#scripts-best-practices]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Reliable bash scripts start with a clear shebang, strict mode, quoted expansions, and explicit error handling. Treat bash as glue: keep logic simple, prefer well-tested tools, and fail fast with useful messages.

## 🔧 Core concepts [#-core-concepts]

| Practice                | Why                        |
| ----------------------- | -------------------------- |
| `#!/usr/bin/env bash`   | Portable interpreter       |
| `set -euo pipefail`     | Fail on error/unset/pipe   |
| `IFS=$'\n\t'`           | Safer splitting (optional) |
| Quote `"$var"` / `"$@"` | Avoid splitting/globbing   |
| `local` in functions    | No global leaks            |
| Check deps              | `command -v`               |
| Prefer arrays           | Lists with spaces          |
| ShellCheck              | Static analysis            |

Structure: constants → functions → `main "$@"` at the bottom. Log to stderr; keep stdout for data.

## 💡 Examples [#-examples]

**Skeleton:**

```shellscript
#!/usr/bin/env bash
set -euo pipefail

log() { printf '%s\n' "$*" >&2; }
die() { log "$*"; exit 1; }

need() { command -v "$1" >/dev/null || die "missing: $1"; }

main() {
  need jq
  [[ $# -ge 1 ]] || die "usage: $0 <file>"
  local file=$1
  [[ -f "$file" ]] || die "not a file: $file"
  jq . <"$file"
}

main "$@"
```

**Safe temp files:**

```shellscript
tmp="$(mktemp)"
trap 'rm -f "$tmp"' EXIT
```

**Dry-run pattern:**

```shellscript
run() {
  if [[ "${DRY_RUN:-}" == 1 ]]; then
    log "DRY: $*"
  else
    "$@"
  fi
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Blind `set -e` without understanding exceptions in `if` / `&&` chains.
* Parsing `ls`, `ps`, or word-splitting filenames.
* Hard-coding `/bin/bash` when `env` is more portable.
* Silent failures: always surface errors with context.
* Running as root by default—drop privileges when possible.
* Skipping ShellCheck (`shellcheck script.sh`) in CI.

## 🔗 Related [#-related]

* [shebang.md](/docs/bash/shebang)
* [debugging.md](/docs/bash/debugging)
* [exit\_codes.md](/docs/bash/exit-codes)
* [quoting.md](/docs/bash/quoting)
* [functions.md](/docs/bash/functions)
* [getopts.md](/docs/bash/getopts)


# Shebang (/docs/bash/shebang)



# Shebang [#shebang]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The shebang (`#!`) is the first line of a script. It tells the kernel which interpreter to run. Prefer `#!/usr/bin/env bash` so the script finds `bash` on `PATH` across systems.

## 🔧 Core concepts [#-core-concepts]

| Form                     | Meaning                            |
| ------------------------ | ---------------------------------- |
| `#!/bin/bash`            | Hard-coded path to bash            |
| `#!/usr/bin/env bash`    | Resolve bash via `PATH` (portable) |
| `#!/bin/sh`              | POSIX `sh` (often dash on Debian)  |
| `#!/usr/bin/env python3` | Same pattern for other languages   |

Requirements: shebang must be line 1, no BOM, Unix line endings (`LF`). The file needs execute permission (`chmod +x`). Options after the interpreter (e.g. `#!/usr/bin/env bash -e`) are not portable with `env` on all systems—set options inside the script instead.

## 💡 Examples [#-examples]

**Portable bash script:**

```shellscript
#!/usr/bin/env bash
set -euo pipefail

echo "Running under: $BASH_VERSION"
```

**Make executable and run:**

```shellscript
chmod +x ./deploy.sh
./deploy.sh          # uses shebang
bash ./deploy.sh     # ignores shebang; forces bash
```

**Detect interpreter:**

```shellscript
head -n1 "$0"        # show shebang of current script
readlink -f "$(command -v bash)"
```

**Avoid:**

```shellscript
#!/usr/bin/env bash -e   # often broken: env treats "-e" as a program name
```

Use `set -e` in the body instead.

## ⚠️ Pitfalls [#️-pitfalls]

* Windows editors may save `CRLF`; the kernel then looks for `/usr/bin/env bash\r` and fails.
* `#!/bin/bash` breaks on systems where bash lives elsewhere (e.g. some BSDs, Nix).
* Running with `sh script.sh` forces POSIX `sh` and ignores bashisms even if the shebang says bash.
* `env` may not pass flags; put `set -o` / `set -euo pipefail` after the shebang.
* Scripts without a shebang inherit the caller’s shell when run as `./script` only if the kernel allows—always include one.

## 🔗 Related [#-related]

* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [debugging.md](/docs/bash/debugging)
* [exit\_codes.md](/docs/bash/exit-codes)
* [variables.md](/docs/bash/variables)


# SSH (/docs/bash/ssh)



# SSH [#ssh]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

SSH authenticates and encrypts remote shell access. Day-to-day work uses keys, `~/.ssh/config` host aliases, agent forwarding (carefully), and non-interactive remote commands. Prefer key-based auth over passwords for scripts and automation.

## 🔧 Core concepts [#-core-concepts]

| Piece                           | Role                  |
| ------------------------------- | --------------------- |
| `ssh user@host`                 | Interactive session   |
| `ssh host 'cmd'`                | Remote command        |
| `scp` / `sftp` / `rsync -e ssh` | File transfer         |
| `ssh-keygen`                    | Create key pair       |
| `ssh-copy-id`                   | Install public key    |
| `ssh-agent` / `ssh-add`         | Unlock keys in memory |
| `~/.ssh/config`                 | Per-host settings     |
| `ProxyJump`                     | Bastion / jump host   |

Common config keys: `Host`, `HostName`, `User`, `IdentityFile`, `Port`, `ForwardAgent`, `LocalForward`, `ServerAliveInterval`.

## 💡 Examples [#-examples]

**Config aliases:**

```ssh-config
Host prod
  HostName 203.0.113.10
  User deploy
  IdentityFile ~/.ssh/id_ed25519_prod
  IdentitiesOnly yes

Host app
  HostName 10.0.0.5
  User ubuntu
  ProxyJump prod
```

**Keys and remote cmd:**

```shellscript
ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/id_ed25519
ssh-copy-id -i ~/.ssh/id_ed25519.pub prod
ssh prod 'hostname; uptime'
```

**Rsync and tunnels:**

```shellscript
rsync -avz -e ssh ./dist/ prod:/var/www/app/
ssh -L 5432:localhost:5432 prod   # local port forward
ssh -N -D 1080 prod               # SOCKS dynamic forward
```

**Batch / CI style:**

```shellscript
ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new prod 'systemctl status app'
```

## ⚠️ Pitfalls [#️-pitfalls]

* `ForwardAgent yes` exposes your keys to the remote—use only on trusted hosts.
* Wrong file permissions: `~/.ssh` should be `700`, private keys `600`.
* Host key changes: verify MITM vs legitimate rebuild before deleting `known_hosts` entries.
* Interactive prompts break CI—use `BatchMode=yes` and deployed keys.
* Don’t embed private keys in repos; use secrets managers / SSH deploy keys.
* `scp` is dated; prefer `rsync` or `sftp` for robust transfers.

## 🔗 Related [#-related]

* [scripts\_best\_practices.md](/docs/bash/scripts-best-practices)
* [cron.md](/docs/bash/cron)
* [pipes\_redirection.md](/docs/bash/pipes-redirection)
* [debugging.md](/docs/bash/debugging)
* [exit\_codes.md](/docs/bash/exit-codes)


# String Operations (/docs/bash/string-ops)



# String Operations [#string-operations]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash can slice and transform strings with parameter expansion—no external `sed` required for common cases. Patterns use glob rules (or regex with `=~`). Prefer expansions for portability within bash; use `printf` for formatting.

## 🔧 Core concepts [#-core-concepts]

| Expansion                    | Result                         |
| ---------------------------- | ------------------------------ |
| `$\{#s\}`                    | Length                         |
| `$\{s:offset\}`              | Slice from offset              |
| `$\{s:offset:len\}`          | Slice with length              |
| `$\{s#pat\}` / `$\{s##pat\}` | Remove shortest/longest prefix |
| `$\{s%pat\}` / `$\{s%%pat\}` | Remove shortest/longest suffix |
| `$\{s/pat/rep\}`             | Replace first match            |
| `$\{s//pat/rep\}`            | Replace all                    |
| `$\{s/#pat/rep\}`            | Replace prefix                 |
| `$\{s/%pat/rep\}`            | Replace suffix                 |
| `$\{s,,\}` / `$\{s^^\}`      | Lower / upper (bash 4+)        |
| `$\{s:0:1\}`                 | First character                |

Negative offsets count from end: `$\{s: -3\}` (space required after `:`).

## 💡 Examples [#-examples]

**Paths and extensions:**

```shellscript
path="/var/log/app.tar.gz"
echo "${path##*/}"      # app.tar.gz
echo "${path%/*}"       # /var/log
echo "${path%%.*}"      # /var/log/app
echo "${path%.*}"       # /var/log/app.tar
```

**Replace and case:**

```shellscript
s="Hello World"
echo "${s// /_}"        # Hello_World
echo "${s,,}"           # hello world
echo "${s^^}"           # HELLO WORLD
```

**Default padding with printf:**

```shellscript
printf '%04d\n' 42      # 0042
printf '%s\n' "${name:-anonymous}"
```

**Trim whitespace (extglob):**

```shellscript
shopt -s extglob
x="  hi  "
x="${x##+([[:space:]])}"
x="${x%%+([[:space:]])}"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Patterns are globs, not regex (`*` vs `.*`).
* `$\{s: -1\}` needs the space; `$\{s:-1\}` is a default-value expansion.
* Unicode: length/offsets are in characters for bash 4+ locales, but be careful with combining marks.
* Heavy parsing: use `awk`/`sed`/`python` for complex text.
* Quoting: `"$\{s\}"` still required when expanding results into commands.
* Associative replace with `/` in pattern: escape or choose another approach.

## 🔗 Related [#-related]

* [variables.md](/docs/bash/variables)
* [quoting.md](/docs/bash/quoting)
* [arrays.md](/docs/bash/arrays)
* [conditionals.md](/docs/bash/conditionals)
* [globbing.md](/docs/bash/globbing)


# Subshells (/docs/bash/subshells)



# Subshells [#subshells]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A subshell is a child shell process. Changes to variables, `cd`, and shell options inside it do not affect the parent. Subshells appear with `(…)`, pipelines, command substitution `$(…)`, and process substitution contexts.

## 🔧 Core concepts [#-core-concepts]

| Construct               | Subshell?                                             |
| ----------------------- | ----------------------------------------------------- |
| `( cd /tmp && pwd )`    | Yes                                                   |
| `\{ cd /tmp && pwd; \}` | No (group command; needs trailing `;`)                |
| `$(cmd)` / `` `cmd` ``  | Yes                                                   |
| `cmd \| cmd`            | Each side may be (bash: last may not with `lastpipe`) |
| `coproc`                | Separate process                                      |
| Background `cmd &`      | Child process                                         |

Use subshells to isolate `cd`, temporary `umask`, or option changes. Use `\{ …; \}` when you need side effects in the current shell.

## 💡 Examples [#-examples]

**Isolate directory change:**

```shellscript
pwd
( cd /tmp && ls )
pwd   # unchanged
```

**Group vs subshell:**

```shellscript
{ echo a; echo b; } > both.txt     # current shell
( echo a; echo b ) > both.txt      # subshell (usually fine for I/O)
```

**Capture without polluting:**

```shellscript
version="$(
  cd "$repo" || exit 1
  git describe --tags
)"
```

**Avoid pipeline subshell for vars:**

```shellscript
# bad: count lost
# printf '%s\n' a b | while read -r x; do ((count++)); done

count=0
while read -r x; do ((count++)) || true; done < <(printf '%s\n' a b)
echo "$count"   # 2
```

## ⚠️ Pitfalls [#️-pitfalls]

* Variable assignments in pipelines often don’t persist—use process substitution or lastpipe.
* `(exit 1)` only exits the subshell; parent continues unless you check status.
* Nested subshells add process overhead; don’t overuse in tight loops.
* `cd` in scripts: prefer subshell or `pushd`/`popd` over relying on later `cd -`.
* Functions defined in a subshell vanish when it ends.
* `export` inside subshell does not affect parent environment.

## 🔗 Related [#-related]

* [process\_substitution.md](/docs/bash/process-substitution)
* [pipes\_redirection.md](/docs/bash/pipes-redirection)
* [variables.md](/docs/bash/variables)
* [loops.md](/docs/bash/loops)
* [functions.md](/docs/bash/functions)


# Variables (/docs/bash/variables)



# Variables [#variables]

*Bash · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash variables hold strings (and, with care, integers/arrays). Assignment has no spaces: `name=value`. Expand with `$name` or `$\{name\}`. Prefer quoting expansions to avoid word-splitting and globbing.

## 🔧 Core concepts [#-core-concepts]

| Syntax                     | Meaning                            |
| -------------------------- | ---------------------------------- |
| `var=value`                | Assign (no spaces around `=`)      |
| `$var` / `$\{var\}`        | Expand                             |
| `$\{var:-default\}`        | Default if unset or empty          |
| `$\{var:=default\}`        | Assign default if unset/empty      |
| `$\{var:?err\}`            | Error if unset/empty               |
| `$\{var:+alt\}`            | Expand `alt` if set and non-empty  |
| `readonly VAR=1`           | Immutable                          |
| `local x=1`                | Function-scoped (inside functions) |
| `export VAR=1`             | Pass to child processes            |
| `declare -i n=0`           | Integer attribute                  |
| `declare -r` / `-a` / `-A` | Readonly / indexed / associative   |

Special: `$0` script name, `$1`…`$n` args, `$#` count, `$@` / `$*` all args, `$?` last exit, `$$` PID, `$!` last background PID, `$_` last arg of previous command.

## 💡 Examples [#-examples]

**Basics and defaults:**

```shellscript
name="Ada"
echo "Hello, ${name}"
port="${PORT:-8080}"
: "${API_KEY:?API_KEY is required}"
```

**Export and env:**

```shellscript
export DATABASE_URL="postgres://localhost/app"
env | grep DATABASE
printenv DATABASE_URL
```

**Arithmetic:**

```shellscript
declare -i count=0
count+=1
((count++))
echo $((count * 2))
```

**Safe empty check:**

```shellscript
if [[ -z "${var:-}" ]]; then
  echo "unset or empty"
fi
```

## ⚠️ Pitfalls [#️-pitfalls]

* `var = value` runs command `var` (spaces break assignment).
* Unquoted `$var` splits on `IFS` and expands globs.
* `$1` vs `"$1"`: always quote unless you intentionally want splitting.
* `$*` vs `$@`: use `"$@"` to preserve argument boundaries.
* Environment variables are always strings; `(( ))` / `declare -i` for math.
* `local` only works inside functions; using it at top level errors.

## 🔗 Related [#-related]

* [quoting.md](/docs/bash/quoting)
* [arrays.md](/docs/bash/arrays)
* [string\_ops.md](/docs/bash/string-ops)
* [functions.md](/docs/bash/functions)
* [conditionals.md](/docs/bash/conditionals)


# Express vs Fastify (/docs/comparisons/express-vs-fastify)



# Express vs Fastify [#express-vs-fastify]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Express** is the ubiquitous minimalist Node framework. **Fastify** emphasizes performance, schema validation, and plugin encapsulation. Both are excellent — pick based on team needs and ecosystem.

## 🔧 Core concepts [#-core-concepts]

| Dimension      | Express              | Fastify                         |
| -------------- | -------------------- | ------------------------------- |
| Habit / hiring | Extremely common     | Growing, strong for APIs        |
| Validation     | DIY / middleware     | JSON Schema first-class         |
| Plugin model   | Middleware + routers | Encapsulated plugins            |
| Perf           | Good                 | Typically faster out of box     |
| TypeScript     | Manual/community     | Strong schema → types workflows |
| Ecosystem      | Largest              | Smaller but solid               |

**When to use Express:** existing Express apps, max middleware compatibility, simplest tutorials/hiring.

**When to use Fastify:** new JSON APIs wanting schemas, logging, and encapsulation by default.

## 💡 Examples [#-examples]

**Express:**

```js
import express from "express";
const app = express();
app.use(express.json());
app.post("/users", (req, res) => res.status(201).json(req.body));
app.listen(9000);
```

**Fastify:**

```js
import Fastify from "fastify";
const app = Fastify({ logger: true });
app.post(
  "/users",
  { schema: { body: { type: "object", required: ["email"], properties: { email: { type: "string" } } } } },
  async (req, reply) => {
    reply.code(201);
    return req.body;
  },
);
await app.listen({ port: 9000, host: "0.0.0.0" });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Porting middleware 1:1 often fails — Fastify hooks ≠ Express middleware.
* Express async errors need wrappers (v4); don't assume parity with Fastify's async handling.
* “Faster” rarely matters until measured — schema safety often matters more.

## 🔗 Related [#-related]

* [Node/express\_basics.md](/docs/comparisons/../node/express-basics)
* [Node/fastify\_basics.md](/docs/comparisons/../node/fastify-basics)
* [README.md](/docs/comparisons)


# fetch vs axios (/docs/comparisons/fetch-vs-axios)



# fetch vs axios [#fetch-vs-axios]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**fetch** is the web-standard HTTP client (also in Node 18+). **axios** is a popular library with richer ergonomics (interceptors, automatic JSON, better older-browser story historically).

## 🔧 Core concepts [#-core-concepts]

| Dimension       | fetch                                | axios                         |
| --------------- | ------------------------------------ | ----------------------------- |
| Availability    | Built-in                             | `npm install axios`           |
| JSON body       | Manual `res.json()`                  | Auto-parsed `response.data`   |
| HTTP errors     | Only network fail rejects; 404 is OK | Rejects on non-2xx by default |
| Interceptors    | DIY wrappers                         | First-class                   |
| Upload progress | Limited                              | Easier (`onUploadProgress`)   |
| Timeouts        | `AbortController`                    | `timeout` option              |

**When to use fetch:** browser-native, Next.js/edge, zero deps, Request/Response compatibility.

**When to use axios:** interceptors, uniform error handling, upload progress, large existing axios codebases.

## 💡 Examples [#-examples]

**fetch:**

```js
const res = await fetch("/api/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ada" }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
```

**axios:**

```js
import axios from "axios";

const { data } = await axios.post("/api/users", { name: "Ada" });
```

## ⚠️ Pitfalls [#️-pitfalls]

* fetch does not throw on 404/500 — always check `res.ok`.
* axios throws — wrap in try/catch or check `validateStatus`.
* Credentials/cookies: fetch needs `credentials: 'include'`; axios uses `withCredentials`.

## 🔗 Related [#-related]

* [Javascript/fetch.md](/docs/comparisons/../javascript/fetch)
* [Node/getting\_started.md](/docs/comparisons/../node/getting-started)
* [README.md](/docs/comparisons)


# Comparisons (/docs/comparisons)



# Comparisons [#comparisons]

A vs B trade-offs.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Pages Router vs App Router (/docs/comparisons/pages-vs-app-router)



# Pages Router vs App Router [#pages-router-vs-app-router]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Next.js **Pages Router** (`pages/`) is the original model. **App Router** (`app/`) is the modern default with Server Components, nested layouts, and richer caching controls. New projects should prefer App Router unless constrained.

## 🔧 Core concepts [#-core-concepts]

| Dimension          | Pages Router                            | App Router                              |
| ------------------ | --------------------------------------- | --------------------------------------- |
| Directory          | `pages/`                                | `app/`                                  |
| Default components | Client-centric pages                    | Server Components                       |
| Data fetching      | `getServerSideProps` / `getStaticProps` | async server components / `fetch` cache |
| API routes         | `pages/api/*`                           | `app/**/route.ts`                       |
| Layouts            | `_app` + manual                         | Nested `layout.tsx`                     |
| Metadata           | `next/head` / `Head`                    | `metadata` / `generateMetadata`         |

**When to use App Router:** new apps, RSC, nested layouts, modern Next features.

**When to use Pages Router:** large legacy codebases, libraries that assume Pages only, gradual migration.

## 💡 Examples [#-examples]

**Pages:**

```tsx
export async function getServerSideProps() {
  return { props: { t: Date.now() } };
}
export default function Page({ t }: { t: number }) {
  return <p>{t}</p>;
}
```

**App:**

```tsx
export default async function Page() {
  const t = Date.now();
  return <p>{t}</p>;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing both routers works but doubles mental models — document boundaries.
* Hooks require `'use client'` in App Router — easy to forget.
* Caching defaults in App Router surprise Pages veterans — learn `no-store` / revalidate.

## 🔗 Related [#-related]

* [Next.js/app\_router.md](/docs/comparisons/../next.js/app-router)
* [Next.js/pages\_router.md](/docs/comparisons/../next.js/pages-router)
* [Next.js/server\_components.md](/docs/comparisons/../next.js/server-components)
* [README.md](/docs/comparisons)


# pathlib vs os.path (/docs/comparisons/pathlib-vs-os)



# pathlib vs os.path [#pathlib-vs-ospath]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Choose **pathlib** for most new Python path logic (object-oriented, readable). Use **os.path** / `os` when maintaining legacy code or needing specific `os` side effects (cwd, env, process).

## 🔧 Core concepts [#-core-concepts]

| Dimension      | pathlib                    | os / os.path                 |
| -------------- | -------------------------- | ---------------------------- |
| Style          | Objects (`Path`)           | Strings                      |
| Join           | `/` operator, `joinpath`   | `os.path.join`               |
| Exists / mkdir | `path.exists()`, `mkdir()` | `os.path.exists`, `os.mkdir` |
| Glob           | `path.glob` / `rglob`      | `glob.glob`                  |
| Read/write     | `read_text` / `write_text` | open + join paths            |
| Best for       | New code, clarity          | Legacy, thin wrappers        |

**When to use pathlib:** new scripts, apps, anything that manipulates many paths.

**When to use os.path:** drop-in maintenance, or APIs that already require strings and `os.*` process calls.

## 💡 Examples [#-examples]

**pathlib:**

```python
from pathlib import Path

root = Path.cwd() / "data"
root.mkdir(parents=True, exist_ok=True)
for p in root.glob("*.csv"):
    print(p.read_text(encoding="utf-8")[:80])
```

**os.path:**

```python
import os

root = os.path.join(os.getcwd(), "data")
os.makedirs(root, exist_ok=True)
for name in os.listdir(root):
    if name.endswith(".csv"):
        path = os.path.join(root, name)
        with open(path, encoding="utf-8") as f:
            print(f.read(80))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing `Path` and strings casually works often (`os.fspath`) but be consistent at API boundaries.
* `Path` on Windows vs POSIX differs for anchors — test both if you ship cross-platform.
* `os.path` won't stop you from forgetting `exist_ok` / parents the way pathlib habits encourage.

## 🔗 Related [#-related]

* [Python/os.md](/docs/comparisons/../python/os) (if present)
* [Python/getting\_started.md](/docs/comparisons/../python/getting-started)
* [README.md](/docs/comparisons)


# pytest vs unittest (/docs/comparisons/pytest-vs-unittest)



# pytest vs unittest [#pytest-vs-unittest]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**pytest** is the common default for modern Python tests (fixtures, parametrize, assert rewriting). **unittest** is the stdlib xUnit-style framework — fine for stdlib-only environments and legacy suites.

## 🔧 Core concepts [#-core-concepts]

| Dimension   | pytest                     | unittest             |
| ----------- | -------------------------- | -------------------- |
| Install     | Third-party                | Stdlib               |
| Assertions  | Plain `assert`             | `self.assertEqual`…  |
| Fixtures    | Elegant `@pytest.fixture`  | `setUp` / `tearDown` |
| Parametrize | `@pytest.mark.parametrize` | More boilerplate     |
| Plugins     | Rich ecosystem             | Limited              |
| Discovery   | `test_*.py` conventions    | `unittest` discovery |

**When to use pytest:** almost all application and library projects.

**When to use unittest:** zero-dependency constraints, teaching stdlib, or extending large existing unittest suites.

## 💡 Examples [#-examples]

**pytest:**

```python
import pytest

@pytest.fixture
def n():
    return 2

@pytest.mark.parametrize("x,y", [(1, 2), (2, 4)])
def test_double(x, y, n):
    assert x * n == y
```

**unittest:**

```python
import unittest

class DoubleTest(unittest.TestCase):
    def test_double(self):
        self.assertEqual(2 * 2, 4)

if __name__ == "__main__":
    unittest.main()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing styles in one repo without guidance confuses contributors — pick a default.
* pytest plugin overload can obscure failures — keep conftest lean.
* unittest mock (`unittest.mock`) works great *with* pytest too.

## 🔗 Related [#-related]

* [Pytest/](../Pytest/)
* [Python/getting\_started.md](/docs/comparisons/../python/getting-started)
* [README.md](/docs/comparisons)


# Redis vs Postgres (/docs/comparisons/redis-vs-postgres)



# Redis vs Postgres [#redis-vs-postgres]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Postgres** is a durable relational system of record. **Redis** is an in-memory data structure server optimized for speed, caching, ephemeral state, and specialized structures. Often used together, not as mutual substitutes.

## 🔧 Core concepts [#-core-concepts]

| Dimension         | Redis                      | Postgres                         |
| ----------------- | -------------------------- | -------------------------------- |
| Primary store?    | Usually no (cache/session) | Yes (SoR)                        |
| Durability        | Optional RDB/AOF           | WAL + strong durability defaults |
| Query model       | Keys + data structures     | SQL + relational model           |
| Latency           | Sub-ms in-memory           | Low ms; disk-backed              |
| Relations / joins | DIY                        | First-class                      |
| Memory cost       | Entire working set in RAM  | Buffer cache + disk              |

**When to use Redis:** cache, rate limits, sessions, leaderboards, pub/sub, queues (or Streams).

**When to use Postgres:** authoritative business data, complex queries, transactions, constraints.

## 💡 Examples [#-examples]

**Redis cache aside:**

```shellscript
GET user:42
# miss → load from Postgres → SET user:42 … EX 300
```

**Postgres source of truth:**

```sql
SELECT id, email FROM users WHERE id = 42;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using Redis as the only database without HA/persistence for critical data.
* Caching without invalidation strategy serves stale Postgres data forever.
* Storing huge blobs in Redis blows RAM — keep hot, small keys.

## 🔗 Related [#-related]

* [Redis/getting\_started.md](/docs/comparisons/../redis/getting-started)
* [Postgres/getting\_started.md](/docs/comparisons/../postgres/getting-started)
* [Redis/expiry\_ttl.md](/docs/comparisons/../redis/expiry-ttl)
* [README.md](/docs/comparisons)


# Tailwind vs hand-written CSS (/docs/comparisons/tailwind-vs-css)



# Tailwind vs hand-written CSS [#tailwind-vs-hand-written-css]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Tailwind** accelerates UI via utility classes and a shared design scale. **Hand-written CSS** (or CSS Modules / plain stylesheets) offers full control and fewer markup classes. Many teams mix: Tailwind for app UI, custom CSS for complex animations or third-party overrides.

## 🔧 Core concepts [#-core-concepts]

| Dimension          | Tailwind                | Hand-written CSS            |
| ------------------ | ----------------------- | --------------------------- |
| Speed of iteration | Very fast for common UI | Slower unless well-factored |
| Bundle discipline  | Scans used classes      | Depends on your imports     |
| Readability        | Busy class strings      | Centralized selectors       |
| Design consistency | Theme tokens by default | You must enforce tokens     |
| Learning curve     | Utility vocabulary      | CSS cascade/specificity     |
| Dynamic theming    | Variants + CSS vars     | Full freedom                |

**When to use Tailwind:** product UIs, design systems with utility tokens, rapid component work.

**When to use CSS:** intricate animations, unique marketing layouts, existing CSS architecture, or teams that dislike utilities-in-markup.

## 💡 Examples [#-examples]

**Tailwind:**

```html
<button class="rounded-md bg-zinc-900 px-3 py-2 text-sm text-white hover:bg-zinc-700">
  Save
</button>
```

**CSS:**

```css
.button {
  border-radius: 0.375rem;
  background: #18181b;
  padding: 0.5rem 0.75rem;
  font-size: 0.875rem;
  color: white;
}
.button:hover {
  background: #3f3f46;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Tailwind without content paths generates empty CSS.
* Hand-written CSS without conventions recreates a one-off design system by accident.
* `@apply` everywhere reintroduces the problems utilities were meant to solve.

## 🔗 Related [#-related]

* [Tailwind/getting\_started.md](/docs/comparisons/../tailwind/getting-started)
* [CSS/](../CSS/)
* [README.md](/docs/comparisons)


# useEffect vs useLayoutEffect (/docs/comparisons/useeffect-vs-uselayouteffect)



# useEffect vs useLayoutEffect [#useeffect-vs-uselayouteffect]

*Comparisons · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Both React hooks run after render from side-effect logic. **useLayoutEffect** fires synchronously after DOM mutations before paint; **useEffect** fires after paint. Prefer `useEffect` unless you must measure/mutate DOM before the user sees a frame.

## 🔧 Core concepts [#-core-concepts]

| Dimension      | useEffect                     | useLayoutEffect                            |
| -------------- | ----------------------------- | ------------------------------------------ |
| Timing         | After paint                   | Before paint (sync)                        |
| Blocking       | Non-blocking paint            | Can delay paint                            |
| SSR            | OK (warns if misused)         | Warning on server — often gate             |
| Typical use    | Fetch, subscriptions, logging | DOM measure, scroll lock, tooltip position |
| Default choice | Yes                           | Only when needed                           |

**When to use useEffect:** data loading, event listeners, integrating non-React libs that can wait a frame.

**When to use useLayoutEffect:** avoid flicker when reading layout (`getBoundingClientRect`) and synchronously updating state/DOM.

## 💡 Examples [#-examples]

**useEffect (fetch):**

```tsx
useEffect(() => {
  let cancelled = false;
  fetch("/api").then(async (r) => {
    const data = await r.json();
    if (!cancelled) setData(data);
  });
  return () => {
    cancelled = true;
  };
}, []);
```

**useLayoutEffect (measure):**

```tsx
useLayoutEffect(() => {
  const rect = ref.current?.getBoundingClientRect();
  if (rect) setWidth(rect.width);
}, [deps]);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Putting heavy work in `useLayoutEffect` janks the UI.
* `useLayoutEffect` on the server warns — use `useEffect` or client-only components.
* Neither replaces data libraries (react-query) for complex fetching.

## 🔗 Related [#-related]

* [React/](../React/)
* [Next.js/server\_components.md](/docs/comparisons/../next.js/server-components)
* [README.md](/docs/comparisons)


# Docker Compose (/docs/docker/compose)



# Docker Compose [#docker-compose]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Compose defines multi-service stacks in YAML: web, db, redis, networks, and volumes with one `docker compose up`.

## 🔧 Core concepts [#-core-concepts]

| Key                        | Role                         |
| -------------------------- | ---------------------------- |
| `services`                 | Containers to run            |
| `images` / `build`         | Prebuilt vs local Dockerfile |
| `ports`                    | `host:container` publish     |
| `environment` / `env_file` | Config                       |
| `volumes`                  | Persist or share data        |
| `networks`                 | Service DNS names            |
| `depends_on`               | Start order (not readiness)  |

| Command                  | Purpose        |
| ------------------------ | -------------- |
| `docker compose up -d`   | Start detached |
| `docker compose down`    | Stop + remove  |
| `docker compose logs -f` | Follow logs    |
| `docker compose ps`      | Status         |

## 💡 Examples [#-examples]

**Minimal stack:**

```yaml
services:
  web:
    build: .
    ports:
      - "9000:9000"
    environment:
      DATABASE_URL: postgres://postgres:postgres@db:5432/app
    depends_on:
      - db
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: postgres
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
```

**Rebuild one service:**

```shellscript
docker compose up -d --build web
```

## ⚠️ Pitfalls [#️-pitfalls]

* `depends_on` does not wait for DB ready — use healthchecks + `condition: service_healthy`.
* Host `localhost` inside a container is the container itself — use service names (`db`).
* Old `docker-compose` (hyphen) CLI differs from `docker compose` plugin — prefer the plugin.

## 🔗 Related [#-related]

* [networks.md](/docs/docker/networks)
* [volumes.md](/docs/docker/volumes)
* [healthchecks.md](/docs/docker/healthchecks)
* [env\_secrets.md](/docs/docker/env-secrets)


# Dockerfile (/docs/docker/dockerfile)



# Dockerfile [#dockerfile]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A Dockerfile is a sequence of instructions that build an image layer by layer. Order matters for cache efficiency.

## 🔧 Core concepts [#-core-concepts]

| Instruction          | Role                             |
| -------------------- | -------------------------------- |
| `FROM`               | Base image                       |
| `WORKDIR`            | Set working directory            |
| `COPY` / `ADD`       | Add files (`COPY` preferred)     |
| `RUN`                | Execute build commands           |
| `ENV` / `ARG`        | Runtime env / build args         |
| `EXPOSE`             | Document port (does not publish) |
| `USER`               | Switch user                      |
| `CMD` / `ENTRYPOINT` | Default process                  |

| Cache tip            | Practice                                |
| -------------------- | --------------------------------------- |
| Copy lockfiles first | Reuse `npm ci` / `pip` layers           |
| Fewer layers         | Combine related `RUN`s when it helps    |
| `.dockerignore`      | Exclude `node_modules`, `.git`, secrets |

## 💡 Examples [#-examples]

**Node app sketch:**

```dockerfile
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
USER node
EXPOSE 9000
CMD ["node", "server.js"]
```

**Build args:**

```dockerfile
ARG NODE_ENV=production
ENV NODE_ENV=$NODE_ENV
```

**`.dockerignore`:**

```
node_modules
.git
.env
Dockerfile*
```

## ⚠️ Pitfalls [#️-pitfalls]

* `ADD` auto-extracts archives and can fetch URLs — surprising; prefer `COPY`.
* Secrets in `RUN` lines leak into image history — use BuildKit secret mounts.
* `CMD` vs `ENTRYPOINT` confusion: know exec-form JSON arrays vs shell form.

## 🔗 Related [#-related]

* [multi\_stage.md](/docs/docker/multi-stage)
* [images\_tags.md](/docs/docker/images-tags)
* [env\_secrets.md](/docs/docker/env-secrets)
* [getting\_started.md](/docs/docker/getting-started)


# Env & Secrets (/docs/docker/env-secrets)



# Env & Secrets [#env--secrets]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Pass configuration with environment variables and inject secrets without baking them into image layers. Prefer runtime secrets over `Dockerfile ENV` for credentials.

## 🔧 Core concepts [#-core-concepts]

| Mechanism            | Use                                                   |
| -------------------- | ----------------------------------------------------- |
| `ENV`                | Non-secret defaults in image                          |
| `ARG`                | Build-time only (still visible in history if misused) |
| `-e` / `environment` | Runtime env                                           |
| `env_file`           | File of KEY=VAL                                       |
| BuildKit `--secret`  | Secret mounts during build                            |
| Orchestrator secrets | Swarm/K8s/Compose secrets                             |

## 💡 Examples [#-examples]

**Runtime env:**

```shellscript
docker run --rm -e DATABASE_URL="$DATABASE_URL" myapp:1.0.0
```

**Compose env\_file:**

```yaml
services:
  api:
    env_file:
      - .env
    environment:
      NODE_ENV: production
```

**BuildKit npm token (sketch):**

```dockerfile
# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=npm,target=/root/.npmrc npm ci
```

```shellscript
docker build --secret id=npm,src=$HOME/.npmrc -t myapp .
```

## ⚠️ Pitfalls [#️-pitfalls]

* `ENV SECRET=...` in a Dockerfile is recoverable from image history.
* Committing `.env` with production credentials is a common breach path.
* `docker history` and layer caching can retain leaked build args.

## 🔗 Related [#-related]

* [dockerfile.md](/docs/docker/dockerfile)
* [compose.md](/docs/docker/compose)
* [multi\_stage.md](/docs/docker/multi-stage)
* [getting\_started.md](/docs/docker/getting-started)


# Getting Started with Docker (/docs/docker/getting-started)



# Getting Started with Docker [#getting-started-with-docker]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Docker packages apps and dependencies into images and runs them as containers. Use it for reproducible environments, local stacks, and deployment units.

## 🔧 Core concepts [#-core-concepts]

| Idea       | Meaning                                   |
| ---------- | ----------------------------------------- |
| Image      | Immutable filesystem + metadata template  |
| Container  | Running (or stopped) instance of an image |
| Dockerfile | Build recipe for an image                 |
| Registry   | Image store (Docker Hub, GHCR, …)         |
| Compose    | Multi-container app definition            |

| Command          | Purpose                  |
| ---------------- | ------------------------ |
| `docker version` | Client/server versions   |
| `docker pull`    | Download image           |
| `docker run`     | Create + start container |
| `docker ps`      | List running containers  |
| `docker build`   | Build from Dockerfile    |

## 💡 Examples [#-examples]

**Run nginx:**

```shellscript
docker run --rm -p 8080:80 nginx:alpine
```

**Build and run:**

```shellscript
docker build -t myapp:dev .
docker run --rm -p 9000:9000 myapp:dev
```

**Shell into a container:**

```shellscript
docker exec -it <container> sh
```

## ⚠️ Pitfalls [#️-pitfalls]

* Binding only to container localhost is fine; publishing ports needs `-p host:container`.
* Data in the writable container layer is lost when the container is removed — use volumes.
* Running as root inside images increases risk — prefer non-root users in production images.

## 🔗 Related [#-related]

* [dockerfile.md](/docs/docker/dockerfile)
* [compose.md](/docs/docker/compose)
* [images\_tags.md](/docs/docker/images-tags)
* [glossary.md](/docs/docker/glossary)


# Glossary (/docs/docker/glossary)



# Glossary [#glossary]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of Docker image, container, and Compose terms.

## 🔧 Core concepts [#-core-concepts]

| Term            | Definition                                                   |
| --------------- | ------------------------------------------------------------ |
| Bind mount      | Host directory mounted into a container path.                |
| Bridge network  | Default single-host virtual network for containers.          |
| Build context   | Files sent to the daemon for `docker build`.                 |
| Compose         | YAML-driven multi-container application tool.                |
| Container       | Runnable instance of an image with its own filesystem layer. |
| Digest          | Content-addressed `sha256:` image identity.                  |
| EntryPoint      | Primary executable configuration for a container.            |
| Image           | Immutable layered snapshot used to create containers.        |
| Layer           | Filesystem diff produced by a Dockerfile instruction.        |
| Multi-stage     | Build pattern with multiple `FROM` stages.                   |
| Registry        | Remote store for images (Docker Hub, GHCR, ECR…).            |
| Tag             | Mutable human label for an image (`:1.2.0`, `:latest`).      |
| Volume          | Persistent Docker-managed storage mount.                     |
| `.dockerignore` | Excludes files from the build context.                       |

## 💡 Examples [#-examples]

**Name anatomy:**

```
ghcr.io/acme/api:1.4.0
└ registry ┘ └image┘ └tag┘
```

**Quick lifecycle:**

```shellscript
docker build -t demo:1 .
docker run --rm demo:1
```

## ⚠️ Pitfalls [#️-pitfalls]

* “Container stopped” still exists until removed — check `docker ps -a`.
* Tag ≠ immutable identity — digests do.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/docker/getting-started)
* [dockerfile.md](/docs/docker/dockerfile)
* [compose.md](/docs/docker/compose)
* [README.md](/docs/docker)


# Healthchecks (/docs/docker/healthchecks)



# Healthchecks [#healthchecks]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Healthchecks tell Docker/Compose whether a container is ready or healthy. Use them for restart policies and `depends_on` conditions.

## 🔧 Core concepts [#-core-concepts]

| Field          | Meaning                           |
| -------------- | --------------------------------- |
| `test`         | Command that exits 0 when healthy |
| `interval`     | Time between checks               |
| `timeout`      | Max time for one check            |
| `retries`      | Failures before unhealthy         |
| `start_period` | Grace period during boot          |

| Status      | Meaning              |
| ----------- | -------------------- |
| `starting`  | Within start\_period |
| `healthy`   | Checks passing       |
| `unhealthy` | Checks failing       |

## 💡 Examples [#-examples]

**Dockerfile HEALTHCHECK:**

```dockerfile
HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
  CMD wget -qO- http://127.0.0.1:9000/health || exit 1
```

**Compose healthcheck + depends\_on:**

```yaml
services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy
```

**Inspect:**

```shellscript
docker inspect --format='{{.State.Health.Status}}' <container>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Checking TCP port open ≠ app ready — hit a real `/health` when possible.
* Too-aggressive intervals spam logs and CPU.
* Healthcheck tools must exist in the image (`curl`/`wget` often missing on alpine/distroless).

## 🔗 Related [#-related]

* [compose.md](/docs/docker/compose)
* [dockerfile.md](/docs/docker/dockerfile)
* [networks.md](/docs/docker/networks)
* [getting\_started.md](/docs/docker/getting-started)


# Images & Tags (/docs/docker/images-tags)



# Images & Tags [#images--tags]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Images are addressed as `name:tag` (and digests). Tags are mutable labels — pin carefully for production reproducibility.

## 🔧 Core concepts [#-core-concepts]

| Reference           | Example              |
| ------------------- | -------------------- |
| Official short name | `nginx:alpine`       |
| Namespaced          | `grafana/grafana:11` |
| Digest pin          | `nginx@sha256:…`     |
| Local tag           | `myapp:dev`          |

| Command                             | Purpose          |
| ----------------------------------- | ---------------- |
| `docker images` / `docker image ls` | List             |
| `docker tag`                        | Add another name |
| `docker push` / `pull`              | Registry sync    |
| `docker rmi`                        | Remove image     |
| `docker image prune`                | Clean dangling   |

| Tag hygiene | Prefer                                  |
| ----------- | --------------------------------------- |
| Prod        | Digests or immutable tags (`1.2.3`)     |
| Base images | Distroless / alpine / slim thoughtfully |
| Avoid       | Floating `latest` in prod deploys       |

## 💡 Examples [#-examples]

**Tag and push:**

```shellscript
docker build -t ghcr.io/acme/api:1.4.0 .
docker push ghcr.io/acme/api:1.4.0
```

**Retag:**

```shellscript
docker tag myapp:dev myapp:1.4.0
```

**Remove dangling:**

```shellscript
docker image prune -f
```

## ⚠️ Pitfalls [#️-pitfalls]

* `latest` moves — yesterday’s deploy may not equal today’s pull.
* Deleting a tag on the registry does not delete all digests immediately.
* Huge images slow pulls — multi-stage builds and `.dockerignore` help.

## 🔗 Related [#-related]

* [dockerfile.md](/docs/docker/dockerfile)
* [multi\_stage.md](/docs/docker/multi-stage)
* [getting\_started.md](/docs/docker/getting-started)
* [compose.md](/docs/docker/compose)


# Docker (/docs/docker)



# Docker [#docker]

Images, Compose, containers.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Multi-stage Builds (/docs/docker/multi-stage)



# Multi-stage Builds [#multi-stage-builds]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Multi-stage Dockerfiles use multiple `FROM` stages so build tools stay out of the final runtime image. Smaller, safer production images.

## 🔧 Core concepts [#-core-concepts]

| Pattern             | Role                              |
| ------------------- | --------------------------------- |
| `AS name`           | Name a stage                      |
| `COPY --from=stage` | Copy artifacts only               |
| Builder stage       | Compile, `npm ci`, tests optional |
| Runtime stage       | Minimal base + binary/dist        |

| Benefit          | Why                     |
| ---------------- | ----------------------- |
| Smaller image    | No compilers/toolchains |
| Fewer CVEs       | Less software surface   |
| Clear separation | Build vs run            |

## 💡 Examples [#-examples]

**Go binary:**

```dockerfile
FROM golang:1.22 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app

FROM gcr.io/distroless/static
COPY --from=build /out/app /app
USER nonroot
ENTRYPOINT ["/app"]
```

**Node (deps → build → run):**

```dockerfile
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
COPY package.json .
CMD ["node", "dist/server.js"]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Copying entire `node_modules` from a build stage may include devDependencies — use production installs in the final stage.
* Forgetting `.dockerignore` still bloats build context even with multi-stage.
* Debugging is harder — keep a `debug` stage target when needed (`docker build --target`).

## 🔗 Related [#-related]

* [dockerfile.md](/docs/docker/dockerfile)
* [images\_tags.md](/docs/docker/images-tags)
* [env\_secrets.md](/docs/docker/env-secrets)
* [getting\_started.md](/docs/docker/getting-started)


# Networks (/docs/docker/networks)



# Networks [#networks]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Docker networks connect containers. Compose creates a default network so services resolve each other by service name as DNS.

## 🔧 Core concepts [#-core-concepts]

| Driver    | Use                              |
| --------- | -------------------------------- |
| `bridge`  | Default single-host network      |
| `host`    | Share host network stack (Linux) |
| `none`    | No networking                    |
| `overlay` | Swarm multi-host                 |

| Concept          | Detail                                 |
| ---------------- | -------------------------------------- |
| Service DNS      | `http://api:9000` from another service |
| Publish ports    | Expose to host via `-p`                |
| Internal network | No external connectivity               |

## 💡 Examples [#-examples]

**Inspect defaults:**

```shellscript
docker network ls
docker network inspect bridge
```

**User-defined bridge:**

```shellscript
docker network create appnet
docker run -d --name db --network appnet postgres:16-alpine
docker run -d --name api --network appnet -p 9000:9000 myapi
```

**Compose networks:**

```yaml
services:
  api:
    networks: [frontend, backend]
  db:
    networks: [backend]
networks:
  frontend:
  backend:
    internal: true
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using host `localhost` to reach another container fails — use DNS name.
* Publishing every port widens attack surface — only publish what you need.
* `host` network mode breaks container isolation assumptions.

## 🔗 Related [#-related]

* [compose.md](/docs/docker/compose)
* [getting\_started.md](/docs/docker/getting-started)
* [healthchecks.md](/docs/docker/healthchecks)
* [volumes.md](/docs/docker/volumes)


# Volumes (/docs/docker/volumes)



# Volumes [#volumes]

*Docker · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Volumes persist data beyond a container’s lifecycle and share files between host and container. Prefer named volumes for databases; bind mounts for live code in development.

## 🔧 Core concepts [#-core-concepts]

| Type             | Behavior                         |
| ---------------- | -------------------------------- |
| Named volume     | Docker-managed storage           |
| Bind mount       | Host path mounted into container |
| Anonymous volume | Unnamed; easy to lose track of   |
| tmpfs            | In-memory mount                  |

| Flag                  | Example            |
| --------------------- | ------------------ |
| `-v name:/path`       | Named volume       |
| `-v /host:/container` | Bind mount         |
| `--mount`             | Explicit long form |

## 💡 Examples [#-examples]

**Named volume for Postgres:**

```shellscript
docker volume create pgdata
docker run -v pgdata:/var/lib/postgresql/data postgres:16
```

**Compose volume:**

```yaml
services:
  db:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:
```

**Dev bind mount:**

```shellscript
docker run --rm -v "${PWD}:/app" -w /app node:22 npm test
```

## ⚠️ Pitfalls [#️-pitfalls]

* Bind-mounting over a path that had image data hides the image content.
* Permissions (UID/GID) on Linux bind mounts often break writes — match users.
* `docker compose down -v` deletes named volumes — destructive.

## 🔗 Related [#-related]

* [compose.md](/docs/docker/compose)
* [getting\_started.md](/docs/docker/getting-started)
* [env\_secrets.md](/docs/docker/env-secrets)
* [networks.md](/docs/docker/networks)


# Adaptive design (/docs/css/adaptive)



# Adaptive design [#adaptive-design]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Adaptive design adjusts layout, typography, and interaction patterns to the viewport, input method, and user preferences. In CSS this is driven by media queries, container queries, and preference queries (`prefers-*`). Use it when a single fixed layout cannot serve phones, tablets, desktops, and accessibility needs equally well.

Prefer fluid units and container queries for component-level adaptation; reserve viewport media queries for page chrome and major breakpoints.

## 🔧 Core concepts [#-core-concepts]

### Media features [#media-features]

| Feature                             | Typical use                 |
| ----------------------------------- | --------------------------- |
| `width` / `min-width` / `max-width` | Viewport breakpoints        |
| `height` / `orientation`            | Tall vs wide layouts        |
| `hover` / `pointer`                 | Touch vs mouse affordances  |
| `prefers-reduced-motion`            | Disable or soften animation |
| `prefers-color-scheme`              | Light / dark themes         |
| `prefers-contrast`                  | High-contrast adjustments   |

### Breakpoint pattern [#breakpoint-pattern]

```css
/* Mobile-first: base styles, then enhance */
.card { padding: 1rem; }

@media (min-width: 48rem) {
  .card { padding: 1.5rem; display: grid; grid-template-columns: 1fr 1fr; }
}

@media (min-width: 80rem) {
  .card { grid-template-columns: 1fr 1fr 1fr; }
}
```

### Container queries [#container-queries]

| Property / rule               | Role                                      |
| ----------------------------- | ----------------------------------------- |
| `container-type: inline-size` | Establish a size query container          |
| `container-name`              | Name a container for targeted queries     |
| `@container (min-width: …)`   | Style based on parent width, not viewport |

### Logical & fluid sizing [#logical--fluid-sizing]

| Approach      | Example                                                |
| ------------- | ------------------------------------------------------ |
| Fluid type    | `font-size: clamp(1rem, 0.9rem + 0.5vw, 1.25rem)`      |
| Fluid space   | `padding-inline: clamp(1rem, 4vw, 3rem)`               |
| Logical props | `margin-inline`, `padding-block`, `inset-inline-start` |

## 💡 Examples [#-examples]

### Viewport media query (mobile-first) [#viewport-media-query-mobile-first]

```css
.nav {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}

@media (min-width: 64rem) {
  .nav {
    flex-direction: row;
    align-items: center;
    justify-content: space-between;
  }
}
```

### Container query card [#container-query-card]

```html
<div class="card-shell">
  <article class="card">…</article>
</div>
```

```css
.card-shell {
  container-type: inline-size;
  container-name: card;
}

.card { display: block; }

@container card (min-width: 28rem) {
  .card {
    display: grid;
    grid-template-columns: 8rem 1fr;
    gap: 1rem;
  }
}
```

### Input and motion preferences [#input-and-motion-preferences]

```css
/* Coarse pointer: larger hit targets */
@media (pointer: coarse) {
  .btn { min-block-size: 2.75rem; padding-inline: 1.25rem; }
}

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}
```

### Fluid layout without breakpoints [#fluid-layout-without-breakpoints]

```css
.gallery {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
  gap: clamp(0.75rem, 2vw, 1.5rem);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Designing desktop-first and only shrinking with `max-width` queries often creates brittle overrides.
* Using only viewport queries for reusable components breaks when the same card sits in a narrow sidebar.
* Ignoring `prefers-reduced-motion` and `prefers-color-scheme` harms accessibility and OS integration.
* Hard-coding many pixel breakpoints instead of a small set plus fluid `clamp()` / `minmax()`.
* Testing only by resizing a desktop window—verify real devices, zoom, and landscape orientation.

## 🔗 Related [#-related]

* [Flexbox](/docs/css/flex)
* [CSS Grid](/docs/css/grid)
* [Positioning](/docs/css/position)
* [Scroll](/docs/css/scroll)


# Animation (/docs/css/animation)



# Animation [#animation]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS animations change property values over time using `@keyframes` and the `animation` longhands. Use them for attention, state feedback, and ambient motion—not for continuous layout thrashing. Prefer transitions for simple A→B state changes; use keyframe animations when you need multi-step timelines, loops, or delayed sequences.

Always respect `prefers-reduced-motion` and keep animated properties on the compositor (`transform`, `opacity`) when possible.

## 🔧 Core concepts [#-core-concepts]

### Animation properties [#animation-properties]

| Property                    | Purpose                                                              |
| --------------------------- | -------------------------------------------------------------------- |
| `animation-name`            | Keyframes identifier                                                 |
| `animation-duration`        | Length of one cycle                                                  |
| `animation-timing-function` | Easing (`ease`, `cubic-bezier()`, `steps()`)                         |
| `animation-delay`           | Start offset                                                         |
| `animation-iteration-count` | `1`, `n`, or `infinite`                                              |
| `animation-direction`       | `normal` \| `reverse` \| `alternate` \| `alternate-reverse`          |
| `animation-fill-mode`       | `none` \| `forwards` \| `backwards` \| `both`                        |
| `animation-play-state`      | `running` \| `paused`                                                |
| `animation-composition`     | How multiple animations combine (`replace` \| `add` \| `accumulate`) |

Shorthand: `animation: name duration timing-function delay iteration-count direction fill-mode play-state`.

### Keyframes [#keyframes]

```css
@keyframes fade-up {
  from {
    opacity: 0;
    transform: translateY(0.5rem);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}
```

Percent stops (`0%`, `50%`, `100%`) allow multi-step sequences. Omitted properties interpolate when possible.

### Performance notes [#performance-notes]

| Prefer                           | Avoid animating                                  |
| -------------------------------- | ------------------------------------------------ |
| `transform`, `opacity`           | `top` / `left` / `width` / `height`              |
| `translate` / `scale` / `rotate` | Frequent `box-shadow` / `filter` on large layers |
| `will-change` sparingly          | Permanent `will-change` on many nodes            |

## 💡 Examples [#-examples]

### Entrance animation [#entrance-animation]

```css
.toast {
  animation: fade-up 280ms cubic-bezier(0.22, 1, 0.36, 1) both;
}

@keyframes fade-up {
  from { opacity: 0; transform: translateY(0.75rem); }
  to   { opacity: 1; transform: translateY(0); }
}
```

### Infinite loader [#infinite-loader]

```css
.spinner {
  inline-size: 2rem;
  block-size: 2rem;
  border: 0.2rem solid color-mix(in oklab, CanvasText 20%, transparent);
  border-block-start-color: CanvasText;
  border-radius: 50%;
  animation: spin 0.8s linear infinite;
}

@keyframes spin {
  to { transform: rotate(360deg); }
}
```

### Staggered list with delays [#staggered-list-with-delays]

```css
.item {
  animation: fade-up 400ms ease both;
}

.item:nth-child(1) { animation-delay: 0ms; }
.item:nth-child(2) { animation-delay: 60ms; }
.item:nth-child(3) { animation-delay: 120ms; }
```

### Reduced motion fallback [#reduced-motion-fallback]

```css
@media (prefers-reduced-motion: reduce) {
  .toast,
  .spinner,
  .item {
    animation: none;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Animating layout properties every frame causes reflow and jank; use transforms instead.
* Forgetting `animation-fill-mode: forwards` (or `both`) so the end state snaps back after the animation ends.
* Running `infinite` animations on off-screen content without pausing (`animation-play-state` or removing the class).
* Ignoring `prefers-reduced-motion`, which can make interfaces unusable for vestibular disorders.
* Overusing `will-change`, which can increase memory use and create unexpected stacking contexts.

## 🔗 Related [#-related]

* [Transforms](/docs/css/transform)
* [Hover](/docs/css/hover)
* [Effects](/docs/css/effects)
* [Scale](/docs/css/scale)


# Aspect Ratio (/docs/css/aspect-ratio)



# Aspect Ratio [#aspect-ratio]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`aspect-ratio` preserves a box’s width-to-height relationship (e.g. `16 / 9`) as the other dimension flexes. Replaces old padding-top hacks for media frames, embeds, and cards. Combine with `object-fit` for replaced content.

## 🔧 Core concepts [#-core-concepts]

* **Syntax**: `aspect-ratio: auto | <ratio>` e.g. `16 / 9`, `1`, `4 / 3`.
* **`auto`**: use intrinsic ratio of replaced elements when available.
* **Conflict**: if width, height, and ratio all set, browsers may ignore one per rules — prefer width + ratio or height + ratio.
* **Min/max**: `min-height` can override the ratio box.
* **With grid/flex**: ratio boxes as items work well for galleries.

```css
.video {
  aspect-ratio: 16 / 9;
  width: 100%;
  background: #000;
}
.video iframe {
  width: 100%;
  height: 100%;
  border: 0;
}
```

## 💡 Examples [#-examples]

```css
/* Square thumbs */
.thumb {
  aspect-ratio: 1;
  object-fit: cover;
  width: 100%;
}

/* Portrait card */
.poster {
  aspect-ratio: 2 / 3;
}

/* Prefer auto for images with intrinsic size */
img {
  max-width: 100%;
  height: auto;
  aspect-ratio: auto;
}

/* Grid gallery */
.gallery {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(12rem, 1fr));
  gap: 1rem;
}
.gallery > * {
  aspect-ratio: 4 / 3;
  object-fit: cover;
}

/* Fallback old hack (legacy) */
.legacy {
  height: 0;
  padding-top: 56.25%;
  position: relative;
}
```

```css
/* Explicit both dimensions wins over ratio in some cases — avoid */
```

## ⚠️ Pitfalls [#️-pitfalls]

* Setting both `width` and `height` plus `aspect-ratio` can produce surprising ignored values.
* Content taller than the ratio box overflows unless `overflow: hidden` / flex layout inside.
* Intrinsic `auto` ratio fails for empty containers — set an explicit ratio.
* SVGs without intrinsic sizing may need explicit ratio.
* Don’t use ratio alone for text-heavy cards without overflow plan.

## 🔗 Related [#-related]

* [object\_fit.md](/docs/css/object-fit) — fitting media
* [image.md](/docs/css/image) — images
* [box\_model.md](/docs/css/box-model) — sizing
* [grid.md](/docs/css/grid) — galleries
* [../Html/video\_audio.md](/docs/css/../html/video-audio) — media embeds


# Background (/docs/css/background)



# Background [#background]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Background properties paint behind an element’s content and padding (by default), including colors, images, gradients, and layered stacks. Use them for surfaces, hero imagery, patterns, and decorative layers without adding extra DOM nodes. Multiple backgrounds are listed comma-separated, drawn from top (first) to bottom (last).

Prefer modern color spaces (`oklch`, `color-mix`) and `background-size` / `background-position` for responsive imagery; use `image-set()` when serving resolution variants.

## 🔧 Core concepts [#-core-concepts]

### Core properties [#core-properties]

| Property                | Role                                                            |
| ----------------------- | --------------------------------------------------------------- |
| `background-color`      | Solid fill (shows through transparent images)                   |
| `background-image`      | URL, gradient, or `none` (stackable)                            |
| `background-position`   | Anchor of the image (`center`, `top right`, `%`, lengths)       |
| `background-size`       | `auto` \| `cover` \| `contain` \| `<w> <h>`                     |
| `background-repeat`     | `repeat` \| `no-repeat` \| `space` \| `round` \| axes           |
| `background-attachment` | `scroll` \| `fixed` \| `local`                                  |
| `background-origin`     | Positioning box: `padding-box` \| `border-box` \| `content-box` |
| `background-clip`       | Painting area; `text` for clipped text fills                    |
| `background-blend-mode` | How layers blend with each other / color                        |

Shorthand: `background: [layer], [layer], … / color` — color is listed last and is not layered the same way as images.

### Layering model [#layering-model]

```css
.hero {
  background:
    linear-gradient(to bottom, rgb(0 0 0 / 0.45), transparent 60%),
    url("/img/hero.jpg") center / cover no-repeat,
    oklch(0.25 0.02 250);
}
```

First layer paints on top. The final color acts as a fallback under all images.

### Clipping & text fills [#clipping--text-fills]

| Value                          | Effect                                     |
| ------------------------------ | ------------------------------------------ |
| `background-clip: border-box`  | Default paint into border edge             |
| `background-clip: padding-box` | Stop under the border                      |
| `background-clip: content-box` | Only content box                           |
| `background-clip: text`        | Fill glyphs (needs transparent text color) |

## 💡 Examples [#-examples]

### Cover photo with scrim [#cover-photo-with-scrim]

```css
.banner {
  min-block-size: 20rem;
  color: white;
  background:
    linear-gradient(180deg, rgb(0 0 0 / 0.55), rgb(0 0 0 / 0.2)),
    url("/media/banner.jpg") center / cover no-repeat;
}
```

### Pattern tile [#pattern-tile]

```css
.panel {
  background-color: oklch(0.97 0.01 100);
  background-image: url("/patterns/dots.svg");
  background-size: 1.5rem 1.5rem;
  background-repeat: repeat;
}
```

### Gradient text [#gradient-text]

```css
.brand {
  background-image: linear-gradient(90deg, #0ea5e9, #6366f1);
  background-clip: text;
  -webkit-background-clip: text; /* WebKit */
  color: transparent;
}
```

### Fixed parallax-style layer [#fixed-parallax-style-layer]

```css
.parallax {
  background-image: url("/img/texture.jpg");
  background-size: cover;
  background-attachment: fixed;
  background-position: center;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Putting `background-color` in the middle of a multi-layer shorthand can drop layers or confuse cascade order—keep color last.
* `background-attachment: fixed` is expensive and often broken or disabled on mobile browsers.
* Using `cover` without a sensible `background-position` crops important subject matter.
* Forgetting a solid `background-color` fallback when images fail or load slowly.
* Relying on `background` for meaningful content—screen readers and broken-image states won’t expose it; use `<img>` for content images.

## 🔗 Related [#-related]

* [Gradients](/docs/css/gradient)
* [Images](/docs/css/image)
* [Effects](/docs/css/effects)
* [Text](/docs/css/text)


# Box Model Basics (/docs/css/box-model-basics)



# Box Model Basics [#box-model-basics]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Every element is a **box** made of content, padding, border, and margin. Layout spacing bugs almost always come from misunderstanding this model. Prefer `box-sizing: border-box` in modern pages.

## 🔧 Core concepts [#-core-concepts]

| Layer         | Role                                          |
| ------------- | --------------------------------------------- |
| Content       | Text or children; sized by `width` / `height` |
| Padding       | Space inside the border                       |
| Border        | Line around the padding                       |
| Margin        | Space outside the border                      |
| `content-box` | Default: width = content only                 |
| `border-box`  | Width includes padding + border               |

Vertical margins can **collapse** between stacked blocks.

## 💡 Examples [#-examples]

**See the box:**

```css
.card {
  width: 200px;
  padding: 16px;
  border: 4px solid #334155;
  margin: 24px;
  background: #f8fafc;
}
```

**border-box (recommended):**

```css
*,
*::before,
*::after {
  box-sizing: border-box;
}

.box {
  width: 200px;
  padding: 20px;
  border: 5px solid black;
  /* total outer width stays 200px with border-box */
}
```

**Margin vs padding:**

```css
.section {
  padding: 1rem; /* space inside, keeps background */
  margin-bottom: 2rem; /* space outside, separates from next block */
  background: #e2e8f0;
}
```

**Inspect in DevTools:** select an element and view the box model diagram.

## ⚠️ Pitfalls [#️-pitfalls]

* With `content-box`, `width: 200px` + padding + border grows past 200px.
* `margin: auto` horizontal centering needs a defined width on block boxes.
* Margin collapse can remove expected vertical gaps between siblings.
* Inline elements ignore `width`/`height` differently than block elements.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/css/getting-started)
* [selectors\_basics.md](/docs/css/selectors-basics)
* [cascade\_basics.md](/docs/css/cascade-basics)
* [box\_model.md](/docs/css/box-model)


# Box Model (/docs/css/box-model)



# Box Model [#box-model]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Every element box has content, padding, border, and margin. `box-sizing` controls whether `width`/`height` include padding and border. Mastering the box model prevents overflow surprises and layout math errors.

## 🔧 Core concepts [#-core-concepts]

* **Content box**: where text/replaced content sits.
* **Padding**: inside the border, clears content.
* **Border**: edge around padding.
* **Margin**: outside border; vertical margins may collapse.
* **`box-sizing: content-box`** (default): width = content only.
* **`box-sizing: border-box`**: width includes padding + border (recommended reset).
* **Outline** / **box-shadow**: don’t add to layout size.

```css
*,
*::before,
*::after {
  box-sizing: border-box;
}
.card {
  width: 320px;
  padding: 1rem;
  border: 2px solid #ccc;
  margin: 1rem auto;
}
```

## 💡 Examples [#-examples]

```css
/* Total footprint with border-box */
.box {
  box-sizing: border-box;
  width: 100%;
  padding: 16px;
  border: 4px solid;
} /* content shrinks; outer width stays 100% */

/* Margin collapse (siblings / parent-child) */
.section + .section {
  margin-top: 2rem; /* prefer gap in flex/grid */
}

/* Intrinsic sizing */
img {
  max-width: 100%;
  height: auto;
  display: block; /* remove inline gap */
}

/* Min/max */
.panel {
  min-width: 0; /* allow flex/grid children to shrink */
  max-width: 60ch;
}

/* Logical box */
.box {
  padding-inline: 1rem;
  padding-block: 0.5rem;
  margin-inline: auto;
}
```

```css
/* Debug */
* {
  outline: 1px solid rgb(255 0 0 / 0.2);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing `content-box` widths with padding causes overflow past the intended size.
* Vertical margin collapse can “eat” parent padding expectations — use flex `gap` or BFC (`overflow: auto`).
* Inline elements ignore `width`/`height` / vertical margins differently — use `inline-block` or block.
* `min-width: auto` on flex items prevents shrinking below content — set `min-width: 0`.
* Percentage padding resolves against **width** of containing block (including vertical padding %).

## 🔗 Related [#-related]

* [logical\_properties.md](/docs/css/logical-properties) — inline/block
* [overflow.md](/docs/css/overflow) — clipping
* [z\_index.md](/docs/css/z-index) — stacking
* [flex.md](/docs/css/flex) — flex sizing
* [grid.md](/docs/css/grid) — grid tracks


# Buttons (/docs/css/button)



# Buttons [#buttons]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Button styling covers native `<button>`, `[type="submit"]`, and link-buttons that must look and behave like controls. Good button CSS balances affordance (clear hit target, focus, hover/active), accessibility (contrast, keyboard focus), and consistency across variants (primary, secondary, ghost, danger). Prefer styling the real `<button>` element over clickable `<div>`s.

Use logical properties, relative units, and `:focus-visible` so mouse and keyboard users both get appropriate feedback.

## 🔧 Core concepts [#-core-concepts]

### Baseline reset & structure [#baseline-reset--structure]

| Concern   | Recommendation                                                         |
| --------- | ---------------------------------------------------------------------- |
| Font      | `font: inherit` so buttons match surrounding type                      |
| Cursor    | `cursor: pointer` on enabled controls                                  |
| Sizing    | Min hit area ≈ 44×44 CSS px on touch UIs                               |
| Alignment | `inline-flex` + `align-items` / `justify-content` for icon+label       |
| Disabled  | `disabled` attribute + `:disabled` styles; don’t rely on opacity alone |

### Interactive pseudo-classes [#interactive-pseudo-classes]

| Selector                               | When it applies                              |
| -------------------------------------- | -------------------------------------------- |
| `:hover`                               | Pointer over control (may be false on touch) |
| `:active`                              | During press                                 |
| `:focus-visible`                       | Keyboard (or UA-determined) focus ring       |
| `:disabled` / `[aria-disabled="true"]` | Non-interactive                              |
| `:focus-within`                        | Rarely needed on the button itself           |

### Design tokens (typical) [#design-tokens-typical]

| Token                         | Example role            |
| ----------------------------- | ----------------------- |
| `--btn-bg` / `--btn-fg`       | Fill and label          |
| `--btn-radius`                | Corner radius           |
| `--btn-pad-x` / `--btn-pad-y` | Internal spacing        |
| `--btn-border`                | Outline / ghost borders |

## 💡 Examples [#-examples]

### Solid primary button [#solid-primary-button]

```css
.btn {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
  padding: 0.625rem 1rem;
  border: 1px solid transparent;
  border-radius: 0.5rem;
  font: inherit;
  font-weight: 600;
  line-height: 1.2;
  cursor: pointer;
  background: oklch(0.55 0.18 250);
  color: white;
  transition: background-color 150ms ease, transform 100ms ease;
}

.btn:hover { background: oklch(0.48 0.18 250); }
.btn:active { transform: translateY(1px); }

.btn:focus-visible {
  outline: 2px solid oklch(0.7 0.15 250);
  outline-offset: 2px;
}

.btn:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}
```

### Ghost / secondary variants [#ghost--secondary-variants]

```css
.btn--ghost {
  background: transparent;
  color: oklch(0.4 0.12 250);
  border-color: color-mix(in oklab, currentColor 35%, transparent);
}

.btn--ghost:hover {
  background: color-mix(in oklab, currentColor 8%, transparent);
}
```

### Icon + label markup [#icon--label-markup]

```html
<button type="button" class="btn">
  <svg class="btn__icon" aria-hidden="true" focusable="false">…</svg>
  Save
</button>
```

```css
.btn__icon {
  inline-size: 1.125rem;
  block-size: 1.125rem;
  flex-shrink: 0;
}
```

### Full-width on small containers [#full-width-on-small-containers]

```css
.btn--block {
  display: flex;
  inline-size: 100%;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Removing `outline` without providing an equivalent `:focus-visible` style breaks keyboard users.
* Using `<a>` styled as a button for actions that don’t navigate—prefer `<button type="button">`.
* Setting only `opacity` on disabled buttons without `pointer-events` / `disabled`, so clicks still fire.
* Tiny tap targets (`padding: 2px 4px`) that fail mobile accessibility guidelines.
* Animating layout on press (`height` changes) instead of lightweight `transform` / color shifts.

## 🔗 Related [#-related]

* [Hover](/docs/css/hover)
* [Cursor](/docs/css/cursor)
* [Icons](/docs/css/icon)
* [Text fields](/docs/css/textfield)


# calc, min, max, clamp (/docs/css/calc-min-max-clamp)



# calc, min, max, clamp [#calc-min-max-clamp]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS math functions compute lengths and numbers: `calc()` for expressions, `min()`/`max()` for bounds, and `clamp(min, preferred, max)` for fluid sizing. Essential for responsive type, gutters, and hybrid fixed/fluid layouts without many breakpoints.

## 🔧 Core concepts [#-core-concepts]

* **`calc(a + b)`**: `+`/`-` need spaces; `*`/`/` don’t mix incompatible units blindly.
* **`min(a, b, …)`*&#x2A;: smallest value; &#x2A;*`max`**: largest.
* **`clamp(MIN, VAL, MAX)`**: equivalent to `max(MIN, min(VAL, MAX))`.
* **Units**: mix `%`, `rem`, `vw`, `vh` inside calc carefully (browser resolves).
* **Nested**: functions can nest; variables welcome.
* **Also**: `abs()`, `round()`, `sin()`… in modern CSS (support varies).

```css
width: calc(100% - 2rem);
font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
padding-inline: max(1rem, 3vw);
```

## 💡 Examples [#-examples]

```css
/* Fluid type */
:root {
  --step-0: clamp(1rem, 0.9rem + 0.4vw, 1.125rem);
}

/* Full-bleed breakout */
.full {
  width: 100vw;
  margin-inline: calc(50% - 50vw);
}

/* Sidebar layout */
.main {
  width: min(100%, 70rem);
  margin-inline: auto;
  padding-inline: max(1rem, calc((100% - 70rem) / 2));
}

/* Gap with vars */
.grid {
  gap: calc(var(--space, 0.5rem) * 2);
}

/* Prefer clamp over media queries for simple scales */
.hero-title {
  font-size: clamp(1.75rem, 1rem + 3vw, 3rem);
}

/* Keep readable measure */
.prose {
  max-width: min(65ch, 100%);
}
```

```css
/* Safe area */
padding-bottom: max(1rem, env(safe-area-inset-bottom));
```

## ⚠️ Pitfalls [#️-pitfalls]

* `calc(100% - 2)` is invalid — units required on both sides of `+`/`-`.
* Division by zero / invalid units make the declaration dropped.
* `clamp` preferred value can be written so min > max — browsers may swap or fail; keep MIN ≤ MAX.
* Mixing `vh` with mobile browser chrome causes jumpiness — consider `dvh`/`svh`.
* Don’t over-fluidize — extreme `vw` type harms zoom/a11y; prefer rem-based clamps.

## 🔗 Related [#-related]

* [variables.md](/docs/css/variables) — tokens in calc
* [media\_queries.md](/docs/css/media-queries) — when math isn’t enough
* [adaptive.md](/docs/css/adaptive) — responsive patterns
* [box\_model.md](/docs/css/box-model) — width math
* [font.md](/docs/css/font) — fluid type


# Cascade Basics (/docs/css/cascade-basics)



# Cascade Basics [#cascade-basics]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The **cascade** decides which CSS rule wins when several apply to the same element. Browsers combine origin, importance, **specificity**, and source order. Understanding this stops “why didn’t my style apply?” frustration.

## 🔧 Core concepts [#-core-concepts]

| Factor       | Simple takeaway                                        |
| ------------ | ------------------------------------------------------ |
| Importance   | `!important` beats normal rules (avoid while learning) |
| Specificity  | Id > class > type (roughly)                            |
| Source order | Later rule wins if specificity is equal                |
| Inheritance  | Some properties flow to children (`color`, `font`)     |
| Inline style | `style=""` is very specific                            |

When two class selectors conflict, the one that appears **last** in the CSS usually wins.

## 💡 Examples [#-examples]

**Source order:**

```css
.title {
  color: blue;
}
.title {
  color: crimson; /* wins */
}
```

**Specificity sketch:**

```css
p {
  color: black;
} /* type: low */
.note {
  color: green;
} /* class: medium */
#intro {
  color: purple;
} /* id: high */
```

```html
<p id="intro" class="note">Which color?</p>
<!-- purple — id wins -->
```

**Inheritance:**

```css
article {
  color: #334155;
  font-family: Georgia, serif;
}
/* paragraphs inside article inherit color/font unless overridden */
```

**Equal specificity — last wins:**

```css
.btn {
  background: gray;
}
.btn {
  background: teal;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fighting with `#id` and `!important` creates unmaintainable CSS.
* Browser DevTools “Computed” panel shows the winner — use it.
* Not all properties inherit (`margin` does not).
* Linked stylesheets order in HTML matters for equal-specificity ties.

## 🔗 Related [#-related]

* [selectors\_basics.md](/docs/css/selectors-basics)
* [box\_model\_basics.md](/docs/css/box-model-basics)
* [specificity.md](/docs/css/specificity)
* [cascade\_layers.md](/docs/css/cascade-layers)


# Cascade Layers (/docs/css/cascade-layers)



# Cascade Layers [#cascade-layers]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`@layer` groups style rules into named cascade layers so **order of layers** beats specificity across layers. Use layers to keep resets, tokens, components, and utilities predictable without specificity wars. Unlayered styles win over layered ones.

## 🔧 Core concepts [#-core-concepts]

* **Declare order**: `@layer reset, tokens, base, components, utilities;`
* **Assign**: `@layer components \{ .card \{\} \}` or `@layer components.card \{ \}`.
* **Import**: `@import "x.css" layer(components);`
* **Priority**: earlier layers lose to later layers (when both apply), regardless of specificity.
* **Unlayered**: strongest among normal author styles (before `!important` games).
* **`!important`**: reverses layer order in the important bucket.

```css
@layer reset, base, components, utilities;

@layer reset {
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }
}
@layer components {
  .btn {
    padding: 0.5rem 1rem;
  }
}
@layer utilities {
  .p-0 {
    padding: 0;
  }
}
```

## 💡 Examples [#-examples]

```css
/* Nested layers */
@layer framework {
  @layer base {
    body {
      margin: 0;
    }
  }
  @layer components {
    .btn {
      color: white;
    }
  }
}
/* framework.base, framework.components */

/* Reordering via first declaration */
@layer a, b;
@layer b {
  .x {
    color: red;
  }
}
@layer a {
  .x {
    color: blue;
  }
} /* still loses — b is later */

/* Anonymous layer */
@layer {
  /* first anonymous */
}

/* Libraries first */
@layer vendor, app;
```

```css
/* Tip: put utilities last so .mt-0 beats components */
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting the initial `@layer a, b, c` order makes first-seen order define priority — declare explicitly.
* Unlayered CSS accidentally overrides everything layered — migrate carefully.
* `!important` in early layers becomes surprisingly strong — avoid.
* Layers don’t replace good naming — still organize files.
* DevTools cascade view is essential when debugging layer order.

## 🔗 Related [#-related]

* [specificity.md](/docs/css/specificity) — within a layer
* [reset\_normalize.md](/docs/css/reset-normalize) — reset layer
* [selectors.md](/docs/css/selectors) — selector design
* [variables.md](/docs/css/variables) — tokens layer
* [nesting.md](/docs/css/nesting) — nest inside layers


# Color Functions (/docs/css/color-functions)



# Color Functions [#color-functions]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Modern CSS colors use wide-gamut spaces and functions: `oklch`, `oklab`, `color()`, relative color syntax, and alpha with `/`. Prefer perceptually uniform spaces (`oklch`) for design systems and accessible gradients. Legacy `hex`, `rgb()`, `hsl()` remain fine.

## 🔧 Core concepts [#-core-concepts]

| Function                    | Notes                                     |
| --------------------------- | ----------------------------------------- |
| `oklch(L C H / A)`          | lightness, chroma, hue — great for themes |
| `oklab(...)`                | rectangular OKLab                         |
| `hsl()` / `hwb()`           | classic cylindrical                       |
| `rgb()` / `#rrggbbaa`       | sRGB                                      |
| `color(display-p3 ...)`     | wide gamut                                |
| `color-mix(in oklch, A, B)` | mix in a space                            |

* **Alpha**: `oklch(60% 0.1 250 / 0.8)` or `/ 80%`.
* **Relative**: `oklch(from var(--c) l c h)` / channel math.
* **Fallback**: provide hex/rgb before newer functions when needed.

```css
:root {
  --brand: oklch(62% 0.19 255);
  --brand-soft: color-mix(in oklch, var(--brand) 30%, white);
}
.button {
  background: var(--brand);
  color: oklch(99% 0 0);
}
```

## 💡 Examples [#-examples]

```css
/* Palette from one hue */
--h: 255;
--brand-1: oklch(95% 0.03 var(--h));
--brand-5: oklch(55% 0.18 var(--h));
--brand-9: oklch(30% 0.08 var(--h));

/* Relative color */
--accent: #3366ff;
--accent-dark: oklch(from var(--accent) calc(l * 0.8) c h);

/* Mix for hover */
.button:hover {
  background: color-mix(in oklch, var(--brand) 85%, black);
}

/* Gradients that don’t muddy */
background: linear-gradient(
  135deg,
  oklch(70% 0.15 30),
  oklch(65% 0.14 250)
);

/* P3 with fallback */
.hero {
  background: #ff3b00;
  background: color(display-p3 1 0.3 0);
}
```

```css
/* Contrast: still verify WCAG — oklch L helps but isn’t automatic */
```

## ⚠️ Pitfalls [#️-pitfalls]

* Out-of-gamut colors may map unexpectedly — check in target displays.
* Older Safari needed `-webkit` or lacked `color-mix` / relative syntax — progressive enhance.
* Mixing in sRGB often produces grayish midpoints — mix in `oklch`.
* `currentColor` and inheritance interact with computed colors carefully.
* Don’t assume L% maps 1:1 to WCAG contrast — measure.

## 🔗 Related [#-related]

* [variables.md](/docs/css/variables) — color tokens
* [gradient.md](/docs/css/gradient) — gradients
* [dark\_mode.md](/docs/css/dark-mode) — theme palettes
* [background.md](/docs/css/background) — backgrounds
* [filter\_backdrop.md](/docs/css/filter-backdrop) — filter color effects


# Multi-column layout (/docs/css/column)



# Multi-column layout [#multi-column-layout]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS multi-column layout (`columns`, `column-count`, `column-width`, and related properties) flows content into newspaper-style columns. Use it for long prose, glossaries, or tag lists where vertical reading across balanced columns improves scanability. Prefer Flexbox or Grid when you need explicit item placement, equal card rows, or complex alignment—columns are for continuous flow, not component grids.

Columns fragment content automatically; control breaks with `break-inside`, `break-before`, and `break-after`.

## 🔧 Core concepts [#-core-concepts]

### Primary properties [#primary-properties]

| Property       | Role                                                  |
| -------------- | ----------------------------------------------------- |
| `column-count` | Ideal number of columns                               |
| `column-width` | Minimum comfortable column width; UA picks count      |
| `columns`      | Shorthand: `columns: <count> \|\| <width>`            |
| `column-gap`   | Gutters between columns (also `gap` in some contexts) |
| `column-rule`  | Vertical line between columns (`width style color`)   |
| `column-span`  | `all` lets a child span the full width                |
| `column-fill`  | `balance` (default in most UIs) \| `auto`             |

### Fragmentation controls [#fragmentation-controls]

| Property                       | Useful values                              |
| ------------------------------ | ------------------------------------------ |
| `break-inside`                 | `avoid` on headings, figures, cards        |
| `break-before` / `break-after` | `column`, `avoid-column`                   |
| `orphans` / `widows`           | Min lines left at bottom/top of a fragment |

### When to choose what [#when-to-choose-what]

| Need                  | Prefer                                 |
| --------------------- | -------------------------------------- |
| Flowing article text  | Multi-column                           |
| Card / gallery layout | Grid / Flex                            |
| Sidebar + main        | Grid / Flex                            |
| Masonry-like packing  | Grid (`masonry` where supported) or JS |

## 💡 Examples [#-examples]

### Responsive columns by width [#responsive-columns-by-width]

```css
.article-body {
  column-width: 18rem;
  column-gap: 2rem;
  column-rule: 1px solid color-mix(in oklab, CanvasText 15%, transparent);
  text-align: start;
}
```

### Fixed count with spanning heading [#fixed-count-with-spanning-heading]

```html
<section class="features">
  <h2 class="features__title">Highlights</h2>
  <p>…</p>
  <p>…</p>
</section>
```

```css
.features {
  columns: 3;
  column-gap: 1.5rem;
}

.features__title {
  column-span: all;
  margin-block-end: 1rem;
}
```

### Keep cards from splitting [#keep-cards-from-splitting]

```css
.card-list {
  columns: 2;
  column-gap: 1rem;
}

.card-list > .card {
  break-inside: avoid;
  margin-block-end: 1rem;
}
```

### Balance short content [#balance-short-content]

```css
.short-copy {
  columns: 2;
  column-fill: balance;
  max-block-size: 12rem; /* height can affect balancing */
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using multi-column for a grid of independent cards without `break-inside: avoid`, which splits cards awkwardly.
* Setting both a high `column-count` and a large `column-width` so columns become unreadably narrow on small screens.
* Expecting Flex/Grid-like alignment control—columns don’t offer `justify-content` per “cell.”
* Forgetting that `column-span: all` only works for in-flow children of the multicol container.
* Overusing vertical rules that clash with nested borders or dark themes—tint with `color-mix` and test contrast.

## 🔗 Related [#-related]

* [CSS Grid](/docs/css/grid)
* [Flexbox](/docs/css/flex)
* [Text](/docs/css/text)
* [Adaptive design](/docs/css/adaptive)


# Container Queries (/docs/css/container-queries)



# Container Queries [#container-queries]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Container queries style descendants based on a **container’s** size (or style), not the viewport. Perfect for reusable components that adapt in sidebars vs main columns. Define a containment context with `container-type` / `container-name`, then `@container`.

## 🔧 Core concepts [#-core-concepts]

* **Context**: `container-type: inline-size | size | normal` (plus `container-name`).
* **Shorthand**: `container: name / inline-size;`.
* **Query**: `@container (min-width: 400px) \{ ... \}` or `@container card (min-width: 400px)`.
* **Units**: `cqw` `cqh` `cqi` `cqb` `cqmin` `cqmax` relative to container.
* **Style queries**: `@container style(--variant: compact)` (support evolving).
* **vs media**: media = viewport/device; container = parent component width.

```css
.card {
  container-type: inline-size;
  container-name: card;
}
@container card (min-width: 36rem) {
  .card-inner {
    display: grid;
    grid-template-columns: 1fr 1fr;
  }
}
```

## 💡 Examples [#-examples]

```css
.sidebar,
.main {
  container: layout / inline-size;
}

.widget {
  padding: 1rem;
}
@container layout (max-width: 300px) {
  .widget {
    font-size: 0.9rem;
  }
  .widget .meta {
    display: none;
  }
}

/* Fluid based on container */
@container (min-width: 20rem) {
  .title {
    font-size: clamp(1rem, 4cqi, 1.5rem);
  }
}

/* Named vs nearest */
@container (min-width: 500px) {
  /* nearest ancestor container */
}

/* Grid of cards each querying themselves */
.grid > * {
  container-type: inline-size;
}
```

```css
/* Need size queries for height */
.panel {
  container-type: size;
  height: 200px;
}
@container (min-height: 180px) {
  .panel .extra {
    display: block;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `container-type` means `@container` won’t match as expected.
* `inline-size` is most common; `size` also applies block-size containment (may affect sizing).
* Containment can influence layout — test overflow/sticky inside containers.
* Nested containers: queries use the correct named/nearest context — name them when ambiguous.
* Older browsers need fallbacks — progressive enhancement with default single-column layouts.

## 🔗 Related [#-related]

* [media\_queries.md](/docs/css/media-queries) — viewport queries
* [grid.md](/docs/css/grid) — responsive grids
* [adaptive.md](/docs/css/adaptive) — responsive strategy
* [calc\_min\_max\_clamp.md](/docs/css/calc-min-max-clamp) — cqi units
* [nesting.md](/docs/css/nesting) — nest @container


# Cursor (/docs/css/cursor)



# Cursor [#cursor]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `cursor` property sets the mouse pointer appearance when hovering an element. It communicates interactivity (links, drag handles, resize edges) and system state (loading, not-allowed). Use it to reinforce affordances already present in markup and behavior—never as the only signal that something is clickable.

Touch devices often ignore cursor styles; always pair with clear visual design and adequate hit targets.

## 🔧 Core concepts [#-core-concepts]

### Common keyword values [#common-keyword-values]

| Value                  | Typical meaning               |
| ---------------------- | ----------------------------- |
| `auto` / `default`     | UA / arrow                    |
| `pointer`              | Link or button-like control   |
| `text`                 | Selectable text / inputs      |
| `move`                 | Draggable item                |
| `grab` / `grabbing`    | Grab affordance / active drag |
| `not-allowed`          | Action unavailable            |
| `wait` / `progress`    | Busy (blocking vs background) |
| `help`                 | Extra information available   |
| `crosshair`            | Precise selection             |
| `zoom-in` / `zoom-out` | Zoomable content              |

### Resize & edge cursors [#resize--edge-cursors]

| Value                                                     | Direction               |
| --------------------------------------------------------- | ----------------------- |
| `n-resize` `s-resize` `e-resize` `w-resize`               | Cardinal edges          |
| `ne-resize` `nw-resize` `se-resize` `sw-resize`           | Corners                 |
| `col-resize` / `row-resize`                               | Column / row separators |
| `ew-resize` / `ns-resize` / `nesw-resize` / `nwse-resize` | Bidirectional           |

### Custom images [#custom-images]

```css
.canvas {
  cursor: url("/cursors/pen.svg") 4 4, crosshair;
}
```

Syntax: `cursor: url(…) [x y], <fallback>`. Hotspot coordinates are optional; always provide a keyword fallback.

## 💡 Examples [#-examples]

### Interactive controls [#interactive-controls]

```css
a[href],
button:not(:disabled),
[role="button"]:not([aria-disabled="true"]) {
  cursor: pointer;
}

button:disabled,
[aria-disabled="true"] {
  cursor: not-allowed;
}
```

### Drag surface [#drag-surface]

```css
.draggable {
  cursor: grab;
}

.draggable:active,
.draggable.is-dragging {
  cursor: grabbing;
}
```

### Text vs chrome [#text-vs-chrome]

```css
.prose { cursor: auto; }
.prose code { cursor: text; }

.toolbar { cursor: default; }
.splitter { cursor: col-resize; }
```

### Loading overlay [#loading-overlay]

```css
.page.is-loading,
.page.is-loading * {
  cursor: progress;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Setting `cursor: pointer` on non-interactive elements without keyboard/semantics support misleads users.
* Omitting a fallback keyword after `url()` so broken custom cursors leave no pointer at all.
* Using `wait` for long operations that still allow interaction—prefer `progress` when the UI remains usable.
* Assuming cursor styles work on mobile; they usually don’t—design for touch without relying on them.
* Nesting conflicting cursors (`*` rules) so child controls never show `pointer` or `text`.

## 🔗 Related [#-related]

* [Buttons](/docs/css/button)
* [Hover](/docs/css/hover)
* [Text fields](/docs/css/textfield)
* [Effects](/docs/css/effects)


# Dark Mode (/docs/css/dark-mode)



# Dark Mode [#dark-mode]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Dark mode adapts UI colors for low-light preference or explicit theme toggles. Combine `prefers-color-scheme` with a class/`data-theme` override, CSS variables for tokens, and `color-scheme` for native form controls scrollbars.

## 🔧 Core concepts [#-core-concepts]

* **System**: `@media (prefers-color-scheme: dark)`.
* **Override**: `html[data-theme="dark"]` or `.dark` class (user choice).
* **`color-scheme: light dark`**: hints UA widgets.
* **Tokens**: redefine `--bg`, `--text`, `--border` per theme.
* **Images**: `picture` / CSS filters / separate assets for dark.
* **Meta**: `<meta name="color-scheme" content="light dark">`.

```css
:root {
  color-scheme: light dark;
  --bg: #fff;
  --text: #111;
}
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --bg: #121212;
    --text: #f2f2f2;
  }
}
html[data-theme="dark"] {
  --bg: #121212;
  --text: #f2f2f2;
}
body {
  background: var(--bg);
  color: var(--text);
}
```

## 💡 Examples [#-examples]

```css
/* Explicit light lock */
html[data-theme="light"] {
  color-scheme: light;
  --bg: #fff;
  --text: #111;
}

/* Soft surfaces */
:root {
  --surface: color-mix(in oklch, var(--bg) 92%, var(--text));
}

/* Avoid pure #000/#fff if harsh — use near-black */
html[data-theme="dark"] {
  --bg: oklch(18% 0.02 260);
  --text: oklch(95% 0.01 260);
  --accent: oklch(75% 0.14 250);
}

/* Dim images slightly in dark */
html[data-theme="dark"] img:not([data-keep]) {
  opacity: 0.92;
}
```

```js
const root = document.documentElement;
const stored = localStorage.getItem("theme");
if (stored) root.dataset.theme = stored;
toggle.onclick = () => {
  const next = root.dataset.theme === "dark" ? "light" : "dark";
  root.dataset.theme = next;
  localStorage.setItem("theme", next);
};
```

## ⚠️ Pitfalls [#️-pitfalls]

* Flash of wrong theme — set theme early (inline script in `<head>`).
* Shadows and borders need retuning — light shadows disappear on dark bg.
* Don’t invert entire pages with `filter: invert()` — breaks images/videos.
* Contrast still must meet WCAG — dark gray on black often fails.
* Third-party embeds may stay light — plan letterboxing.

## 🔗 Related [#-related]

* [variables.md](/docs/css/variables) — tokens
* [color\_functions.md](/docs/css/color-functions) — oklch palettes
* [media\_queries.md](/docs/css/media-queries) — prefers-\*
* [../Javascript/DOM/media\_query\_list.md](/docs/css/../javascript/dom/media-query-list) — matchMedia
* [print.md](/docs/css/print) — force light for print


# Effects (/docs/css/effects)



# Effects [#effects]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Visual effects in CSS include `filter`, `backdrop-filter`, `box-shadow`, `text-shadow`, `mix-blend-mode`, and `opacity`. Use them for depth, glassmorphism, emphasis, and image treatment without editing assets. Prefer compositing-friendly effects and keep heavy filters off scrolling, full-viewport layers when performance matters.

`filter` affects the element and its contents; `backdrop-filter` samples what is *behind* the element (requires semi-transparent background to see the result).

## 🔧 Core concepts [#-core-concepts]

### Filter functions [#filter-functions]

| Function                                 | Role                                                    |
| ---------------------------------------- | ------------------------------------------------------- |
| `blur(r)`                                | Gaussian blur                                           |
| `brightness()` `contrast()` `saturate()` | Tonal adjustments                                       |
| `grayscale()` `sepia()` `hue-rotate()`   | Color treatments                                        |
| `opacity()`                              | Filter-level opacity (separate from `opacity` property) |
| `drop-shadow()`                          | Shadow that follows alpha shape (unlike `box-shadow`)   |
| `url(#svgFilter)`                        | Custom SVG filter reference                             |

Chain with spaces: `filter: brightness(1.1) contrast(1.05)`.

### Shadows & blending [#shadows--blending]

| Property                | Notes                                                           |
| ----------------------- | --------------------------------------------------------------- |
| `box-shadow`            | Shape follows border box; can be inset; multiple layers allowed |
| `text-shadow`           | Glyph shadows; no inset                                         |
| `mix-blend-mode`        | Blend element with backdrop                                     |
| `background-blend-mode` | Blend background layers                                         |
| `isolation: isolate`    | Create stacking context to contain blend modes                  |
| `opacity`               | Affects entire element including descendants                    |

### Backdrop filter checklist [#backdrop-filter-checklist]

1. Element needs a transparent or translucent background.
2. Something visible must sit behind it.
3. Often creates a containing stacking context; test overflow/positioning.

## 💡 Examples [#-examples]

### Soft elevation [#soft-elevation]

```css
.card {
  background: Canvas;
  border-radius: 0.75rem;
  box-shadow:
    0 1px 2px rgb(0 0 0 / 0.06),
    0 8px 24px rgb(0 0 0 / 0.08);
}
```

### Frosted glass panel [#frosted-glass-panel]

```css
.glass {
  background: rgb(255 255 255 / 0.55);
  border: 1px solid rgb(255 255 255 / 0.4);
  backdrop-filter: blur(12px) saturate(1.2);
  -webkit-backdrop-filter: blur(12px) saturate(1.2);
}
```

### Image hover treatment [#image-hover-treatment]

```css
.thumb img {
  filter: grayscale(0.2) brightness(0.95);
  transition: filter 200ms ease;
}

.thumb:hover img,
.thumb:focus-within img {
  filter: grayscale(0) brightness(1);
}
```

### Drop shadow on transparent PNG/SVG [#drop-shadow-on-transparent-pngsvg]

```css
.logo {
  filter: drop-shadow(0 4px 8px rgb(0 0 0 / 0.25));
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Applying large `blur()` or `backdrop-filter` on huge layers tanks scroll performance—limit size and animate sparingly.
* Expecting `box-shadow` to follow irregular transparent image edges—use `drop-shadow()` in `filter` instead.
* Setting `opacity` on a parent fades all children; prefer alpha on `background-color` / borders when only the surface should fade.
* Forgetting vendor-prefixed `-webkit-backdrop-filter` where still required.
* Using `mix-blend-mode` without `isolation`, causing unexpected blends with page chrome.

## 🔗 Related [#-related]

* [Background](/docs/css/background)
* [Hover](/docs/css/hover)
* [Animation](/docs/css/animation)
* [Images](/docs/css/image)


# Filter & Backdrop Filter (/docs/css/filter-backdrop)



# Filter & Backdrop Filter [#filter--backdrop-filter]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`filter` applies graphical effects (blur, brightness, drop-shadow…) to an element’s rendering — including descendants. `backdrop-filter` filters what is **behind** the element (frosted glass). Both can be expensive; use sparingly.

## 🔧 Core concepts [#-core-concepts]

| Function                                 | Role                                     |
| ---------------------------------------- | ---------------------------------------- |
| `blur(r)`                                | Gaussian blur                            |
| `brightness()` `contrast()` `saturate()` | tonal                                    |
| `grayscale()` `sepia()` `hue-rotate()`   | color                                    |
| `opacity()`                              | similar to `opacity` prop                |
| `drop-shadow()`                          | shadow following alpha (vs `box-shadow`) |
| `url(#svgFilter)`                        | SVG filter reference                     |

* **Chain**: `filter: blur(4px) brightness(1.1);`
* **Backdrop**: needs (semi)transparent background to see effect.
* **Containing block / stacking**: filters create containing blocks / stacking contexts.

```css
.avatar {
  filter: grayscale(1);
}
.avatar:hover {
  filter: none;
}
.glass {
  background: rgb(255 255 255 / 0.5);
  backdrop-filter: blur(12px) saturate(1.2);
}
```

## 💡 Examples [#-examples]

```css
/* Image treatment */
.hero img {
  filter: brightness(0.7) contrast(1.05);
}

/* Icon recolor trick (simple) */
.icon {
  filter: invert(1);
}

/* Drop shadow on transparent PNG */
.logo {
  filter: drop-shadow(0 4px 8px rgb(0 0 0 / 0.35));
}

/* Modal frosted overlay content */
.dialog {
  background: oklch(100% 0 0 / 0.7);
  backdrop-filter: blur(16px);
  -webkit-backdrop-filter: blur(16px);
}

/* Performance: prefer transform/opacity for motion; filter for static looks */
```

```css
@media (prefers-reduced-motion: reduce) {
  .blur-on-scroll {
    filter: none;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `filter` on a parent blurs/repaints all descendants — isolate effects on leaf images when possible.
* `backdrop-filter` fails if no backdrop shows through (opaque bg) or browser lacks support — provide solid fallback bg.
* Creates a stacking context — can change `z-index` expectations.
* Animating heavy blurs is costly on low-end devices.
* `drop-shadow` ≠ `box-shadow` (follows alpha silhouette).

## 🔗 Related [#-related]

* [effects.md](/docs/css/effects) — shadows and visuals
* [transitions.md](/docs/css/transitions) — animating filters
* [background.md](/docs/css/background) — translucent backgrounds
* [z\_index.md](/docs/css/z-index) — stacking contexts
* [performance via blur](/docs/css/effects) — cost awareness


# Flexbox (/docs/css/flex)



# Flexbox [#flexbox]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Flexbox is a one-dimensional layout model for distributing space and aligning items along a row or column. Set `display: flex` or `inline-flex` on a container, then control direction, wrapping, alignment, and growth with flex properties. Use Flexbox for toolbars, navs, form rows, and equal-height media objects; use Grid when you need two-dimensional tracks or overlapping areas.

Main axis follows `flex-direction`; cross axis is perpendicular. Logical alignment (`start` / `end`) respects writing mode better than physical `left` / `right`.

## 🔧 Core concepts [#-core-concepts]

### Container properties [#container-properties]

| Property          | Common values                                                        | Role                    |
| ----------------- | -------------------------------------------------------------------- | ----------------------- |
| `flex-direction`  | `row` \| `row-reverse` \| `column` \| `column-reverse`               | Main axis               |
| `flex-wrap`       | `nowrap` \| `wrap` \| `wrap-reverse`                                 | Multi-line flex         |
| `flex-flow`       | shorthand of direction + wrap                                        |                         |
| `justify-content` | `start` `end` `center` `space-between` `space-around` `space-evenly` | Main-axis distribution  |
| `align-items`     | `stretch` `start` `end` `center` `baseline`                          | Cross-axis, one line    |
| `align-content`   | same family as justify                                               | Cross-axis when wrapped |
| `gap`             | `<row-gap> <column-gap>`                                             | Spacing between items   |

### Item properties [#item-properties]

| Property      | Role                                                             |
| ------------- | ---------------------------------------------------------------- |
| `flex-grow`   | Extra free space factor (default `0`)                            |
| `flex-shrink` | Shrink factor (default `1`)                                      |
| `flex-basis`  | Initial main size (`auto`, length, `%`, `content`)               |
| `flex`        | Shorthand: `grow shrink basis` — prefer `flex: 1` / `flex: none` |
| `align-self`  | Override `align-items` for one item                              |
| `order`       | Visual order (avoid for tab order / accessibility)               |

### Useful shorthand recipes [#useful-shorthand-recipes]

| Declaration       | Meaning                                        |
| ----------------- | ---------------------------------------------- |
| `flex: 1`         | `1 1 0%` — share space equally from zero basis |
| `flex: auto`      | `1 1 auto` — grow/shrink from content size     |
| `flex: none`      | `0 0 auto` — sized by content, don’t flex      |
| `flex: 0 0 12rem` | Fixed main size                                |

## 💡 Examples [#-examples]

### Toolbar [#toolbar]

```css
.toolbar {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  padding-inline: 1rem;
}

.toolbar__spacer {
  flex: 1;
}
```

### Media object [#media-object]

```css
.media {
  display: flex;
  gap: 1rem;
  align-items: flex-start;
}

.media__body {
  flex: 1;
  min-inline-size: 0; /* allow text truncation */
}
```

### Wrapping chip list [#wrapping-chip-list]

```css
.chips {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}
```

### Equal-height columns (row) [#equal-height-columns-row]

```css
.pricing {
  display: flex;
  gap: 1rem;
  align-items: stretch; /* default */
}

.pricing > .plan {
  flex: 1 1 0;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `min-inline-size: 0` (or `min-width: 0`) on flex children so long text overflows instead of shrinking.
* Using `order` to reshuffle content without updating DOM order—keyboard and screen-reader order stay source-based.
* Mixing `justify-content: space-between` with `gap` expectations; gap is fixed space between items, not a substitute for margins in every case.
* Default `flex-shrink: 1` unexpectedly crushing icons—set `flex: none` or `flex-shrink: 0` on fixed chrome.
* Choosing Flexbox for a full page 2D layout that Grid expresses more clearly with template areas.

## 🔗 Related [#-related]

* [CSS Grid](/docs/css/grid)
* [Adaptive design](/docs/css/adaptive)
* [Positioning](/docs/css/position)
* [Buttons](/docs/css/button)


# Fonts (/docs/css/font)



# Fonts [#fonts]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Font CSS controls typeface selection, weight, style, size, and loading behavior. Modern stacks combine system fonts, self-hosted files via `@font-face`, and variable fonts for continuous weight/width axes. Good typography sets a clear hierarchy, readable line length, and resilient fallbacks when webfonts are slow or blocked.

Prefer `font-display` strategies that avoid invisible text, and use logical sizing (`rem`, `clamp`) for scalable UIs.

## 🔧 Core concepts [#-core-concepts]

### Key properties [#key-properties]

| Property              | Role                                                                       |
| --------------------- | -------------------------------------------------------------------------- |
| `font-family`         | Ordered stack; last should be generic (`sans-serif`, `serif`, `monospace`) |
| `font-size`           | Absolute, relative, or fluid (`clamp`)                                     |
| `font-weight`         | `100`–`900`, `normal`, `bold`, or variable axis                            |
| `font-style`          | `normal` \| `italic` \| `oblique`                                          |
| `font-stretch`        | Width (`condensed` … `expanded`)                                           |
| `font-variant-*`      | Caps, numeric figures, ligatures                                           |
| `line-height`         | Unitless preferred for inheritance                                         |
| `font`                | Shorthand (order-sensitive)                                                |
| `font-optical-sizing` | `auto` \| `none` for optical size axis                                     |
| `font-synthesis`      | Control fake bold/italic                                                   |

### @font-face essentials [#font-face-essentials]

```css
@font-face {
  font-family: "InterVar";
  src:
    url("/fonts/InterVar.woff2") format("woff2-variations"),
    url("/fonts/InterVar.woff2") format("woff2");
  font-weight: 100 900;
  font-style: normal;
  font-display: swap;
  unicode-range: U+0000-00FF; /* optional subset */
}
```

| `font-display` | Behavior                                             |
| -------------- | ---------------------------------------------------- |
| `swap`         | Show fallback immediately, swap in webfont           |
| `optional`     | May skip webfont if not cached—great for performance |
| `block`        | Short block period, then swap                        |
| `fallback`     | Short block, short swap window                       |

### Generic families [#generic-families]

`serif`, `sans-serif`, `monospace`, `cursive`, `fantasy`, `system-ui`, `ui-sans-serif`, `ui-serif`, `ui-monospace`, `ui-rounded`, `emoji`, `math`, `fangsong`.

## 💡 Examples [#-examples]

### System stack [#system-stack]

```css
:root {
  --font-sans: system-ui, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
  --font-mono: ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, monospace;
}

body {
  font-family: var(--font-sans);
  font-size: 1rem;
  line-height: 1.5;
}
```

### Fluid type scale [#fluid-type-scale]

```css
h1 {
  font-size: clamp(1.75rem, 1.2rem + 2vw, 3rem);
  font-weight: 700;
  line-height: 1.15;
  letter-spacing: -0.02em;
}
```

### Variable font weight on hover [#variable-font-weight-on-hover]

```css
.nav-link {
  font-family: "InterVar", system-ui, sans-serif;
  font-weight: 500;
  transition: font-weight 120ms ease;
}

.nav-link:hover {
  font-weight: 700;
}
```

### Tabular numbers for data [#tabular-numbers-for-data]

```css
.numeric {
  font-variant-numeric: tabular-nums lining-nums;
  font-feature-settings: "tnum" 1;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Listing a webfont without a robust system fallback causes FOUT/FOIT layout jumps—match metrics or reserve space.
* Using `px` everywhere prevents user font-size preferences; prefer `rem` for UI text.
* Applying unitful `line-height` on parents so children inherit unexpected computed values—prefer unitless.
* Loading every weight/style file instead of one variable font increases bytes and requests.
* Setting `font-display: block` on body text, which can leave content invisible too long.

## 🔗 Related [#-related]

* [Text](/docs/css/text)
* [Icons](/docs/css/icon)
* [Buttons](/docs/css/button)
* [Adaptive design](/docs/css/adaptive)


# Getting Started with CSS (/docs/css/getting-started)



# Getting Started with CSS [#getting-started-with-css]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS (Cascading Style Sheets) controls how HTML looks: colors, spacing, layout, and responsive behavior. You select elements and declare properties inside rules.

## 🔧 Core concepts [#-core-concepts]

| Idea       | Meaning                               |
| ---------- | ------------------------------------- |
| Rule       | `selector \{ property: value; \}`     |
| Selector   | Which elements the rule targets       |
| Property   | What to change (`color`, `margin`, …) |
| Cascade    | How conflicting rules are resolved    |
| Stylesheet | A `.css` file or `<style>` block      |

Link CSS from HTML with `<link rel="stylesheet" href="styles.css" />`.

## 💡 Examples [#-examples]

**Inline link in HTML:**

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>CSS demo</title>
    <link rel="stylesheet" href="styles.css" />
  </head>
  <body>
    <h1 class="title">Hello, CSS</h1>
  </body>
</html>
```

**`styles.css`:**

```css
body {
  font-family: system-ui, sans-serif;
  margin: 2rem;
  background: #f6f7f9;
}

.title {
  color: #0f172a;
  font-size: 2rem;
}
```

**Quick experiment in a `<style>` tag:**

```html
<style>
  p {
    line-height: 1.5;
  }
</style>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Typos in property names fail silently (nothing happens).
* Specificity wars — prefer simple class selectors while learning.
* Browser default styles differ; a small reset/normalize helps later.
* Inline `style=""` attributes override stylesheets and are hard to maintain.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/css/hello-world)
* [selectors\_basics.md](/docs/css/selectors-basics)
* [cascade\_basics.md](/docs/css/cascade-basics)
* [box\_model\_basics.md](/docs/css/box-model-basics)


# Glossary (/docs/css/glossary)



# Glossary [#glossary]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core CSS terms for the cascade, box model, layout, selectors, and modern styling features.

## 🔧 Core concepts [#-core-concepts]

| Term             | Definition                                                                              |
| ---------------- | --------------------------------------------------------------------------------------- |
| At-rule          | A CSS statement starting with `@`, such as `@media` or `@keyframes`.                    |
| Box model        | The content, padding, border, and margin layers that size an element.                   |
| Cascade          | The algorithm that resolves conflicting declarations by origin, layer, and specificity. |
| Containing block | The ancestor box used as the reference for positioned layout.                           |
| Container query  | A rule that styles an element based on its container’s size, not the viewport.          |
| Declaration      | A property–value pair inside a rule, such as `color: red`.                              |
| Em               | A length relative to the element’s own computed font size.                              |
| Flexbox          | A one-dimensional layout model for aligning items in a row or column.                   |
| Grid             | A two-dimensional layout model of rows and columns.                                     |
| Inheritance      | Passing certain computed values from parent to child elements.                          |
| Keyframes        | Named animation frames defined with `@keyframes`.                                       |
| Logical property | Direction-relative properties like `margin-inline` instead of left/right.               |
| Media query      | A condition that applies styles based on device or viewport features.                   |
| Pseudo-class     | A selector state such as `:hover`, `:focus`, or `:nth-child`.                           |
| Pseudo-element   | A selector for generated parts such as `::before` or `::after`.                         |
| Rem              | A length relative to the root element’s font size.                                      |
| Rule set         | A selector plus its block of declarations.                                              |
| Selector         | The pattern that matches which elements a rule applies to.                              |
| Specificity      | A weight used to decide which competing selector wins.                                  |
| Stacking context | A local layering scope that controls how `z-index` paints.                              |
| Shorthand        | A property that sets multiple related longhands at once, like `margin`.                 |
| Transform        | A visual change such as translate, rotate, scale, or skew.                              |
| Transition       | Smooth interpolation of property changes over time.                                     |
| Variable         | A custom property declared with `--name` and read via `var()`.                          |
| Viewport         | The visible area of the page used by units like `vw` and `vh`.                          |
| Z-index          | A stacking order value within a stacking context.                                       |

## 💡 Examples [#-examples]

**Flexbox and variables:**

```css
:root {
  --gap: 1rem;
}
.row {
  display: flex;
  gap: var(--gap);
  align-items: center;
}
```

**Grid and media query:**

```css
.layout {
  display: grid;
  grid-template-columns: 1fr;
}
@media (min-width: 768px) {
  .layout {
    grid-template-columns: 240px 1fr;
  }
}
```

**Specificity and cascade layers:**

```css
@layer base, components;
@layer base {
  button { padding: 0.5rem; }
}
@layer components {
  .btn { padding: 1rem; }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **margin** (outside border) with **padding** (inside border).
* Mixing **flex** and **grid** goals — one axis vs two axes.
* Treating **pseudo-class** (`:hover`) like a **pseudo-element** (`::before`).
* Assuming higher **z-index** always wins — stacking contexts can trap layers.
* Equating **em** and **rem** — em is relative to the element; rem to the root.

## 🔗 Related [#-related]

* [box\_model](/docs/css/box-model)
* [flex](/docs/css/flex)
* [grid](/docs/css/grid)
* [specificity](/docs/css/specificity)
* [variables](/docs/css/variables)
* [media\_queries](/docs/css/media-queries)


# Gradients (/docs/css/gradient)



# Gradients [#gradients]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Gradients are images generated by CSS—usable anywhere `background-image` or `mask-image` accepts an image. The main types are linear, radial, conic, and their repeating variants. Use gradients for soft backgrounds, scrims over photos, progress fills, and decorative accents without exporting bitmap assets.

Modern color stops work well in `oklch` / `oklab` for perceptually even blends; `color-mix()` helps derive stop colors from tokens.

## 🔧 Core concepts [#-core-concepts]

### Gradient functions [#gradient-functions]

| Function                      | Shape                             |
| ----------------------------- | --------------------------------- |
| `linear-gradient()`           | Straight-line blend               |
| `radial-gradient()`           | From center (or position) outward |
| `conic-gradient()`            | Around a center (angles)          |
| `repeating-linear-gradient()` | Tiled linear pattern              |
| `repeating-radial-gradient()` | Tiled radial pattern              |
| `repeating-conic-gradient()`  | Tiled angular pattern             |

### Linear syntax [#linear-syntax]

```css
linear-gradient(
  [ to <side-or-corner> | <angle> ],
  <color-stop-list>
)
```

Examples: `to bottom`, `to top right`, `135deg`. Color stops: `color`, optional position (`30%`, `4rem`).

### Radial & conic [#radial--conic]

| Type   | Key options                                                                               |
| ------ | ----------------------------------------------------------------------------------------- |
| Radial | `circle` \| `ellipse`, size keywords (`closest-side`, `farthest-corner`), `at <position>` |
| Conic  | `from <angle>`, `at <position>`, stops by angle (`0deg`, `25%`)                           |

### Multiple layers [#multiple-layers]

Gradients stack like any background images—list them first for overlays, solid color last as fallback.

## 💡 Examples [#-examples]

### Soft page wash [#soft-page-wash]

```css
body {
  background-color: oklch(0.98 0.01 100);
  background-image: linear-gradient(
    160deg,
    oklch(0.95 0.03 250),
    oklch(0.98 0.01 100) 45%,
    oklch(0.96 0.03 40)
  );
  background-attachment: fixed;
}
```

### Image scrim [#image-scrim]

```css
.hero {
  background:
    linear-gradient(to top, rgb(0 0 0 / 0.75), transparent 55%),
    url("/hero.jpg") center / cover no-repeat;
}
```

### Conic chart / progress ring base [#conic-chart--progress-ring-base]

```css
.pie {
  inline-size: 8rem;
  block-size: 8rem;
  border-radius: 50%;
  background: conic-gradient(
    oklch(0.6 0.18 250) 0 72%,
    oklch(0.9 0.02 250) 0
  );
}
```

### Striped repeating pattern [#striped-repeating-pattern]

```css
.stripes {
  background-image: repeating-linear-gradient(
    -45deg,
    transparent,
    transparent 6px,
    rgb(0 0 0 / 0.06) 6px,
    rgb(0 0 0 / 0.06) 12px
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hard-coding `left`/`right` in gradients for i18n UIs—prefer `to inline-end` where supported, or logical design tokens.
* Using too many stops in sRGB that band or look muddy—try `oklch` stops for smoother ramps.
* Forgetting a solid `background-color` underneath for print, email, or failed paint.
* Animating gradient stop positions poorly (often not interpolatable)—animate `opacity` / overlays instead.
* Applying huge fixed gradients on `body` with `background-attachment: fixed` on low-end mobile GPUs.

## 🔗 Related [#-related]

* [Background](/docs/css/background)
* [Effects](/docs/css/effects)
* [Images](/docs/css/image)
* [Buttons](/docs/css/button)


# CSS Grid (/docs/css/grid)



# CSS Grid [#css-grid]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS Grid is a two-dimensional layout system for rows and columns. Define tracks on a container with `grid-template-*`, place items with line-based or area-based positioning, and control gaps and alignment. Use Grid for page shells, card galleries, dashboards, and any UI where rows and columns interact. Prefer Flexbox for simple one-axis distribution inside a grid cell.

Subgrid (`grid-template-*: subgrid`) lets nested grids inherit parent tracks for aligned columns across components.

## 🔧 Core concepts [#-core-concepts]

### Container properties [#container-properties]

| Property                            | Role                                                 |
| ----------------------------------- | ---------------------------------------------------- |
| `display: grid` \| `inline-grid`    | Establish grid formatting context                    |
| `grid-template-columns` / `rows`    | Track list (`fr`, `px`, `%`, `minmax()`, `repeat()`) |
| `grid-template-areas`               | Named rectangular areas                              |
| `grid-auto-columns` / `rows`        | Implicit track sizing                                |
| `grid-auto-flow`                    | `row` \| `column` \| `dense`                         |
| `gap` / `row-gap` / `column-gap`    | Gutters                                              |
| `justify-items` / `align-items`     | Default cell alignment                               |
| `justify-content` / `align-content` | Tracks inside the container                          |
| `place-items` / `place-content`     | Shorthands                                           |

### Item properties [#item-properties]

| Property                      | Role                                 |
| ----------------------------- | ------------------------------------ |
| `grid-column` / `grid-row`    | Line start / end (`1 / 3`, `span 2`) |
| `grid-area`                   | Area name or four-line shorthand     |
| `justify-self` / `align-self` | Per-item alignment                   |
| `order`                       | Visual order (use carefully)         |

### Track sizing functions [#track-sizing-functions]

| Function                                             | Use                            |
| ---------------------------------------------------- | ------------------------------ |
| `fr`                                                 | Share free space               |
| `minmax(min, max)`                                   | Flexible bounds                |
| `repeat(n, …)` / `repeat(auto-fit, …)` / `auto-fill` | Patterns                       |
| `fit-content()`                                      | Clamp to content up to a limit |
| `min-content` / `max-content` / `auto`               | Content-based tracks           |

## 💡 Examples [#-examples]

### Responsive card gallery [#responsive-card-gallery]

```css
.gallery {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 16rem), 1fr));
  gap: 1rem;
}
```

### Holy grail with areas [#holy-grail-with-areas]

```css
.page {
  display: grid;
  grid-template-columns: 12rem 1fr 12rem;
  grid-template-rows: auto 1fr auto;
  grid-template-areas:
    "header header header"
    "nav    main   aside"
    "footer footer footer";
  min-block-size: 100dvh;
  gap: 1rem;
}

.header { grid-area: header; }
.nav    { grid-area: nav; }
.main   { grid-area: main; }
.aside  { grid-area: aside; }
.footer { grid-area: footer; }

@media (max-width: 48rem) {
  .page {
    grid-template-columns: 1fr;
    grid-template-areas:
      "header"
      "nav"
      "main"
      "aside"
      "footer";
  }
}
```

### Span and dense packing [#span-and-dense-packing]

```css
.board {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  grid-auto-flow: dense;
  gap: 0.5rem;
}

.board .wide {
  grid-column: span 2;
}
```

### Align within cells [#align-within-cells]

```css
.cell-center {
  display: grid;
  place-items: center;
  min-block-size: 10rem;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using only fixed `px` columns that overflow small viewports—prefer `minmax` + `auto-fit`/`fr`.
* Confusing `auto-fit` (collapses empty tracks) with `auto-fill` (keeps empty tracks).
* Forgetting that percentage row heights need a definite container block size.
* Over-nesting grids when one template + areas would suffice.
* Relying on `order` or visual placement that diverges from DOM order for keyboard users.

## 🔗 Related [#-related]

* [Flexbox](/docs/css/flex)
* [Adaptive design](/docs/css/adaptive)
* [Positioning](/docs/css/position)
* [Multi-column layout](/docs/css/column)


# :has() Selector (/docs/css/has-selector)



# :has() Selector [#has-selector]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`:has()` is a relational pseudo-class: select a parent (or earlier sibling context) based on descendants/siblings matching a selector. Enables “parent of” styling long missing from CSS — form validation UI, cards with images, and conditional layouts without JS.

## 🔧 Core concepts [#-core-concepts]

* **Form**: `parent:has(child-selector)`.
* **Relative selectors**: `:has(> img)`, `:has(+ .error)`, `:has(.icon)`.
* **Specificity**: contributes the most specific selector in its argument list.
* **Forgiving vs not**: invalid selectors inside may drop the whole `:has` in some cases — keep args valid.
* **Performance**: powerful; avoid extremely broad `:has(*)` on huge documents.
* **Use with `:is`/`:not`**: `label:not(:has(:checked))`.

```css
.card:has(img) {
  display: grid;
  grid-template-columns: 8rem 1fr;
}
label:has(:invalid) {
  color: crimson;
}
```

## 💡 Examples [#-examples]

```css
/* Field error when control invalid */
.field:has(:user-invalid) {
  border-color: crimson;
}
.field:has(:user-invalid) .hint {
  display: block;
}

/* Nav current section style via fragment targets — example */
section:has(:target) {
  outline: 1px solid var(--accent);
}

/* Empty-ish cards */
.card:not(:has(.body:not(:empty))) {
  opacity: 0.7;
}

/* Sibling previous — style label when input focused */
.field:has(:focus-visible) > .label {
  color: var(--accent);
}

/* Grid: featured when contains badge */
.item:has(.badge-featured) {
  grid-column: span 2;
}

/* Checkbox tree */
.tree li:has(> ul) > .twisty::before {
  content: "▾";
}
```

```css
/* Media layout */
article:has(> figure) {
  max-width: 70rem;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Not a substitute for accessibility — still need proper structure/ARIA.
* Can be costly if used everywhere with deep descendant selectors — scope tightly.
* Specificity surprises when arguments include IDs.
* Older browsers lack `:has` — provide acceptable non-`:has` fallbacks.
* `:has` does not “look up” forever without a subject — the subject is the element before `:has`.

## 🔗 Related [#-related]

* [selectors.md](/docs/css/selectors) — selector overview
* [pseudo\_classes.md](/docs/css/pseudo-classes) — other states
* [specificity.md](/docs/css/specificity) — scoring
* [nesting.md](/docs/css/nesting) — nested :has
* [forms via CSS](/docs/css/pseudo-classes) — :user-invalid


# Hello World (/docs/css/hello-world)



# Hello World [#hello-world]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS Hello World usually means styling a heading or page background so you can see a visible change. If the look updates when you refresh, your stylesheet is connected correctly.

## 🔧 Core concepts [#-core-concepts]

| Piece             | Role                             |
| ----------------- | -------------------------------- |
| Selector          | Targets `h1`, `.class`, `#id`, … |
| Declaration       | `property: value;`               |
| Declaration block | `\{ ... \}`                      |
| External CSS      | Best default for learning        |

Change one obvious property first (color or background) to verify the link.

## 💡 Examples [#-examples]

**HTML + CSS pair:**

```html
<!-- index.html -->
<h1>Hello, World!</h1>
```

```css
/* styles.css */
h1 {
  color: darkslateblue;
  text-align: center;
}
```

**Background and body text:**

```css
body {
  background-color: #fff7ed;
  color: #1c1917;
  font-family: Georgia, serif;
}
```

**Class-based hello:**

```html
<p class="hello">Hello, World!</p>
```

```css
.hello {
  font-size: 1.5rem;
  letter-spacing: 0.02em;
}
```

**DevTools tip:** right-click the element → Inspect → watch which rules apply.

## ⚠️ Pitfalls [#️-pitfalls]

* Wrong path in `<link href="...">` means no styles — check the Network tab.
* Caching can hide changes — hard refresh if needed.
* `colour` is invalid; use `color` (American spelling in CSS).
* Styling `html` vs `body` height differently can confuse full-page backgrounds.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/css/getting-started)
* [selectors\_basics.md](/docs/css/selectors-basics)
* [cascade\_basics.md](/docs/css/cascade-basics)
* [box\_model\_basics.md](/docs/css/box-model-basics)


# Hover (/docs/css/hover)



# Hover [#hover]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Hover styles respond when a pointing device is over an element (`:hover`). They provide previews, affordance, and progressive disclosure—but they are unreliable on touchscreens and unavailable to keyboard-only users unless mirrored with `:focus-visible` / `:focus-within`. Use hover for enhancement, not for the only path to critical UI.

Feature-query with `@media (hover: hover)` when hover-only behavior would confuse touch users.

## 🔧 Core concepts [#-core-concepts]

### Selectors & companions [#selectors--companions]

| Selector                 | Role                                 |
| ------------------------ | ------------------------------------ |
| `:hover`                 | Pointer over element                 |
| `:focus-visible`         | Keyboard-style focus                 |
| `:focus-within`          | Focus inside a parent (menus, cards) |
| `:active`                | Pressed state                        |
| `@media (hover: hover)`  | Primary input can hover              |
| `@media (pointer: fine)` | Precise pointer (mouse)              |

### Typical properties to change [#typical-properties-to-change]

| Category  | Examples                                    |
| --------- | ------------------------------------------- |
| Color     | `color`, `background-color`, `border-color` |
| Elevation | `box-shadow`, `translate`                   |
| Emphasis  | `opacity`, `filter`, `text-decoration`      |
| Motion    | `transform`, `transition`                   |

Keep transitions short (100–200ms) for UI chrome; longer for decorative motion.

### Safe pattern [#safe-pattern]

```css
.card {
  transition: transform 160ms ease, box-shadow 160ms ease;
}

@media (hover: hover) and (pointer: fine) {
  .card:hover {
    transform: translateY(-2px);
    box-shadow: 0 8px 24px rgb(0 0 0 / 0.12);
  }
}

.card:focus-within {
  outline: 2px solid Highlight;
  outline-offset: 2px;
}
```

## 💡 Examples [#-examples]

### Link underline reveal [#link-underline-reveal]

```css
.prose a {
  color: inherit;
  text-decoration-color: transparent;
  text-underline-offset: 0.2em;
  transition: text-decoration-color 150ms ease;
}

.prose a:hover,
.prose a:focus-visible {
  text-decoration-color: currentColor;
}
```

### Icon button feedback [#icon-button-feedback]

```css
.icon-btn {
  background: transparent;
  border-radius: 0.5rem;
  transition: background-color 120ms ease;
}

.icon-btn:hover {
  background: color-mix(in oklab, CanvasText 8%, transparent);
}

.icon-btn:active {
  background: color-mix(in oklab, CanvasText 14%, transparent);
}
```

### Show action affordances on card [#show-action-affordances-on-card]

```css
.card .actions {
  opacity: 0;
  transition: opacity 150ms ease;
}

.card:hover .actions,
.card:focus-within .actions {
  opacity: 1;
}
```

### Disable sticky-hover traps on touch [#disable-sticky-hover-traps-on-touch]

```css
@media (hover: none) {
  .tooltip[data-show-on-hover] {
    display: none;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hiding essential controls only behind `:hover` so touch and keyboard users never see them.
* Leaving “stuck” hover styles on touch devices after tap—gate with `(hover: hover)`.
* Animating expensive properties (`width`, `top`, large `filter`) on every hover.
* Removing focus outlines and only styling `:hover`, which fails keyboard navigation.
* Nesting hover rules that fight (`parent:hover child` vs `child:hover`) and cause flicker.

## 🔗 Related [#-related]

* [Buttons](/docs/css/button)
* [Cursor](/docs/css/cursor)
* [Animation](/docs/css/animation)
* [Effects](/docs/css/effects)


# Icons (/docs/css/icon)



# Icons [#icons]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Icons in CSS-driven UIs are usually inline SVG, icon fonts, or mask/background images. Inline SVG is preferred for accessibility, theming via `currentColor`, and crisp scaling. Style icons to align with text, inherit color, and keep decorative icons hidden from assistive tech with `aria-hidden="true"`.

Treat icon size as a design token (`1em` or fixed rem) so icons scale with surrounding type when appropriate.

## 🔧 Core concepts [#-core-concepts]

### Delivery techniques [#delivery-techniques]

| Technique               | Pros                                  | Cons                         |
| ----------------------- | ------------------------------------- | ---------------------------- |
| Inline SVG              | Colorable, accessible, CSS-targetable | Markup weight if not sprited |
| `<img src="*.svg">`     | Simple caching                        | Harder to recolor            |
| CSS `mask-image`        | Recolor with `background-color`       | Needs careful sizing         |
| Icon font               | Easy swap                             | Ligature/a11y pitfalls, FOIT |
| Sprite / symbol `<use>` | Deduplicates paths                    | Cross-origin/`use` quirks    |

### Alignment & sizing [#alignment--sizing]

| Property / tip                     | Why                        |
| ---------------------------------- | -------------------------- |
| `inline-size` / `block-size`       | Explicit box               |
| `flex-shrink: 0`                   | Prevent crush in flex rows |
| `vertical-align: -0.125em`         | Optical align with text    |
| `display: block` on SVG in buttons | Remove baseline gap        |

### Theming with currentColor [#theming-with-currentcolor]

```css
.icon {
  inline-size: 1.25rem;
  block-size: 1.25rem;
  fill: currentColor; /* or stroke for outline icons */
}
```

Parent `color` then drives the icon.

## 💡 Examples [#-examples]

### Button with inline SVG [#button-with-inline-svg]

```html
<button type="button" class="btn">
  <svg class="icon" aria-hidden="true" focusable="false" viewBox="0 0 24 24">
    <path d="…" />
  </svg>
  Download
</button>
```

```css
.btn {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
}

.icon {
  inline-size: 1.125rem;
  block-size: 1.125rem;
  fill: currentColor;
  flex-shrink: 0;
}
```

### Mask-based icon [#mask-based-icon]

```css
.icon-mask {
  display: inline-block;
  inline-size: 1.25rem;
  block-size: 1.25rem;
  background-color: currentColor;
  mask: url("/icons/check.svg") center / contain no-repeat;
  -webkit-mask: url("/icons/check.svg") center / contain no-repeat;
}
```

### Optical alignment in text [#optical-alignment-in-text]

```css
.with-icon {
  display: inline-flex;
  align-items: center;
  gap: 0.35em;
}

.with-icon .icon {
  inline-size: 1em;
  block-size: 1em;
}
```

### Standalone icon button (accessible name) [#standalone-icon-button-accessible-name]

```html
<button type="button" class="icon-btn" aria-label="Close">
  <svg class="icon" aria-hidden="true" focusable="false">…</svg>
</button>
```

```css
.icon-btn {
  display: inline-grid;
  place-items: center;
  inline-size: 2.5rem;
  block-size: 2.5rem;
  padding: 0;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using icon fonts with ligature text that screen readers announce as random letters—prefer SVG + accessible names.
* Leaving SVG focusable in some browsers without `focusable="false"` inside buttons.
* Scaling icons with only `font-size` on icon fonts while stroke widths look uneven—prefer SVG.
* Crushing icons in flex layouts without `flex-shrink: 0`.
* Decorative icons without `aria-hidden` that add noise to the accessibility tree.

## 🔗 Related [#-related]

* [Buttons](/docs/css/button)
* [Images](/docs/css/image)
* [Fonts](/docs/css/font)
* [Flexbox](/docs/css/flex)


# Images (/docs/css/image)



# Images [#images]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS for images covers how replaced elements (`<img>`, `<picture>`, `object-fit` containers, and background images) size, crop, and align. Content images belong in HTML (`<img>` / `<picture>`) for semantics, alt text, and lazy loading; CSS then controls layout fit. Use `object-fit` and `object-position` for consistent crops in fixed frames, and modern formats (`avif`, `webp`) via `<picture>` or `image-set()`.

Always reserve space (width/height attributes or aspect-ratio) to reduce layout shift.

## 🔧 Core concepts [#-core-concepts]

### Sizing & fitting [#sizing--fitting]

| Property                | Role                                                     |
| ----------------------- | -------------------------------------------------------- |
| `max-inline-size: 100%` | Prevent overflow in fluid layouts                        |
| `block-size: auto`      | Preserve intrinsic ratio with width                      |
| `aspect-ratio`          | Explicit box ratio before load                           |
| `object-fit`            | `fill` \| `contain` \| `cover` \| `none` \| `scale-down` |
| `object-position`       | Crop anchor (`center`, `top`, percentages)               |
| `image-rendering`       | `auto` \| `crisp-edges` \| `pixelated`                   |

### Responsive sources (HTML + CSS) [#responsive-sources-html--css]

| Tool                     | Use                          |
| ------------------------ | ---------------------------- |
| `srcset` + `sizes`       | Resolution / width switching |
| `<picture>` + `<source>` | Art direction / format       |
| `image-set()`            | CSS background candidates    |

### Decorative vs content [#decorative-vs-content]

| Kind       | Approach                                                            |
| ---------- | ------------------------------------------------------------------- |
| Content    | `<img alt="…">`                                                     |
| Decorative | Empty `alt` or CSS background; don’t rely on background for meaning |

## 💡 Examples [#-examples]

### Fluid content image [#fluid-content-image]

```css
.content img {
  max-inline-size: 100%;
  block-size: auto;
  border-radius: 0.5rem;
}
```

### Cover crop in a fixed frame [#cover-crop-in-a-fixed-frame]

```css
.avatar {
  inline-size: 3rem;
  block-size: 3rem;
  border-radius: 50%;
  overflow: hidden;
}

.avatar img {
  inline-size: 100%;
  block-size: 100%;
  object-fit: cover;
  object-position: center;
}
```

### Aspect-ratio placeholder [#aspect-ratio-placeholder]

```css
.media-frame {
  aspect-ratio: 16 / 9;
  background: color-mix(in oklab, CanvasText 6%, Canvas);
}

.media-frame > img {
  inline-size: 100%;
  block-size: 100%;
  object-fit: cover;
}
```

### Picture art direction (markup) [#picture-art-direction-markup]

```html
<picture>
  <source media="(min-width: 64rem)" srcset="/hero-wide.avif" type="image/avif" />
  <source media="(min-width: 64rem)" srcset="/hero-wide.webp" type="image/webp" />
  <img src="/hero-square.jpg" width="800" height="800" alt="Product on a desk" />
</picture>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Omitting width/height or `aspect-ratio`, causing Cumulative Layout Shift as images load.
* Using `background-image` for meaningful pictures—no alt text, harder to print/save.
* Applying `object-fit: cover` without controlling `object-position`, cropping faces badly.
* Setting only `width: 100%` with a fixed height and default `object-fit: fill`, which distorts.
* Serving huge desktop assets to mobile without `srcset`/`sizes` or compressed formats.

## 🔗 Related [#-related]

* [Background](/docs/css/background)
* [Icons](/docs/css/icon)
* [Scale](/docs/css/scale)
* [Effects](/docs/css/effects)


# CSS (/docs/css)



# CSS [#css]

Layout, cascade, modern CSS.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Logical Properties (/docs/css/logical-properties)



# Logical Properties [#logical-properties]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Logical properties use **flow-relative** directions (`inline`/`block`, `start`/`end`) instead of physical `left`/`right`/`top`/`bottom`. They adapt automatically to writing modes and direction (`ltr`/`rtl`, vertical text). Prefer them for margins, padding, borders, and positioning in global UIs.

## 🔧 Core concepts [#-core-concepts]

| Physical             | Logical                                     |
| -------------------- | ------------------------------------------- |
| `width` / `height`   | `inline-size` / `block-size`                |
| `min-width`          | `min-inline-size`                           |
| `margin-left/right`  | `margin-inline-start/end` / `margin-inline` |
| `padding-top/bottom` | `padding-block`                             |
| `border-left`        | `border-inline-start`                       |
| `left` / `right`     | `inset-inline-start/end`                    |
| `text-align: left`   | `text-align: start`                         |

* **Inline axis**: text flow direction; **block axis**: stacking of lines/paragraphs.
* **Shorthands**: `margin-inline`, `padding-block`, `inset: block-start inline-end …`, `border-inline`.
* **Writing mode**: `writing-mode`, `direction`, `unicode-bidi`.

```css
.card {
  margin-inline: auto;
  padding-block: 1rem;
  padding-inline: 1.25rem;
  border-inline-start: 4px solid var(--accent);
  max-inline-size: 60ch;
}
```

## 💡 Examples [#-examples]

```css
/* Absolute pin */
.badge {
  position: absolute;
  inset-block-start: 0.5rem;
  inset-inline-end: 0.5rem;
}

/* RTL-friendly nav */
.nav {
  display: flex;
  gap: 1rem;
  padding-inline: 1rem;
}
.nav .icon {
  margin-inline-end: 0.5rem;
}

/* Logical borders radius (modern) */
.panel {
  border-start-start-radius: 8px;
  border-start-end-radius: 8px;
}

/* Scroll padding */
.scroller {
  scroll-padding-block-start: 4rem;
}
```

```css
/* Mixed: physical still OK for shadows/art direction */
.hero {
  background-position: right top; /* intentional art */
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing physical and logical on the same edge is confusing — pick one system per component.
* Older browsers may lack some logical radius/inset properties — check targets.
* `left` in animations/tooling may not map 1:1 when converting — test RTL.
* Transforms like `translateX` are still physical — use logical translations carefully (`translate: auto` evolving).
* Third-party CSS often physical — isolate overrides.

## 🔗 Related [#-related]

* [box\_model.md](/docs/css/box-model) — box edges
* [position.md](/docs/css/position) — inset
* [text.md](/docs/css/text) — alignment
* [flex.md](/docs/css/flex) — start/end alignment
* [adaptive.md](/docs/css/adaptive) — i18n layouts


# Media Queries (/docs/css/media-queries)



# Media Queries [#media-queries]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`@media` applies styles based on device/viewport characteristics: width, hover capability, color scheme, resolution, and more. Use them for layout breakpoints and accessibility preferences. Prefer mobile-first `min-width` queries and modern ranges.

## 🔧 Core concepts [#-core-concepts]

* **Syntax**: `@media (condition) \{ ... \}` / `@media screen and (...)`.
* **Width**: `(min-width: 48rem)`, range `(width >= 48rem)`, `(48rem &lt;= width &lt;= 80rem)`.
* **Preferences**: `prefers-color-scheme`, `prefers-reduced-motion`, `prefers-contrast`.
* **Pointer/hover**: `(hover: hover)`, `(pointer: fine|coarse)`.
* **Display**: `print`, `screen`, `(display-mode: standalone)`.
* **Script**: `matchMedia` mirrors the same queries in JS.

```css
.card {
  display: grid;
  gap: 1rem;
}
@media (min-width: 40rem) {
  .card {
    grid-template-columns: 1fr 1fr;
  }
}
@media (prefers-reduced-motion: reduce) {
  * {
    animation: none !important;
    transition: none !important;
  }
}
```

## 💡 Examples [#-examples]

```css
/* Mobile first */
.nav {
  flex-direction: column;
}
@media (width >= 64rem) {
  .nav {
    flex-direction: row;
  }
}

/* Range */
@media (30rem <= width <= 60rem) {
  .side {
    display: none;
  }
}

/* Interaction */
@media (hover: hover) and (pointer: fine) {
  .tile:hover {
    transform: translateY(-2px);
  }
}

/* Dark */
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #111;
  }
}

/* High DPI assets often via picture/srcset; CSS: */
@media (resolution >= 2dppx) {
  .icon {
    background-size: 50%;
  }
}

/* Container queries for components — see container_queries.md */
```

```css
/* Avoid too many breakpoints — design fluidly first */
```

## ⚠️ Pitfalls [#️-pitfalls]

* Desktop-first `max-width` stacks get messy — prefer `min-width` progression.
* `em`/`rem` in queries refer to initial font size, not element-local rem in some engines — know your units.
* Hover styles on touch devices can stick — gate with `(hover: hover)`.
* Don’t hide critical content only on “mobile” queries — responsive ≠ removed.
* Overlapping conflicting breakpoints cause hard-to-trace bugs — keep a scale.

## 🔗 Related [#-related]

* [container\_queries.md](/docs/css/container-queries) — component queries
* [dark\_mode.md](/docs/css/dark-mode) — color scheme
* [print.md](/docs/css/print) — print media
* [adaptive.md](/docs/css/adaptive) — responsive patterns
* [../Javascript/DOM/media\_query\_list.md](/docs/css/../javascript/dom/media-query-list) — JS API


# Nesting (/docs/css/nesting)



# Nesting [#nesting]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Native CSS nesting lets you write nested rules and at-rules like Sass, without a preprocessor. Use `&` for the parent selector. Keep nesting shallow for readability and specificity control.

## 🔧 Core concepts [#-core-concepts]

* **Nested style rule**: a rule inside another; must usually start with `&` or a nesting selector when ambiguous.
* **`&`**: parent reference — `.card \{ &:hover \{\} \}` → `.card:hover`.
* **Combinators**: `& > .child`, `& + &`, `& .desc`.
* **At-rules**: nest `@media`, `@supports`, `@layer`, `@container`.
* **Specificity**: nested selectors concatenate — still counts as written.
* **Declarations**: may mix with nested rules; modern parsers allow declarations first or interleaved (browser-dependent historically — prefer declarations then nests).

```css
.card {
  padding: 1rem;
  & h2 {
    margin: 0;
  }
  &:hover {
    box-shadow: 0 4px 12px rgb(0 0 0 / 0.1);
  }
  @media (min-width: 40rem) {
    padding: 1.5rem;
  }
}
```

## 💡 Examples [#-examples]

```css
.nav {
  display: flex;
  & ul {
    display: flex;
    gap: 1rem;
    list-style: none;
  }
  & a {
    color: inherit;
    text-decoration: none;
    &:focus-visible {
      outline: 2px solid var(--accent);
    }
  }
}

/* BEM-ish without repetition */
.btn {
  border: 0;
  &--primary {
    background: var(--accent);
  }
  &__icon {
    margin-inline-end: 0.5rem;
  }
}

/* :is wrapping */
.prose {
  & :is(h1, h2, h3) {
    line-height: 1.2;
  }
}

/* Nested container */
.widget {
  container-type: inline-size;
  @container (min-width: 20rem) {
    & .meta {
      display: flex;
    }
  }
}
```

```css
/* Invalid without & in some cases for starting type selectors — use & */
.card {
  & table {
  } /* good */
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Deep nesting (`& & & &`) recreates specificity hell — limit to 2–3 levels.
* Forgetting `&` can make selectors mean something else or be invalid.
* Output selector list can explode with `:is` — inspect DevTools.
* Mixing preprocessors + native nesting can double-process — pick one pipeline.
* Older browsers need PostCSS nesting plugin — know your baseline.

## 🔗 Related [#-related]

* [selectors.md](/docs/css/selectors) — selector grammar
* [specificity.md](/docs/css/specificity) — weights
* [media\_queries.md](/docs/css/media-queries) — nested media
* [container\_queries.md](/docs/css/container-queries) — nested @container
* [cascade\_layers.md](/docs/css/cascade-layers) — @layer


# Object Fit (/docs/css/object-fit)



# Object Fit [#object-fit]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`object-fit` and `object-position` control how replaced content (`img`, `video`, `canvas`) fills its box when the aspect ratios differ. Use with fixed sizes or `aspect-ratio` for consistent media frames without distortion (unless you choose `fill`).

## 🔧 Core concepts [#-core-concepts]

| `object-fit` | Behavior                                |
| ------------ | --------------------------------------- |
| `fill`       | stretch to box (default for some cases) |
| `contain`    | letterbox — entire media visible        |
| `cover`      | crop — fill box, preserve ratio         |
| `none`       | intrinsic size                          |
| `scale-down` | none or contain, whichever is smaller   |

* **`object-position`**: `center`, `top`, `25% 75%`, logical positions evolving.
* Applies to **replaced elements**, not background images (`background-size` instead).

```css
.thumb {
  width: 100%;
  aspect-ratio: 1;
  object-fit: cover;
  object-position: center;
}
```

## 💡 Examples [#-examples]

```css
/* Hero video */
.hero video {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

/* Logo without crop */
.logo {
  width: 160px;
  height: 64px;
  object-fit: contain;
}

/* Avatar */
.avatar {
  width: 3rem;
  height: 3rem;
  border-radius: 50%;
  object-fit: cover;
  object-position: top;
}

/* Prefer cover in cards, contain in galleries of diagrams */
.diagram {
  object-fit: contain;
  background: #f4f4f4;
}

/* Pair with aspect-ratio wrapper */
.frame {
  aspect-ratio: 16 / 9;
}
.frame > img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}
```

```html
<img src="photo.jpg" alt="" width="800" height="600" />
```

## ⚠️ Pitfalls [#️-pitfalls]

* Without an explicit box size (or both dimensions), `object-fit` has nothing to fit into.
* `fill` distorts — rarely what you want for photos.
* Background images use different properties — don’t confuse with `object-*`.
* Focal point cropping may need `object-position` or art-direction (`<picture>`).
* Accessibility: cropped faces can remove important content — choose position carefully.

## 🔗 Related [#-related]

* [aspect\_ratio.md](/docs/css/aspect-ratio) — ratio boxes
* [image.md](/docs/css/image) — image CSS
* [background.md](/docs/css/background) — background-size
* [../Html/images.md](/docs/css/../html/images) — img element
* [../Html/picture\_source.md](/docs/css/../html/picture-source) — art direction


# Overflow (/docs/css/overflow)



# Overflow [#overflow]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`overflow` controls how content that doesn’t fit a box is handled: visible, clipped, or scrollable. Logical longhands and `overflow-wrap` / `text-overflow` handle text. Overflow values other than `visible` often create scroll containers and affect sticky/margin collapse.

## 🔧 Core concepts [#-core-concepts]

| Value     | Behavior                                         |
| --------- | ------------------------------------------------ |
| `visible` | paint outside (default)                          |
| `hidden`  | clip, no scroll UI                               |
| `clip`    | clip without programmatic scroll                 |
| `scroll`  | always show scrollports (axes may still overlay) |
| `auto`    | scrollbars when needed                           |

* **Shorthand**: `overflow: x y` / `overflow: auto`.
* **Axes**: `overflow-x`, `overflow-y`, `overflow-inline`, `overflow-block`.
* **Text**: `text-overflow: ellipsis` needs overflow ≠ visible + nowrap (usually).
* **`overflow-wrap` / `word-break`**: wrapping long strings.
* **Scroll**: `scroll-behavior`, `overscroll-behavior`, scroll snap.

```css
.panel {
  max-height: 240px;
  overflow: auto;
}
.truncate {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}
```

## 💡 Examples [#-examples]

```css
/* Prevent body scroll under modal */
body.modal-open {
  overflow: hidden;
}

/* Contain paint */
.media {
  overflow: hidden;
  border-radius: 12px;
}

/* Horizontal scroller */
.scroller {
  display: flex;
  gap: 1rem;
  overflow-x: auto;
  overscroll-behavior-x: contain;
}

/* Long URLs */
.prose a {
  overflow-wrap: anywhere;
}

/* Sticky inside overflow */
.sidebar {
  overflow: auto;
  height: 100%;
}
.sidebar h2 {
  position: sticky;
  top: 0;
}
```

```css
/* overlay scrollbars hint (limited support) */
.scroll {
  overflow: overlay;
} /* deprecated — use auto */
```

## ⚠️ Pitfalls [#️-pitfalls]

* `overflow-x: hidden` + `overflow-y: visible` computes to `auto` in many cases — can’t mix freely.
* Clipping kills `position: sticky` relative to outer viewport if an ancestor scrolls/clips incorrectly.
* `overflow: hidden` is not a security boundary for content.
* Nested scroll areas hurt UX — prefer one primary scroller.
* Ellipsis requires a bounded width — flex items need `min-width: 0`.

## 🔗 Related [#-related]

* [scroll.md](/docs/css/scroll) — scrolling
* [scroll\_snap.md](/docs/css/scroll-snap) — snap
* [sticky.md](/docs/css/sticky) — sticky constraints
* [box\_model.md](/docs/css/box-model) — sizing
* [text.md](/docs/css/text) — wrapping


# Positioning (/docs/css/position)



# Positioning [#positioning]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `position` property controls how an element is placed in the document flow and how `inset` / `top` / `right` / `bottom` / `left` offsets apply. Static and relative stay in flow; absolute and fixed are removed from flow; sticky toggles between relative and fixed within a scroll ancestor. Use positioning for overlays, badges, sticky headers, and escape hatches—not as a substitute for Flexbox or Grid page layout.

Prefer logical insets (`inset-block`, `inset-inline`) for writing-mode-aware UI.

## 🔧 Core concepts [#-core-concepts]

### Position values [#position-values]

| Value      | In flow?          | Containing block (offsets)                                                       |
| ---------- | ----------------- | -------------------------------------------------------------------------------- |
| `static`   | Yes               | Offsets ignored                                                                  |
| `relative` | Yes               | Own normal position                                                              |
| `absolute` | No                | Nearest positioned ancestor (not `static`), else initial containing block        |
| `fixed`    | No                | Viewport (unless an ancestor transforms/filters/etc. creates a containing block) |
| `sticky`   | Yes (until stuck) | Nearest scrollport; needs inset threshold                                        |

### Inset properties [#inset-properties]

| Property                       | Notes                                                  |
| ------------------------------ | ------------------------------------------------------ |
| `top` `right` `bottom` `left`  | Physical edges                                         |
| `inset`                        | Shorthand for four physical insets                     |
| `inset-block` / `inset-inline` | Logical pairs                                          |
| `inset-block-start` etc.       | Logical singles                                        |
| `z-index`                      | Stacking within a stacking context (`auto` or integer) |

### Stacking context triggers (common) [#stacking-context-triggers-common]

`position` + `z-index` other than `auto`, `opacity &lt; 1`, `transform`, `filter`, `isolation`, `fixed`/`sticky` in many engines, and more. Nested contexts can trap `z-index`.

## 💡 Examples [#-examples]

### Badge on a relative parent [#badge-on-a-relative-parent]

```css
.icon-wrap {
  position: relative;
  display: inline-grid;
}

.badge {
  position: absolute;
  inset-block-start: -0.25rem;
  inset-inline-end: -0.25rem;
  min-inline-size: 1rem;
  block-size: 1rem;
  border-radius: 999px;
  background: tomato;
  color: white;
  font-size: 0.65rem;
  place-content: center;
  display: grid;
}
```

### Fixed toast [#fixed-toast]

```css
.toast {
  position: fixed;
  inset-block-end: 1rem;
  inset-inline: 1rem;
  z-index: 1000;
  max-inline-size: min(24rem, 100% - 2rem);
  margin-inline-start: auto; /* push to inline-end when full width allowed */
}
```

### Sticky section header [#sticky-section-header]

```css
.section__title {
  position: sticky;
  inset-block-start: 0;
  background: Canvas;
  padding-block: 0.5rem;
  z-index: 1;
}
```

### Full-bleed absolute overlay [#full-bleed-absolute-overlay]

```css
.modal-root {
  position: fixed;
  inset: 0;
  display: grid;
  place-items: center;
  background: rgb(0 0 0 / 0.4);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using `absolute` for primary layout instead of Grid/Flex, causing fragile overlaps on resize.
* Expecting `fixed` relative to the viewport when a parent has `transform`, `filter`, or `perspective`—it becomes a containing block.
* Sticky failing because an ancestor has `overflow: hidden` / `auto` without enough scroll room.
* Fighting stacking with huge `z-index` values instead of restructuring stacking contexts.
* Offsetting with physical `left`/`right` only, breaking RTL layouts—prefer logical insets.

## 🔗 Related [#-related]

* [Flexbox](/docs/css/flex)
* [CSS Grid](/docs/css/grid)
* [Scroll](/docs/css/scroll)
* [Transforms](/docs/css/transform)


# Print Styles (/docs/css/print)



# Print Styles [#print-styles]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Print CSS adapts layouts for paper and PDF via `@media print` and paged properties (`page-break_*` / `break-*`). Hide chrome, expand links, avoid wasted ink, and control breaks inside articles. Test with the browser’s print preview.

## 🔧 Core concepts [#-core-concepts]

* **Query**: `@media print \{ ... \}`.
* **Breaks**: `break-before/after/inside`, legacy `page-break-*`.
* **`@page`**: size, margin — `@page \{ margin: 1.5cm; \}`.
* **Widows/orphans**: `orphans`, `widows` line counts.
* **Colors**: `print-color-adjust: exact` when backgrounds must print.
* **Units**: `cm`, `in`, `pt` useful for paper.

```css
@media print {
  nav,
  .ads,
  .no-print {
    display: none !important;
  }
  a[href]::after {
    content: " (" attr(href) ")";
    font-size: 0.8em;
  }
  body {
    color: #000;
    background: #fff;
  }
}
```

## 💡 Examples [#-examples]

```css
@page {
  size: A4;
  margin: 16mm;
}

@media print {
  .page {
    break-after: page;
  }
  h2,
  h3 {
    break-after: avoid;
  }
  pre,
  table,
  figure {
    break-inside: avoid;
  }
  img {
    max-width: 100% !important;
  }
  .shadow-card {
    box-shadow: none;
    border: 1px solid #ccc;
  }
  a {
    text-decoration: underline;
  }
  /* optional: only external URLs */
  a[href^="http"]::after {
    content: " (" attr(href) ")";
  }
}

/* Screen-only */
@media screen {
  .print-only {
    display: none;
  }
}
```

```css
@media print {
  .brand-bar {
    print-color-adjust: exact;
    -webkit-print-color-adjust: exact;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fixed/sticky headers often repeat awkwardly — hide or static them for print.
* Dark themes waste ink and reduce contrast on paper — force light print colors.
* `position: fixed` elements can overlay every page — neutralize.
* Very long URLs in `::after` can overflow — consider shortening or omitting internals.
* Flex/grid print support is better than before but still verify complex dashboards.

## 🔗 Related [#-related]

* [media\_queries.md](/docs/css/media-queries) — @media
* [overflow.md](/docs/css/overflow) — clipping
* [background.md](/docs/css/background) — print backgrounds
* [text.md](/docs/css/text) — typography
* [reset\_normalize.md](/docs/css/reset-normalize) — base styles


# Pseudo-classes (/docs/css/pseudo-classes)



# Pseudo-classes [#pseudo-classes]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Pseudo-classes select elements in a particular state or structural position (`:hover`, `:focus-visible`, `:nth-child`, `:valid`). They help style interaction and structure without extra markup. Prefer `:focus-visible` for keyboard-friendly outlines.

## 🔧 Core concepts [#-core-concepts]

| Group       | Examples                                                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| User action | `:hover` `:active` `:focus` `:focus-visible` `:focus-within`                                                                   |
| Location    | `:link` `:visited` `:target`                                                                                                   |
| Input       | `:checked` `:disabled` `:enabled` `:required` `:optional` `:valid` `:invalid` `:user-invalid` `:placeholder-shown` `:autofill` |
| Structural  | `:first-child` `:last-child` `:nth-child()` `:nth-of-type()` `:only-child` `:empty`                                            |
| Logical     | `:is()` `:where()` `:not()` `:has()`                                                                                           |
| Linguistic  | `:lang()` `:dir()`                                                                                                             |

```css
button:hover {
  filter: brightness(1.05);
}
button:focus-visible {
  outline: 2px solid var(--accent);
}
form:focus-within {
  border-color: var(--accent);
}
```

## 💡 Examples [#-examples]

```css
/* Zebra + first */
tr:nth-child(odd) {
  background: #fafafa;
}
li:not(:last-child) {
  margin-bottom: 0.5rem;
}

/* Checkbox UI */
input[type="checkbox"]:checked + .label {
  text-decoration: line-through;
}

/* Valid/invalid after interaction */
input:user-invalid {
  border-color: crimson;
}
input:user-valid {
  border-color: seagreen;
}

/* Empty state */
.list:empty::before {
  content: "Nothing here";
  color: #888;
}

/* Soft :is */
:is(h1, h2, h3):first-child {
  margin-top: 0;
}

/* Modal open on dialog */
dialog:open {
  border-radius: 12px;
}
```

```css
/* Avoid :visited privacy limits — only limited props allowed */
a:visited {
  color: rebeccapurple;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `:hover` on touch devices can “stick” — pair with `@media (hover: hover)`.
* Styling `:invalid` from page load is noisy — use `:user-invalid`.
* `:visited` is privacy-restricted — few properties apply.
* `:empty` is false if whitespace text nodes exist.
* Specificity of most pseudo-classes equals a class (except `:where`).

## 🔗 Related [#-related]

* [pseudo\_elements.md](/docs/css/pseudo-elements) — ::pseudo
* [selectors.md](/docs/css/selectors) — selector overview
* [has\_selector.md](/docs/css/has-selector) — :has
* [hover.md](/docs/css/hover) — hover patterns
* [specificity.md](/docs/css/specificity) — weights


# Pseudo-elements (/docs/css/pseudo-elements)



# Pseudo-elements [#pseudo-elements]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Pseudo-elements style or generate fragments of elements: `::before`/`::after` boxes, `::placeholder`, `::selection`, `::marker`, `::first-line`, and `::part` for shadow trees. They are not real DOM nodes — limited for accessibility and JS querying.

## 🔧 Core concepts [#-core-concepts]

| Pseudo-element                    | Role                               |
| --------------------------------- | ---------------------------------- |
| `::before` / `::after`            | generated children; need `content` |
| `::placeholder`                   | input placeholder text             |
| `::selection`                     | highlighted text                   |
| `::marker`                        | list marker                        |
| `::first-letter` / `::first-line` | typographic accents                |
| `::backdrop`                      | dialog/fullscreen backdrop         |
| `::part(name)`                    | style shadow parts from outside    |
| `::file-selector-button`          | file input button                  |

* Double-colon `::` is modern; single `:` still works for legacy ones.
* Generated content is not in the accessibility tree as real text in all cases — don’t put critical info only in `content`.

```css
.external::after {
  content: " ↗";
  font-size: 0.85em;
}
::selection {
  background: #ffe08a;
}
```

## 💡 Examples [#-examples]

```css
/* Icon via mask / content */
.icon-check::before {
  content: "";
  display: inline-block;
  width: 1em;
  height: 1em;
  background: currentColor;
  mask: url(/check.svg) center / contain no-repeat;
}

/* Clearfix-ish */
.row::after {
  content: "";
  display: block;
  clear: both;
}

/* Placeholder */
input::placeholder {
  color: #999;
  opacity: 1;
}

/* Marker */
li::marker {
  color: var(--accent);
  font-weight: 700;
}

/* Dialog */
dialog::backdrop {
  background: rgb(0 0 0 / 0.5);
  backdrop-filter: blur(2px);
}

/* Shadow part */
x-button::part(base) {
  border-radius: 8px;
}
```

```css
/* Quotes */
q::before {
  content: open-quote;
}
q::after {
  content: close-quote;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Without `content`, `::before`/`::after` won’t generate a box (except some browser quirks).
* Can’t attach event listeners to pseudo-elements — use real elements when interaction is needed.
* Screen readers may ignore or mishandle decorative `content` — keep meaningful text in DOM.
* Only one `::before` and one `::after` per element.
* `::first-line` accepts a limited property set.

## 🔗 Related [#-related]

* [pseudo\_classes.md](/docs/css/pseudo-classes) — states
* [selectors.md](/docs/css/selectors) — overview
* [icon.md](/docs/css/icon) — icon techniques
* [effects.md](/docs/css/effects) — decorative effects
* [../Javascript/DOM/shadow\_dom.md](/docs/css/../javascript/dom/shadow-dom) — ::part


# Reset & Normalize (/docs/css/reset-normalize)



# Reset & Normalize [#reset--normalize]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Resets and normalize stylesheets reduce browser default inconsistencies. A **reset** aggressively zeros margins/padding; **normalize** preserves useful defaults while fixing bugs. Modern projects often use a small opinionated base (e.g. border-box, margin wipe, media defaults) instead of huge legacy resets.

## 🔧 Core concepts [#-core-concepts]

* **Goals**: predictable box model, typography baseline, media fluidity, form inheritance.
* **`box-sizing: border-box`**: almost universal recommendation.
* **Inheritance**: forms don’t inherit `font` by default — fix it.
* **Lists/quotes**: decide whether to keep bullets or reset.
* **Layers**: put reset in the earliest `@layer`.
* **Don’t**: remove focus outlines without `:focus-visible` replacement.

```css
@layer reset {
  *,
  *::before,
  *::after {
    box-sizing: border-box;
  }
  * {
    margin: 0;
  }
  html {
    -webkit-text-size-adjust: 100%;
  }
  body {
    line-height: 1.5;
    -webkit-font-smoothing: antialiased;
  }
  img,
  picture,
  video,
  canvas,
  svg {
    display: block;
    max-width: 100%;
  }
  input,
  button,
  textarea,
  select {
    font: inherit;
  }
  p,
  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    overflow-wrap: break-word;
  }
}
```

## 💡 Examples [#-examples]

```css
/* Focus visible, not none */
:focus {
  outline: none;
}
:focus-visible {
  outline: 2px solid var(--accent, #06c);
  outline-offset: 2px;
}

/* List opt-in */
ul[role="list"],
ol[role="list"] {
  list-style: none;
  padding: 0;
}

/* Button reset */
button {
  background: none;
  border: none;
  color: inherit;
  cursor: pointer;
}

/* Table normalize bits */
table {
  border-collapse: collapse;
  border-spacing: 0;
}

/* Reduce motion baseline */
@media (prefers-reduced-motion: reduce) {
  html:focus-within {
    scroll-behavior: auto;
  }
}
```

```css
/* Prefer small modern base over * { all: unset } nukes */
```

## ⚠️ Pitfalls [#️-pitfalls]

* Ultra-aggressive resets fight third-party widgets — scope when embedding.
* Removing list styles without `role="list"` can hurt VoiceOver semantics in some cases.
* Never `outline: none` without a visible `:focus-visible` alternative.
* Duplicate normalize + framework reboot causes conflicts — pick one base.
* Reset ≠ design system — still define tokens/type after.

## 🔗 Related [#-related]

* [cascade\_layers.md](/docs/css/cascade-layers) — reset layer
* [box\_model.md](/docs/css/box-model) — border-box
* [font.md](/docs/css/font) — typography base
* [button.md](/docs/css/button) — button styles
* [pseudo\_classes.md](/docs/css/pseudo-classes) — focus-visible


# Scale (/docs/css/scale)



# Scale [#scale]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Scaling changes an element’s visual size without necessarily affecting layout the same way as `width`/`height`. In modern CSS, prefer the independent `scale` property or `transform: scale()` for UI feedback (hover grow, press shrink, zoom previews). Unlike changing box dimensions, transform-based scale typically does not reflow siblings—ideal for micro-interactions.

For true layout scaling (zoom entire UI), consider `zoom` (non-standard but widely used) or rem-based design tokens; know the trade-offs.

## 🔧 Core concepts [#-core-concepts]

### Ways to scale [#ways-to-scale]

| Approach                         | Layout impact                        | Notes                             |
| -------------------------------- | ------------------------------------ | --------------------------------- |
| `scale: <sx> <sy>?`              | Visual; used space usually unchanged | Individual transform property     |
| `transform: scale()`             | Same as above                        | Can combine with rotate/translate |
| `width` / `height` / `font-size` | Reflows                              | Real box change                   |
| `zoom`                           | Affects layout in supporting engines | Not in formal CSS standard        |
| SVG `viewBox` / `width`          | Vector scaling                       | Best for icons/illustrations      |

### Transform origin [#transform-origin]

| Property           | Role                                                    |
| ------------------ | ------------------------------------------------------- |
| `transform-origin` | Pivot for scale/rotate (`center`, `top left`, `%`)      |
| `transform-box`    | `border-box` \| `fill-box` \| `view-box` (SVG-relevant) |

Uniform scale: `scale: 1.05` or `scale(1.05)`. Non-uniform: `scale: 1.2 0.9`.

### Accessibility [#accessibility]

Large unexpected scale animations can bother users—respect `prefers-reduced-motion` and don’t rely on scale alone for meaning.

## 💡 Examples [#-examples]

### Hover grow (compositor-friendly) [#hover-grow-compositor-friendly]

```css
.card {
  transform-origin: center;
  transition: scale 160ms ease;
  scale: 1;
}

@media (hover: hover) {
  .card:hover {
    scale: 1.03;
  }
}

@media (prefers-reduced-motion: reduce) {
  .card { transition: none; }
  .card:hover { scale: 1; }
}
```

### Press feedback on button [#press-feedback-on-button]

```css
.btn:active {
  scale: 0.98;
}
```

### Zoom preview from corner [#zoom-preview-from-corner]

```css
.thumb {
  overflow: hidden;
}

.thumb img {
  transform-origin: center;
  transition: transform 220ms ease;
}

.thumb:hover img {
  transform: scale(1.08);
}
```

### Scale with translate for popover [#scale-with-translate-for-popover]

```css
.popover[data-open="true"] {
  scale: 1;
  opacity: 1;
}

.popover[data-open="false"] {
  scale: 0.96;
  opacity: 0;
  transition: scale 120ms ease, opacity 120ms ease;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Scaling up without `overflow: hidden` on parents so content paints outside and overlaps neighbors.
* Using `scale` for responsive layout instead of fluid type/grid—hit targets and text reflow won’t match the visual size.
* Forgetting `transform-origin`, so elements appear to slide while scaling.
* Combining conflicting `transform` shorthand and individual `scale`/`translate` properties without understanding the combined used transform.
* Animating scale on huge filtered layers, which can be costly on low-end GPUs.

## 🔗 Related [#-related]

* [Transforms](/docs/css/transform)
* [Animation](/docs/css/animation)
* [Hover](/docs/css/hover)
* [Images](/docs/css/image)


# Scroll Snap (/docs/css/scroll-snap)



# Scroll Snap [#scroll-snap]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS scroll snap aligns a scroll container’s viewport to snap positions on children — carousels, paginated strips, and section snapping — without heavy JS. Configure snap on the container and snap alignment on items.

## 🔧 Core concepts [#-core-concepts]

| Property            | Where     | Values                                   |
| ------------------- | --------- | ---------------------------------------- |
| `scroll-snap-type`  | container | `x`/`y`/`both` + `mandatory`/`proximity` |
| `scroll-snap-align` | items     | `start` `center` `end` `none`            |
| `scroll-snap-stop`  | items     | `normal` `always`                        |
| `scroll-padding`    | container | inset for sticky headers                 |
| `scroll-margin`     | items     | snap area outset                         |

* **Mandatory**: always settle on a snap point; **proximity**: only if close.
* Works with overflow scrollers (`overflow-x: auto`).
* Pair with `scroll-behavior: smooth` carefully (a11y).

```css
.scroller {
  display: flex;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
  gap: 1rem;
}
.scroller > * {
  flex: 0 0 80%;
  scroll-snap-align: center;
}
```

## 💡 Examples [#-examples]

```css
/* Full-page sections */
html {
  scroll-snap-type: y proximity;
}
section {
  min-height: 100vh;
  scroll-snap-align: start;
  scroll-snap-stop: always;
}

/* Padding for fixed header */
.scroller {
  scroll-padding-inline: 1rem;
  scroll-padding-block-start: 4rem;
}

/* Stop skipping cards */
.card {
  scroll-snap-stop: always;
}

/* Vertical story */
.stories {
  height: 100dvh;
  overflow-y: auto;
  scroll-snap-type: y mandatory;
}
.stories > article {
  height: 100dvh;
  scroll-snap-align: start;
}
```

```css
@media (prefers-reduced-motion: reduce) {
  .scroller {
    scroll-snap-type: none;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `mandatory` can trap users on small viewports — test keyboard and screen zoom.
* Nested scrollers with snap fight each other — snap one axis/level.
* Images loading late shift snap positions — reserve sizes (`aspect-ratio`, width/height).
* Snap ≠ carousel accessibility — still provide buttons and focus management.
* iOS/Android quirks with momentum — prefer `proximity` when unsure.

## 🔗 Related [#-related]

* [scroll.md](/docs/css/scroll) — overflow scroll
* [overflow.md](/docs/css/overflow) — scroll containers
* [sticky.md](/docs/css/sticky) — scroll-padding with sticky
* [media\_queries.md](/docs/css/media-queries) — reduced motion
* [flex.md](/docs/css/flex) — horizontal strips


# Scroll (/docs/css/scroll)



# Scroll [#scroll]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Scroll-related CSS controls overflow, scroll snapping, scrollbars, overscroll behavior, and scroll-driven interactions. Use it to create readable regions, carousels, sticky companions, and safer nested scroll areas. Prefer intentional overflow (`auto` / `hidden`) over accidental clipping, and always ensure keyboard and focusable content remain reachable inside scrollports.

Logical properties (`overflow-inline`, `overflow-block`) help in vertical and horizontal writing modes.

## 🔧 Core concepts [#-core-concepts]

### Overflow [#overflow]

| Property                             | Values / role                                           |
| ------------------------------------ | ------------------------------------------------------- |
| `overflow`                           | `visible` \| `hidden` \| `clip` \| `scroll` \| `auto`   |
| `overflow-x` / `overflow-y`          | Per axis (physical)                                     |
| `overflow-inline` / `overflow-block` | Logical axes                                            |
| `overscroll-behavior`                | `auto` \| `contain` \| `none` — chained scroll / bounce |

### Scroll snap [#scroll-snap]

| Property            | Role                                                  |
| ------------------- | ----------------------------------------------------- |
| `scroll-snap-type`  | `x`/`y`/`both` + `mandatory`/`proximity` on container |
| `scroll-snap-align` | `start` \| `center` \| `end` on items                 |
| `scroll-snap-stop`  | `normal` \| `always`                                  |
| `scroll-padding`    | Insets for snap/scroll targets (sticky headers)       |
| `scroll-margin`     | Outset on targets for `scrollIntoView` / snap         |

### Scrollbars & utilities [#scrollbars--utilities]

| Feature                               | Notes                                        |
| ------------------------------------- | -------------------------------------------- |
| `scrollbar-gutter: stable`            | Reserve space to avoid layout shift          |
| `scrollbar-width` / `scrollbar-color` | Standard scrollbar styling (limited)         |
| `::-webkit-scrollbar*`                | WebKit/Blink custom scrollbars               |
| `scroll-behavior: smooth`             | Animated navigation (respect reduced motion) |

## 💡 Examples [#-examples]

### Scrollable panel [#scrollable-panel]

```css
.panel {
  max-block-size: min(24rem, 70dvh);
  overflow: auto;
  overscroll-behavior: contain;
  scrollbar-gutter: stable;
}
```

### Horizontal snap carousel [#horizontal-snap-carousel]

```css
.carousel {
  display: flex;
  gap: 1rem;
  overflow-x: auto;
  scroll-snap-type: x mandatory;
  scroll-padding-inline: 1rem;
  -webkit-overflow-scrolling: touch;
}

.carousel > .slide {
  flex: 0 0 min(80%, 20rem);
  scroll-snap-align: start;
}
```

### Offset for sticky header anchors [#offset-for-sticky-header-anchors]

```css
:root {
  --header-h: 3.5rem;
}

.site-header {
  position: sticky;
  inset-block-start: 0;
  block-size: var(--header-h);
}

:target,
[id] {
  scroll-margin-block-start: calc(var(--header-h) + 0.5rem);
}
```

### Smooth scroll with reduced motion [#smooth-scroll-with-reduced-motion]

```css
html {
  scroll-behavior: smooth;
}

@media (prefers-reduced-motion: reduce) {
  html { scroll-behavior: auto; }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Putting `overflow: hidden` on ancestors and breaking `position: sticky` descendants.
* Nested scroll areas that trap scroll chaining—use `overscroll-behavior: contain` thoughtfully.
* `scroll-behavior: smooth` without a reduced-motion fallback.
* Snap carousels that hide focusable controls off-screen without keyboard alternatives.
* Custom WebKit scrollbar CSS that removes affordance or fails contrast checks.

## 🔗 Related [#-related]

* [Positioning](/docs/css/position)
* [Adaptive design](/docs/css/adaptive)
* [Flexbox](/docs/css/flex)
* [Hover](/docs/css/hover)


# Selectors Basics (/docs/css/selectors-basics)



# Selectors Basics [#selectors-basics]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Selectors** choose which HTML elements a rule applies to. Start with type, class, and id selectors, then combine them. Keep selectors short and readable.

## 🔧 Core concepts [#-core-concepts]

| Selector   | Example   | Matches                    |
| ---------- | --------- | -------------------------- |
| Type       | `p`       | All `<p>` elements         |
| Class      | `.card`   | `class="card"`             |
| Id         | `#main`   | `id="main"` (one per page) |
| Descendant | `nav a`   | `a` inside `nav`           |
| Child      | `ul > li` | Direct child only          |
| Group      | `h1, h2`  | Both `h1` and `h2`         |
| Universal  | `*`       | Everything (use sparingly) |

Classes are the workhorse of maintainable CSS.

## 💡 Examples [#-examples]

**Type and class:**

```css
h1 {
  font-size: 2rem;
}

.note {
  padding: 1rem;
  background: #eef2ff;
}
```

```html
<h1>Title</h1>
<p class="note">Remember selectors.</p>
```

**Descendant vs child:**

```css
article p {
  margin-bottom: 0.75rem;
}

ul > li {
  list-style: disc;
}
```

**Grouping and multiple classes:**

```css
h1,
h2,
h3 {
  line-height: 1.2;
}

.btn.primary {
  background: #2563eb;
  color: white;
}
```

```html
<button class="btn primary">Save</button>
```

## ⚠️ Pitfalls [#️-pitfalls]

* `#id` is very specific — overuse makes overrides painful.
* `div div div span` selectors are brittle; prefer classes.
* Forgetting the `.` in `.class` styles a non-existent `<class>` element type.
* `ul > li` does not match nested `li` deeper than one level.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/css/getting-started)
* [cascade\_basics.md](/docs/css/cascade-basics)
* [box\_model\_basics.md](/docs/css/box-model-basics)
* [selectors.md](/docs/css/selectors)


# Selectors (/docs/css/selectors)



# Selectors [#selectors]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Selectors target elements for styling. From type/class/id to attributes, combinators, and modern relational selectors (`:is`, `:where`, `:has`). Write selectors that express intent without over-specificity.

## 🔧 Core concepts [#-core-concepts]

| Kind              | Example                                |
| ----------------- | -------------------------------------- |
| Type / class / id | `div` `.card` `#app`                   |
| Attribute         | `[type="text"]` `[data-x]`             |
| Combinators       | `A B` `A > B` `A + B` `A ~ B`          |
| Pseudo-class      | `:hover` `:nth-child` `:focus-visible` |
| Pseudo-element    | `::before` `::placeholder`             |
| Grouping          | `h1, h2` / `:is(h1, h2)`               |
| Relatival         | `:has(> img)`                          |

* **`:where()`*&#x2A;: specificity 0; &#x2A;*`:is()`**: takes most specific argument.
* **Universal**: `*` — use sparingly.
* **Namespace**: `svg|a` rare in HTML docs.

```css
nav > ul > li + li {
  margin-left: 1rem;
}
article:has(img) {
  display: grid;
}
```

## 💡 Examples [#-examples]

```css
/* Attributes */
a[target="_blank"]::after {
  content: "↗";
}
input[type="checkbox"]:checked + label {
  font-weight: 600;
}

/* Structural */
tr:nth-child(even) {
  background: #f6f6f6;
}
li:not(:last-child) {
  border-bottom: 1px solid #ddd;
}

/* Soft specificity */
:where(.prose) a {
  color: var(--link);
}
:is(h1, h2, h3):hover {
  text-decoration: underline;
}

/* Has */
label:has(:invalid) {
  color: crimson;
}
.card:has(> .badge) {
  padding-top: 2rem;
}

/* Focus */
:focus-visible {
  outline: 2px solid var(--accent);
  outline-offset: 2px;
}
```

```css
/* Avoid over-qualification */
/* BAD: div.card.panel */
/* GOOD: .card */
```

## ⚠️ Pitfalls [#️-pitfalls]

* IDs (`#x`) crush specificity — prefer classes for UI.
* Descendant selectors (`A B`) are costly when very broad on large DOMs — tighten when needed.
* `:has()` is powerful but can be expensive — avoid pathological deep queries.
* `::before` needs `content` or it won’t generate a box.
* Case sensitivity of attributes depends on language / `i` flag in selectors.

## 🔗 Related [#-related]

* [specificity.md](/docs/css/specificity) — scoring
* [pseudo\_classes.md](/docs/css/pseudo-classes) — states
* [pseudo\_elements.md](/docs/css/pseudo-elements) — generated boxes
* [has\_selector.md](/docs/css/has-selector) — :has deep dive
* [nesting.md](/docs/css/nesting) — nested selectors


# Specificity (/docs/css/specificity)



# Specificity [#specificity]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Specificity decides which declaration wins when selectors match the same element. Count IDs, classes/attributes/pseudo-classes, and types/pseudo-elements. Cascade layers, importance, and order also matter — specificity is only one axis.

## 🔧 Core concepts [#-core-concepts]

| Selector piece                | Weight (a,b,c)                                 |
| ----------------------------- | ---------------------------------------------- |
| Inline `style=""`             | wins over selectors (except `!important` wars) |
| `#id`                         | (1,0,0)                                        |
| `.class`, `[attr]`, `:hover`  | (0,1,0)                                        |
| `div`, `::before`             | (0,0,1)                                        |
| `:where()`                    | (0,0,0)                                        |
| `:is()` / `:has()` / `:not()` | specificity of most specific argument          |

* **Tie-break**: later rule in the cascade wins (within same layer/importance).
* **`!important`**: escalates importance; still compare specificity within that bucket.
* **Layers**: `@layer` can make lower-specificity author styles win over unlayered — see cascade layers.

```css
#nav .link {
  /* 1,1,0 */
  color: blue;
}
.link:hover {
  /* 0,2,0 */
  color: red;
} /* loses to #nav .link */
```

## 💡 Examples [#-examples]

```css
/* Soft defaults */
:where(.btn) {
  padding: 0.5rem 1rem;
} /* 0 */
.btn.primary {
  background: var(--accent);
} /* easy override */

/* :is takes max */
:is(#a, .b) span {
  /* 1,0,1 */
}

/* Avoid IDs for styling */
/* BAD */
#header nav ul li a {
}
/* GOOD */
.site-nav a {
}

/* Inline vs class */
/* style="color:red" beats .text { color: blue } */
.text {
  color: blue !important;
} /* beats inline without !important */

/* Attribute vs class — same bucket */
[data-active] {
}
.is-active {
}
```

```css
/* Progressive override */
.card {
  padding: 1rem;
}
.card.compact {
  padding: 0.5rem;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fighting specificity with ever-longer selectors or `!important` creates unmaintainable CSS.
* IDs in CSS couple to unique DOM nodes — prefer classes.
* `!important` in utilities can be OK; in components it usually signals a specificity problem.
* Shadow DOM has a separate boundary — host/page rules don’t pierce freely.
* Order only matters after layer + importance + specificity compare equal.

## 🔗 Related [#-related]

* [selectors.md](/docs/css/selectors) — selector types
* [cascade\_layers.md](/docs/css/cascade-layers) — @layer
* [pseudo\_classes.md](/docs/css/pseudo-classes) — specificity contributors
* [nesting.md](/docs/css/nesting) — nested specificity
* [variables.md](/docs/css/variables) — theming without specificity wars


# Sticky Positioning (/docs/css/sticky)



# Sticky Positioning [#sticky-positioning]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`position: sticky` toggles between relative and fixed positioning within a scroll ancestor based on `top`/`bottom`/`inset-*` thresholds. Ideal for sticky headers, table column labels, and sidebars. Sticky fails when any ancestor has unexpected overflow or insufficient height.

## 🔧 Core concepts [#-core-concepts]

* **Declare**: `position: sticky; top: 0;` (threshold required on the sticking axis).
* **Containing block**: sticks within the nearest scroll ancestor’s padding box.
* **Not fixed to viewport** if an ancestor scrolls/clips first.
* **Stacking**: sticky creates a stacking context when `z-index` is applied.
* **Logical**: `inset-block-start` instead of `top` for writing modes.
* **Tables**: `th \{ position: sticky; top: 0; \}` for header rows.

```css
.header {
  position: sticky;
  top: 0;
  z-index: 5;
  background: var(--bg);
}
```

## 💡 Examples [#-examples]

```css
/* Subnav under main header */
.subnav {
  position: sticky;
  top: 3.5rem; /* header height */
  z-index: 4;
}

/* Sticky sidebar */
.layout {
  display: grid;
  grid-template-columns: 1fr 16rem;
  gap: 2rem;
  align-items: start;
}
.aside {
  position: sticky;
  top: 1rem;
}

/* Sticky table head */
.table-wrap {
  max-height: 20rem;
  overflow: auto;
}
th {
  position: sticky;
  top: 0;
  background: #fff;
}

/* Both axes rare — stick first column */
td:first-child {
  position: sticky;
  inset-inline-start: 0;
  background: #fff;
}
```

```css
/* Common fix: remove overflow: hidden on parents */
.parent {
  overflow: visible;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Ancestor `overflow: hidden|auto|scroll` often becomes the sticky viewport — or prevents sticking.
* Parent height equals sticky child height → nowhere to travel — parent must be taller.
* Forgetting `top`/`bottom` means it never sticks.
* Transparent sticky headers let content show through — set opaque background.
* `top: 0` under a fixed bar covers content — offset by bar height + `scroll-padding`.

## 🔗 Related [#-related]

* [position.md](/docs/css/position) — position schemes
* [z\_index.md](/docs/css/z-index) — stacking
* [overflow.md](/docs/css/overflow) — ancestor overflow
* [scroll\_snap.md](/docs/css/scroll-snap) — scroll-padding
* [logical\_properties.md](/docs/css/logical-properties) — inset-block-start


# Tables (/docs/css/table)



# Tables [#tables]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS table styling covers the table layout model (`display: table*` or real `<table>` markup) plus borders, spacing, and alignment of cells. Use semantic HTML tables for tabular data; use Grid/Flex for non-data layouts that merely look like tables. Modern CSS can make tables responsive with wrappers, `display` switches, or prioritized columns—but accessibility of real tables remains the priority.

Control fixed vs automatic layout with `table-layout`, and borders with `border-collapse`.

## 🔧 Core concepts [#-core-concepts]

### Table-related properties [#table-related-properties]

| Property          | Role                                                                  |
| ----------------- | --------------------------------------------------------------------- |
| `table-layout`    | `auto` (content-based) \| `fixed` (equal/col widths more predictable) |
| `border-collapse` | `separate` \| `collapse`                                              |
| `border-spacing`  | Gap when `separate`                                                   |
| `empty-cells`     | `show` \| `hide`                                                      |
| `caption-side`    | `top` \| `bottom` \| logical variants where supported                 |
| `vertical-align`  | Cell content alignment (`top`, `middle`, `baseline`)                  |

### Display values (for completeness) [#display-values-for-completeness]

`table`, `table-row`, `table-cell`, `table-column`, `table-column-group`, `table-header-group`, `table-footer-group`, `table-row-group`, `inline-table`. Prefer real elements (`<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`).

### Styling patterns [#styling-patterns]

| Pattern         | Technique                                                    |
| --------------- | ------------------------------------------------------------ |
| Zebra rows      | `tbody tr:nth-child(even)`                                   |
| Sticky header   | `th \{ position: sticky; top: 0; \}` inside overflow wrapper |
| Numeric columns | `font-variant-numeric: tabular-nums; text-align: end`        |
| Compact density | Reduce cell padding tokens                                   |

## 💡 Examples [#-examples]

### Clean data table [#clean-data-table]

```css
.table {
  inline-size: 100%;
  border-collapse: collapse;
  font-size: 0.9375rem;
}

.table th,
.table td {
  padding: 0.625rem 0.75rem;
  border-block-end: 1px solid color-mix(in oklab, CanvasText 12%, transparent);
  text-align: start;
}

.table th {
  font-weight: 600;
  background: color-mix(in oklab, CanvasText 4%, Canvas);
}

.table tbody tr:nth-child(even) {
  background: color-mix(in oklab, CanvasText 3%, Canvas);
}

.table .num {
  text-align: end;
  font-variant-numeric: tabular-nums;
}
```

### Fixed layout for predictable columns [#fixed-layout-for-predictable-columns]

```css
.table--fixed {
  table-layout: fixed;
}

.table--fixed th:nth-child(1) { width: 40%; }
.table--fixed th:nth-child(2) { width: 30%; }
.table--fixed th:nth-child(3) { width: 30%; }

.table--fixed td {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}
```

### Scroll wrapper with sticky head [#scroll-wrapper-with-sticky-head]

```css
.table-scroll {
  max-block-size: 20rem;
  overflow: auto;
}

.table-scroll th {
  position: sticky;
  inset-block-start: 0;
  z-index: 1;
  background: Canvas;
}
```

### Caption [#caption]

```css
.table caption {
  caption-side: bottom;
  padding-block: 0.5rem;
  color: color-mix(in oklab, CanvasText 65%, transparent);
  text-align: start;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Building “tables” from divs for data, losing row/column semantics for assistive tech.
* Mixing `border-collapse: collapse` with `border-radius` expectations—radius often won’t apply as on separate boxes.
* Letting wide tables overflow the viewport without a scroll wrapper or responsive strategy.
* Sticky headers failing because a parent uses `overflow: hidden`.
* Aligning numbers to the start, which makes columns hard to scan—use end alignment + tabular nums.

## 🔗 Related [#-related]

* [Text](/docs/css/text)
* [Scroll](/docs/css/scroll)
* [CSS Grid](/docs/css/grid)
* [Fonts](/docs/css/font)


# Text (/docs/css/text)



# Text [#text]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Text CSS controls wrapping, alignment, decoration, spacing, overflow, and white-space behavior. It sits beside font properties: fonts choose the face; text properties shape how glyphs flow in a box. Use these tools for readable paragraphs, truncated labels, wrapping balance, and decorative underlines without breaking accessibility or copy-paste.

Prefer logical alignment (`text-align: start`) and modern wrapping (`overflow-wrap`, `text-wrap`) for internationalized UIs.

## 🔧 Core concepts [#-core-concepts]

### Alignment & direction [#alignment--direction]

| Property                     | Notes                                                          |
| ---------------------------- | -------------------------------------------------------------- |
| `text-align`                 | `start` \| `end` \| `left` \| `right` \| `center` \| `justify` |
| `text-align-last`            | Last line alignment                                            |
| `direction` / `unicode-bidi` | Prefer HTML `dir` attribute when possible                      |
| `writing-mode`               | `horizontal-tb` \| `vertical-rl` \| …                          |
| `text-orientation`           | Vertical text glyph orientation                                |

### Wrapping & overflow [#wrapping--overflow]

| Property                       | Role                                                                        |
| ------------------------------ | --------------------------------------------------------------------------- |
| `white-space`                  | `normal` \| `nowrap` \| `pre` \| `pre-wrap` \| `pre-line` \| `break-spaces` |
| `overflow-wrap` / `word-break` | Long-string breaking strategies                                             |
| `line-break`                   | CJK line breaking                                                           |
| `hyphens`                      | `none` \| `manual` \| `auto` (needs `lang`)                                 |
| `text-overflow`                | `clip` \| `ellipsis` (needs overflow + nowrap typically)                    |
| `text-wrap`                    | `wrap` \| `balance` \| `pretty` \| `nowrap` (modern)                        |

### Decoration & spacing [#decoration--spacing]

| Property                          | Role                                                 |
| --------------------------------- | ---------------------------------------------------- |
| `text-decoration-*`               | line, style, color, thickness                        |
| `text-underline-offset`           | Optical underline position                           |
| `letter-spacing` / `word-spacing` | Tracking                                             |
| `text-indent`                     | First-line indent                                    |
| `text-transform`                  | `uppercase` \| `lowercase` \| `capitalize` \| `none` |
| `hanging-punctuation`             | Optical margin hanging (limited support)             |

## 💡 Examples [#-examples]

### Readable measure [#readable-measure]

```css
.prose {
  max-inline-size: 65ch;
  text-wrap: pretty;
  line-height: 1.6;
}

.prose h2 {
  text-wrap: balance;
}
```

### Truncate single line [#truncate-single-line]

```css
.truncate {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
  max-inline-size: 100%;
}
```

### Clamp to N lines [#clamp-to-n-lines]

```css
.line-clamp-3 {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 3;
  overflow: hidden;
}
```

### Link underline polish [#link-underline-polish]

```css
.prose a {
  text-decoration: underline;
  text-decoration-thickness: 0.08em;
  text-underline-offset: 0.18em;
  text-decoration-color: color-mix(in oklab, currentColor 55%, transparent);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Justifying text on narrow columns without hyphenation, creating huge word gaps.
* Using `word-break: break-all` on normal prose, which shreds readability.
* Truncating with ellipsis without another way to read the full string (title, expand, dialog).
* Applying `text-transform: uppercase` for logos/headings that screen readers may still announce oddly—prefer real content casing when meaning matters.
* Setting `letter-spacing` large on body text, harming readability.

## 🔗 Related [#-related]

* [Fonts](/docs/css/font)
* [Text fields](/docs/css/textfield)
* [Buttons](/docs/css/button)
* [Multi-column layout](/docs/css/column)


# Text fields (/docs/css/textfield)



# Text fields [#text-fields]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Text field styling covers `<input>` (text-like types), `<textarea>`, and contenteditable surfaces. Native controls inherit inconsistently across browsers, so production UIs usually apply a shared reset: font inheritance, explicit padding, borders, and focus styles. Prioritize visible labels, `:focus-visible` rings, error states, and comfortable touch targets over purely decorative chrome.

Use logical padding and `min-block-size` so fields scale with user font settings.

## 🔧 Core concepts [#-core-concepts]

### Elements & types [#elements--types]

| Control              | Notes                            |     |        |          |     |           |                    |
| -------------------- | -------------------------------- | --- | ------ | -------- | --- | --------- | ------------------ |
| \`input\[type="text" | email                            | url | search | password | tel | number]\` | Single-line fields |
| `textarea`           | Multi-line; style `resize`       |     |        |          |     |           |                    |
| `input[type="file"]` | Limited styling; often wrapped   |     |        |          |     |           |                    |
| `::placeholder`      | Hint text; never replace a label |     |        |          |     |           |                    |
| `::selection`        | Selected text colors             |     |        |          |     |           |                    |

### Useful properties [#useful-properties]

| Property                            | Role                                                 |
| ----------------------------------- | ---------------------------------------------------- |
| `font: inherit`                     | Match UI typography                                  |
| `appearance` / `-webkit-appearance` | Reduce native look where needed                      |
| `caret-color`                       | Caret theming                                        |
| `field-sizing`                      | `fixed` \| `content` (modern auto-size inputs/areas) |
| `resize`                            | `none` \| `vertical` \| `both` on textareas          |
| `accent-color`                      | Some controls’ accent (checkboxes, etc.)             |

### State selectors [#state-selectors]

| Selector                     | Use                                         |
| ---------------------------- | ------------------------------------------- |
| `:focus-visible`             | Keyboard-friendly focus ring                |
| `:user-invalid` / `:invalid` | Validation styling (prefer user-interacted) |
| `:disabled` / `:read-only`   | Non-editable affordances                    |
| `:placeholder-shown`         | Empty field styling                         |

## 💡 Examples [#-examples]

### Baseline field [#baseline-field]

```css
.field {
  display: grid;
  gap: 0.35rem;
}

.field__input {
  font: inherit;
  line-height: 1.4;
  padding: 0.625rem 0.75rem;
  min-block-size: 2.5rem;
  border: 1px solid color-mix(in oklab, CanvasText 20%, transparent);
  border-radius: 0.5rem;
  background: Canvas;
  color: CanvasText;
  inline-size: 100%;
}

.field__input::placeholder {
  color: color-mix(in oklab, CanvasText 45%, transparent);
}

.field__input:focus-visible {
  outline: 2px solid oklch(0.65 0.15 250);
  outline-offset: 2px;
  border-color: transparent;
}
```

### Textarea [#textarea]

```css
.field__input--area {
  min-block-size: 6rem;
  resize: vertical;
  field-sizing: content; /* progressive enhancement */
}
```

### Error state [#error-state]

```css
.field__input[aria-invalid="true"] {
  border-color: oklch(0.55 0.2 25);
}

.field__error {
  color: oklch(0.5 0.18 25);
  font-size: 0.875rem;
}
```

### Search with icon padding [#search-with-icon-padding]

```css
.input-search {
  padding-inline-start: 2.25rem;
  background-image: url("/icons/search.svg");
  background-repeat: no-repeat;
  background-position: left 0.65rem center;
  background-size: 1rem;
}

[dir="rtl"] .input-search {
  background-position: right 0.65rem center;
  padding-inline-start: 0.75rem;
  padding-inline-end: 2.25rem;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Removing focus outlines without a strong `:focus-visible` replacement.
* Using placeholder text as the only label—placeholders disappear and hurt accessibility.
* Styling `:invalid` from page load (before user input), which marks empty required fields red immediately—prefer `:user-invalid` where supported.
* Forbidding `resize` on large textareas without another way to grow the control.
* Setting fixed `height` in `px` that clips descenders or breaks zoomed text.

## 🔗 Related [#-related]

* [Buttons](/docs/css/button)
* [Text](/docs/css/text)
* [Fonts](/docs/css/font)
* [Cursor](/docs/css/cursor)


# Transforms (/docs/css/transform)



# Transforms [#transforms]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSS transforms move, rotate, scale, and skew elements in 2D or 3D without necessarily reflowing the document. They are the foundation of performant UI motion when paired with `opacity`. Prefer the individual transform properties (`translate`, `rotate`, `scale`) for readable code, or the classic `transform` list when you need a precise composed matrix order.

Transforms create a containing block for fixed descendants and often a new stacking context—account for that when building overlays.

## 🔧 Core concepts [#-core-concepts]

### Individual vs shorthand [#individual-vs-shorthand]

| Property    | Example                                               |
| ----------- | ----------------------------------------------------- |
| `translate` | `translate: 0 0.5rem` or `translate: 10% 0 2rem` (3D) |
| `rotate`    | `rotate: 15deg` or `rotate: x 45deg`                  |
| `scale`     | `scale: 1.05` / `scale: 1.1 0.9`                      |
| `transform` | `transform: translateY(0.5rem) rotate(3deg)`          |

Used transform combines individual properties with `transform` according to CSS Transforms Module rules—avoid setting conflicting systems blindly.

### Common transform functions [#common-transform-functions]

| Function                                             | Role                                                      |
| ---------------------------------------------------- | --------------------------------------------------------- |
| `translate()` / `translateX/Y/Z()` / `translate3d()` | Move                                                      |
| `scale()` / `scaleX/Y/Z()`                           | Resize visually                                           |
| `rotate()` / `rotateX/Y/Z()` / `rotate3d()`          | Rotate                                                    |
| `skew()` / `skewX/Y()`                               | Oblique distortion                                        |
| `matrix()` / `matrix3d()`                            | Raw matrix                                                |
| `perspective()`                                      | As a function on the element (often use property instead) |

### 3D helpers [#3d-helpers]

| Property              | Role                             |
| --------------------- | -------------------------------- |
| `perspective`         | On parent: depth for 3D children |
| `perspective-origin`  | Vanishing point                  |
| `transform-style`     | `flat` \| `preserve-3d`          |
| `backface-visibility` | `visible` \| `hidden`            |
| `transform-origin`    | Pivot point                      |

## 💡 Examples [#-examples]

### Enter transition with translate + opacity [#enter-transition-with-translate--opacity]

```css
.drawer {
  translate: 0 100%;
  opacity: 0;
  transition: translate 240ms ease, opacity 240ms ease;
}

.drawer.is-open {
  translate: 0 0;
  opacity: 1;
}
```

### Classic transform list [#classic-transform-list]

```css
.badge {
  transform: translateY(-50%) rotate(-6deg);
  transform-origin: left center;
}
```

### 3D card flip [#3d-card-flip]

```css
.flip {
  perspective: 800px;
}

.flip__inner {
  position: relative;
  transform-style: preserve-3d;
  transition: transform 500ms ease;
}

.flip.is-flipped .flip__inner {
  transform: rotateY(180deg);
}

.flip__face {
  backface-visibility: hidden;
}

.flip__face--back {
  transform: rotateY(180deg);
}
```

### GPU-friendly hover lift [#gpu-friendly-hover-lift]

```css
.tile {
  transition: transform 150ms ease, box-shadow 150ms ease;
}

@media (hover: hover) {
  .tile:hover {
    transform: translateY(-4px);
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Animating `top`/`left` instead of `translate`, causing layout thrashing.
* Surprising `position: fixed` children when an ancestor gains a transform.
* Using `skew` for primary layout alignment—text becomes harder to read.
* Forgetting `transform-origin` on rotations so UI pivots from the wrong point.
* Enabling `preserve-3d` and large blurs/filters on many nodes, which is expensive.

## 🔗 Related [#-related]

* [Scale](/docs/css/scale)
* [Animation](/docs/css/animation)
* [Positioning](/docs/css/position)
* [Effects](/docs/css/effects)


# Transitions (/docs/css/transitions)



# Transitions [#transitions]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Transitions interpolate property changes over time when a value changes (hover, class toggle, JS). Prefer transitions for simple state changes; use `@keyframes` animations for looping or multi-step sequences. Respect `prefers-reduced-motion`.

## 🔧 Core concepts [#-core-concepts]

* **Shorthand**: `transition: property duration easing delay`.
* **Longhands**: `transition-property`, `-duration`, `-timing-function`, `-delay`, `-behavior`.
* **Properties**: animatable values (colors, lengths, opacity, transforms…). Discrete props flip (with `transition-behavior: allow-discrete` for some).
* **Easing**: `ease`, `linear`, `ease-in-out`, `cubic-bezier()`, `steps()`.
* **`transitionend` / `transitioncancel`**: JS hooks.
* **Best perf**: `transform` and `opacity` (compositor-friendly).

```css
.button {
  transition:
    background-color 150ms ease,
    transform 150ms ease;
}
.button:hover {
  transform: translateY(-1px);
}
```

## 💡 Examples [#-examples]

```css
/* Multiple */
.card {
  transition:
    box-shadow 200ms ease,
    transform 200ms ease;
}

/* Delay for staggered menus */
.menu a {
  transition: opacity 120ms ease;
  transition-delay: calc(var(--i, 0) * 40ms);
}

/* Height auto — modern interpolate-size / grid trick */
.panel {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 200ms ease;
}
.panel.open {
  grid-template-rows: 1fr;
}
.panel > * {
  overflow: hidden;
}

/* Reduced motion */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    transition-duration: 0.01ms !important;
  }
}
```

```js
el.addEventListener("transitionend", (e) => {
  if (e.propertyName === "opacity") el.hidden = true;
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* `transition: all` is convenient but can animate expensive properties unintentionally.
* Cannot smoothly transition to/from `height: auto` in older engines — use grid/max-height hacks or new CSS features.
* Changing `transition` itself mid-flight can cancel — set transition on base rule, change property on state.
* Display `none` ↔ visible needs care (`allow-discrete` / `@starting-style`).
* Too-long transitions feel sluggish — UI micro-interactions often 100–200ms.

## 🔗 Related [#-related]

* [animation.md](/docs/css/animation) — keyframes
* [transform.md](/docs/css/transform) — transform props
* [effects.md](/docs/css/effects) — shadows/filters
* [hover.md](/docs/css/hover) — hover triggers
* [dark\_mode.md](/docs/css/dark-mode) — theme transitions


# CSS Variables (/docs/css/variables)



# CSS Variables [#css-variables]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Custom properties (`--name`) store reusable values that cascade and inherit. They enable theming, runtime tweaks via JS, and cleaner design tokens. Declare on `:root` or a scope; use with `var(--name, fallback)`.

## 🔧 Core concepts [#-core-concepts]

* **Define**: `--accent: #3366ff;` on any element.
* **Use**: `color: var(--accent);` / `var(--accent, blue)`.
* **Inheritance**: custom props inherit by default; reset with `initial` or new value.
* **Scope**: set on a component host to theme a subtree.
* **Computation**: can hold any token sequence; invalid at computed-value time falls back.
* **JS**: `element.style.setProperty("--x", "1rem")`, `getComputedStyle(el).getPropertyValue("--x")`.

```css
:root {
  --space: 0.5rem;
  --text: #111;
  --accent: oklch(60% 0.2 250);
}
.button {
  padding: calc(var(--space) * 2);
  color: var(--text);
  background: var(--accent);
}
```

## 💡 Examples [#-examples]

```css
/* Theming */
html[data-theme="dark"] {
  --text: #f5f5f5;
  --bg: #121212;
}
body {
  color: var(--text);
  background: var(--bg);
}

/* Component tokens */
.card {
  --card-pad: 1rem;
  padding: var(--card-pad);
}
.card.compact {
  --card-pad: 0.5rem;
}

/* Fallback chain */
color: var(--brand, var(--accent, navy));

/* With relative color / calc */
--h: 200;
background: oklch(70% 0.1 var(--h));
width: calc(100% - var(--sidebar, 0px));
```

```js
document.documentElement.style.setProperty("--accent", userColor);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `--x: 10` without units breaks `calc` expecting lengths — store units in the variable or multiply carefully.
* Custom properties are not CSS variables in the preprocessor sense — invalid values fail at computed-value time.
* Animating custom props needs `@property` for typed interpolation in many cases.
* Overusing global tokens without scopes creates coupling.
* `var()` inside URLs / some older contexts has quirks — test.

## 🔗 Related [#-related]

* [color\_functions.md](/docs/css/color-functions) — modern colors
* [calc\_min\_max\_clamp.md](/docs/css/calc-min-max-clamp) — calc with vars
* [dark\_mode.md](/docs/css/dark-mode) — theme switching
* [cascade\_layers.md](/docs/css/cascade-layers) — cascade order
* [specificity.md](/docs/css/specificity) — vs !important


# z-index (/docs/css/z-index)



# z-index [#z-index]

*CSS · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`z-index` controls stacking order **within a stacking context**. Only positioned elements (`relative`/`absolute`/`fixed`/`sticky`) or flex/grid items (and some properties that create contexts) participate. Most z-index bugs are stacking-context bugs, not number-size bugs.

## 🔧 Core concepts [#-core-concepts]

* **Stacking context roots**: `html`, `z-index` ≠ auto on positioned/flex/grid, `opacity &lt; 1`, `transform`, `filter`, `isolation: isolate`, `will-change`, etc.
* **Children** cannot escape a parent’s context to sit above an uncle — raise/isolate the parent.
* **Auto vs integer**: `auto` doesn’t create a new context by itself (with position); integers do on positioned elements.
* **Painting order**: backgrounds/borders → negative z → in-flow → floats → in-flow inline → z=auto/0 → positive z.
* **Strategy**: use small scales (0–10) + `isolation` rather than `99999`.

```css
.modal-backdrop {
  position: fixed;
  inset: 0;
  z-index: 10;
}
.modal {
  position: fixed;
  z-index: 11;
}
```

## 💡 Examples [#-examples]

```css
/* Isolate a component */
.dropdown {
  position: relative;
  isolation: isolate;
  z-index: 1;
}
.dropdown-menu {
  position: absolute;
  z-index: 2; /* only competes inside dropdown */
}

/* Sticky header */
.header {
  position: sticky;
  top: 0;
  z-index: 5;
}

/* Trap: transformed parent */
.parent {
  transform: translateZ(0);
} /* new context */
.child {
  position: relative;
  z-index: 9999;
} /* still under sibling contexts of parent */

/* Flex item z-index without position */
.row > .raise {
  z-index: 1;
}
```

```css
/* Debug layers with outline + temporary z */
```

## ⚠️ Pitfalls [#️-pitfalls]

* Huge `z-index` values don’t beat a parent stacking context.
* `opacity`, `transform`, `filter`, `backdrop-filter` create contexts — surprising for tooltips/modals.
* Mixing stacking from different features (sticky + transform) causes hard bugs — simplify.
* Negative z-index can hide behind the parent’s background.
* Accessibility: visual order ≠ tab order — don’t fake UI order only with z-index.

## 🔗 Related [#-related]

* [position.md](/docs/css/position) — positioning schemes
* [sticky.md](/docs/css/sticky) — sticky stacking
* [filter\_backdrop.md](/docs/css/filter-backdrop) — context creators
* [overflow.md](/docs/css/overflow) — clipping vs stack
* [transform.md](/docs/css/transform) — transform contexts


# Admin (/docs/django/admin)



# Admin [#admin]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django Admin is an auto-generated CRUD UI for models registered with `admin.site`. Enable `django.contrib.admin`, create a superuser, and customize list displays, filters, and search. Use it for internal ops—not as a public end-user interface.

## 🔧 Core concepts [#-core-concepts]

| Piece                                    | Role                                                          |
| ---------------------------------------- | ------------------------------------------------------------- |
| `admin.site.register(Model, ModelAdmin)` | Expose a model                                                |
| `@admin.register(Model)`                 | Decorator form                                                |
| `ModelAdmin`                             | list\_display, list\_filter, search\_fields, readonly\_fields |
| `InlineModelAdmin`                       | Edit related objects on the parent page                       |
| Permissions                              | Staff + model perms; superuser bypasses                       |
| URLs                                     | Included via `path("admin/", admin.site.urls)`                |

Requires `django.contrib.admin`, `auth`, `contenttypes`, `sessions`, `messages` in `INSTALLED_APPS`.

## 💡 Examples [#-examples]

**Register with list options:**

```python
# app/admin.py
from django.contrib import admin
from .models import Article


@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ("title", "author", "published_at", "is_published")
    list_filter = ("is_published", "published_at")
    search_fields = ("title", "body")
    prepopulated_fields = {"slug": ("title",)}
    date_hierarchy = "published_at"
    ordering = ("-published_at",)
```

**Inlines:**

```python
from django.contrib import admin
from .models import Order, OrderItem


class OrderItemInline(admin.TabularInline):
    model = OrderItem
    extra = 1


@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
    inlines = [OrderItemInline]
    list_display = ("id", "user", "created_at")
```

**URLs:**

```python
# config/urls.py
from django.contrib import admin
from django.urls import path

urlpatterns = [
    path("admin/", admin.site.urls),
]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `admin.autodiscover` is fine on modern Django—apps' `admin.py` load via `AppConfig`.
* Heavy `list_display` callables without `list_select_related` cause N+1 queries.
* Exposing admin on the public internet without HTTPS, 2FA, and IP limits is risky.
* Custom user models must be registered carefully; swap before the first migration.

## 🔗 Related [#-related]

* [Custom admin](/docs/django/custom-admin)
* [Models](/docs/django/models)
* [Authentication](/docs/django/authentication)
* [Settings](/docs/django/settings)
* [URLs](/docs/django/urls)
* [Forms](/docs/django/forms)


# ASGI / Channels (/docs/django/asgi-channels)



# ASGI / Channels [#asgi--channels]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

ASGI enables async Django and long-lived connections. Django 4.2+/5.x runs async views on ASGI servers (Uvicorn, Daphne, Hypercorn). **Channels** adds WebSockets, background channel layers (Redis), and consumers. Use ASGI for websockets/SSE; keep ORM calls safe (sync ORM in `sync_to_async` or async ORM where available).

## 🔧 Core concepts [#-core-concepts]

| Piece                                 | Role                         |
| ------------------------------------- | ---------------------------- |
| `asgi.py`                             | ASGI application entry       |
| `ProtocolTypeRouter`                  | HTTP vs WebSocket (Channels) |
| `URLRouter`                           | Websocket URL patterns       |
| `AuthMiddlewareStack`                 | Session user on WS           |
| `AsyncConsumer` / `WebsocketConsumer` | Handlers                     |
| Channel layer                         | Cross-process pub/sub        |
| `async_to_sync` / `sync_to_async`     | Bridge sync/async            |

Django async views: `async def view(request)`. Prefer async-safe libraries.

## 💡 Examples [#-examples]

**asgi.py (Channels):**

```python
import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from channels.security.websocket import AllowedHostsOriginValidator
import chat.routing

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
django_asgi_app = get_asgi_application()

application = ProtocolTypeRouter(
    {
        "http": django_asgi_app,
        "websocket": AllowedHostsOriginValidator(
            AuthMiddlewareStack(URLRouter(chat.routing.websocket_urlpatterns))
        ),
    }
)
```

**Consumer:**

```python
from channels.generic.websocket import AsyncJsonWebsocketConsumer


class ChatConsumer(AsyncJsonWebsocketConsumer):
    async def connect(self):
        self.room = self.scope["url_route"]["kwargs"]["room"]
        await self.channel_layer.group_add(self.room, self.channel_name)
        await self.accept()

    async def disconnect(self, code):
        await self.channel_layer.group_discard(self.room, self.channel_name)

    async def receive_json(self, content, **kwargs):
        await self.channel_layer.group_send(
            self.room, {"type": "chat.message", "text": content["text"]}
        )

    async def chat_message(self, event):
        await self.send_json({"text": event["text"]})
```

**Settings:**

```python
ASGI_APPLICATION = "config.asgi.application"
CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {"hosts": [("127.0.0.1", 6379)]},
    }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Calling sync ORM directly in async consumers without `sync_to_async` → blocking / errors.
* In-memory channel layer—does not work across multiple processes.
* Missing origin validation on WebSockets.
* Mixing WSGI deploy with Channels—need ASGI server.
* Forgetting `type` method name mapping (`chat.message` → `chat_message`).

## 🔗 Related [#-related]

* [Settings](/docs/django/settings)
* [Middleware](/docs/django/middleware)
* [Authentication](/docs/django/authentication)
* [Security](/docs/django/security)
* [Views](/docs/django/views)


# Authentication (/docs/django/authentication)



# Authentication [#authentication]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django’s auth system provides users, permissions, groups, password hashing, and session login. Use `django.contrib.auth` views/forms for classic sites, or packages like django-allauth for social login. Always authenticate against hashed passwords—never store plaintext.

## 🔧 Core concepts [#-core-concepts]

| Piece                                        | Role                                                  |
| -------------------------------------------- | ----------------------------------------------------- |
| `User` / custom user                         | `AUTH_USER_MODEL`                                     |
| `authenticate` / `login` / `logout`          | Session auth helpers                                  |
| `login_required` / `PermissionRequiredMixin` | Protect views                                         |
| Permissions                                  | `app_label.codename` (`add`/`change`/`delete`/`view`) |
| Password validators                          | `AUTH_PASSWORD_VALIDATORS`                            |
| Backends                                     | `AUTHENTICATION_BACKENDS` (ModelBackend default)      |

Sessions middleware + `AuthenticationMiddleware` attach `request.user`.

## 💡 Examples [#-examples]

**Login view (function):**

```python
from django.contrib.auth import authenticate, login
from django.shortcuts import redirect, render


def login_view(request):
    if request.method == "POST":
        user = authenticate(
            request,
            username=request.POST["username"],
            password=request.POST["password"],
        )
        if user is not None:
            login(request, user)
            return redirect("home")
    return render(request, "registration/login.html")
```

**Protect a view:**

```python
from django.contrib.auth.decorators import login_required
from django.contrib.auth.mixins import LoginRequiredMixin
from django.views.generic import TemplateView


@login_required
def dashboard(request):
    return render(request, "dashboard.html")


class DashboardView(LoginRequiredMixin, TemplateView):
    template_name = "dashboard.html"
    login_url = "login"
```

**Custom user (recommended early):**

```python
# accounts/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models


class User(AbstractUser):
    bio = models.TextField(blank=True)

# settings.py
AUTH_USER_MODEL = "accounts.User"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing `AUTH_USER_MODEL` after migrations is painful—set it at project start.
* `authenticate` returns `None` on failure; do not leak whether username exists.
* CSRF must stay enabled on login POSTs.
* API token/JWT auth is separate—use DRF authentication classes for APIs.

## 🔗 Related [#-related]

* [django-allauth](/docs/django/django-allauth)
* [Admin](/docs/django/admin)
* [Views](/docs/django/views)
* [Built-in class-based views](/docs/django/buildin-views)
* [Settings](/docs/django/settings)
* [REST framework](/docs/django/rest-framework)


# Built-in class-based views (/docs/django/buildin-views)



# Built-in class-based views [#built-in-class-based-views]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django ships generic class-based views (CBVs) for common patterns: templates, lists, details, create/update/delete, redirects, and dates. Subclass, set attributes (`model`, `queryset`, `template_name`), and wire with `as_view()` in URLconfs.

## 🔧 Core concepts [#-core-concepts]

| View                                       | Purpose                                                                |
| ------------------------------------------ | ---------------------------------------------------------------------- |
| `TemplateView`                             | Render a template with optional extra context                          |
| `RedirectView`                             | HTTP redirect                                                          |
| `ListView` / `DetailView`                  | Object collections / single object                                     |
| `CreateView` / `UpdateView` / `DeleteView` | Model form CRUD                                                        |
| `FormView`                                 | Arbitrary form                                                         |
| Date views                                 | `ArchiveIndexView`, `YearArchiveView`, …                               |
| Mixins                                     | `LoginRequiredMixin`, `PermissionRequiredMixin`, `UserPassesTestMixin` |

Lifecycle hooks: `get_queryset`, `get_context_data`, `form_valid`, `get_success_url`.

## 💡 Examples [#-examples]

**List and detail:**

```python
from django.views.generic import DetailView, ListView
from .models import Article


class ArticleListView(ListView):
    model = Article
    paginate_by = 20
    context_object_name = "articles"
    template_name = "blog/article_list.html"

    def get_queryset(self):
        return Article.objects.filter(is_published=True).select_related("author")


class ArticleDetailView(DetailView):
    model = Article
    slug_field = "slug"
    context_object_name = "article"
```

**Create with auth:**

```python
from django.contrib.auth.mixins import LoginRequiredMixin
from django.urls import reverse_lazy
from django.views.generic import CreateView
from .models import Article


class ArticleCreateView(LoginRequiredMixin, CreateView):
    model = Article
    fields = ("title", "body", "slug")
    success_url = reverse_lazy("article-list")

    def form_valid(self, form):
        form.instance.author = self.request.user
        return super().form_valid(form)
```

**URLs:**

```python
from django.urls import path
from .views import ArticleCreateView, ArticleDetailView, ArticleListView

urlpatterns = [
    path("", ArticleListView.as_view(), name="article-list"),
    path("new/", ArticleCreateView.as_view(), name="article-create"),
    path("<slug:slug>/", ArticleDetailView.as_view(), name="article-detail"),
]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `.as_view()` in `urlpatterns` passes the class, not a callable.
* `fields = "__all__"` on Create/Update can expose sensitive model fields.
* Overriding `get()` without calling `super()` drops mixin behavior.
* Multiple inheritance mixin order matters—mixins left of the base view.

## 🔗 Related [#-related]

* [Views](/docs/django/views)
* [URLs](/docs/django/urls)
* [Forms](/docs/django/forms)
* [Models](/docs/django/models)
* [Authentication](/docs/django/authentication)
* [Admin](/docs/django/admin)


# Caching (/docs/django/caching)



# Caching [#caching]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django’s cache framework stores expensive results (pages, fragments, query results) behind a pluggable backend: local memory, Memcached, Redis, database, or file. Configure `CACHES`, then use the low-level API, per-view decorators, or template fragment caching.

## 🔧 Core concepts [#-core-concepts]

| Layer      | API                                                                   |
| ---------- | --------------------------------------------------------------------- |
| Low-level  | `cache.get` / `set` / `add` / `delete` / `get_or_set`                 |
| Per-view   | `@cache_page(timeout)`                                                |
| Template   | `\{% cache timeout fragment_name %\}`                                 |
| Middleware | `UpdateCacheMiddleware` + `FetchFromCacheMiddleware`                  |
| Keys       | `make_template_fragment_key`, versioning via `KEY_PREFIX` / `VERSION` |

Backends: `LocMemCache` (dev), `RedisCache` (Django 4.0+), Memcached, DB, file.

## 💡 Examples [#-examples]

**Settings (Redis):**

```python
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "KEY_PREFIX": "myapp",
        "TIMEOUT": 300,
    }
}
```

**Low-level:**

```python
from django.core.cache import cache

def get_article(slug: str):
    key = f"article:{slug}"
    article = cache.get(key)
    if article is None:
        article = Article.objects.select_related("author").get(slug=slug)
        cache.set(key, article, timeout=60 * 10)
    return article
```

**View + template fragment:**

```python
from django.views.decorators.cache import cache_page

@cache_page(60 * 15)
def homepage(request):
    ...
```

```html
{% load cache %}
{% cache 500 sidebar request.user.pk %}
  ... expensive ...
{% endcache %}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Caching personalized pages without varying on user/session → data leaks.
* `LocMemCache` is per-process—wrong for multi-worker production.
* Stale cache after writes—invalidate keys in signals/services.
* Pickling large querysets—cache IDs or rendered HTML instead.
* Forgetting `KEY_PREFIX` when sharing Redis across apps.

## 🔗 Related [#-related]

* [Settings](/docs/django/settings)
* [Signals](/docs/django/signals)
* [Templates](/docs/django/templates)
* [Sessions](/docs/django/sessions)
* [Middleware](/docs/django/middleware)


# Context processors (/docs/django/context-processors)



# Context processors [#context-processors]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Context processors add variables to every template context for a given engine. Register callables under `TEMPLATES[i]["OPTIONS"]["context_processors"]`. Built-ins expose `request`, `user`, `perms`, `messages`, and debug info. Keep processors cheap—they run on every render.

## 🔧 Core concepts [#-core-concepts]

| Built-in           | Provides                       |
| ------------------ | ------------------------------ |
| `debug`            | `debug`, `sql_queries` (DEBUG) |
| `request`          | `request`                      |
| `auth`             | `user`, `perms`                |
| `messages`         | `messages`                     |
| `media` / `static` | `MEDIA_URL`, `STATIC_URL`      |

Signature: `def processor(request) -> dict`. Only applied when using `RequestContext` / `render()` (not bare `Context` + `Template.render` without request).

## 💡 Examples [#-examples]

**Custom processor:**

```python
# myapp/context_processors.py
from django.conf import settings


def site_meta(request):
    return {
        "SITE_NAME": getattr(settings, "SITE_NAME", "My Site"),
        "SUPPORT_EMAIL": "support@example.com",
    }
```

**Settings:**

```python
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
                "myapp.context_processors.site_meta",
            ],
        },
    },
]
```

**Template usage:**

```html
<title>{{ SITE_NAME }}</title>
{% if user.is_authenticated %}
  Hi {{ user.username }}
{% endif %}
```

## ⚠️ Pitfalls [#️-pitfalls]

* DB queries in processors → N× cost on every page.
* Assuming `request` exists when rendering without `RequestContext`.
* Name collisions with view context keys (view wins or merges—avoid overlap).
* Putting secrets into global template context.
* Forgetting to add the processor path after creating it.

## 🔗 Related [#-related]

* [Templates](/docs/django/templates)
* [Settings](/docs/django/settings)
* [Messages framework](/docs/django/messages-framework)
* [Views](/docs/django/views)
* [Authentication](/docs/django/authentication)


# Custom admin (/docs/django/custom-admin)



# Custom admin [#custom-admin]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Customize Admin beyond basic `ModelAdmin` options: actions, custom forms/widgets, computed columns, filters, permissions, and alternate `AdminSite` instances. Keep business logic in models/services; admin should orchestrate display and safe edits.

## 🔧 Core concepts [#-core-concepts]

| Technique            | Use                                                  |
| -------------------- | ---------------------------------------------------- |
| Admin actions        | Bulk operations on selected rows                     |
| `form` / `fieldsets` | Layout and validation                                |
| `@admin.display`     | Annotated list columns (Django 3.2+)                 |
| Custom filters       | `SimpleListFilter`                                   |
| Overrides            | `save_model`, `get_queryset`, `has_*_permission`     |
| Custom templates     | `change_list_template`, app templates under `admin/` |
| Multiple sites       | Subclass `AdminSite`                                 |

## 💡 Examples [#-examples]

**Action and display:**

```python
from django.contrib import admin, messages
from .models import Article


@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ("title", "word_count", "is_published")
    actions = ("publish_selected",)

    @admin.display(description="Words")
    def word_count(self, obj: Article) -> int:
        return len(obj.body.split())

    @admin.action(description="Mark selected as published")
    def publish_selected(self, request, queryset):
        updated = queryset.update(is_published=True)
        self.message_user(request, f"Published {updated} articles.", messages.SUCCESS)
```

**Restrict queryset and save:**

```python
@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    def get_queryset(self, request):
        qs = super().get_queryset(request)
        if request.user.is_superuser:
            return qs
        return qs.filter(author=request.user)

    def save_model(self, request, obj, form, change):
        if not change:
            obj.author = request.user
        super().save_model(request, obj, form, change)

    def has_delete_permission(self, request, obj=None):
        return request.user.is_superuser
```

**Custom list filter:**

```python
from django.contrib import admin


class PublishedFilter(admin.SimpleListFilter):
    title = "publication"
    parameter_name = "pub"

    def lookups(self, request, model_admin):
        return (("yes", "Published"), ("no", "Draft"))

    def queryset(self, request, queryset):
        if self.value() == "yes":
            return queryset.filter(is_published=True)
        if self.value() == "no":
            return queryset.filter(is_published=False)
        return queryset
```

## ⚠️ Pitfalls [#️-pitfalls]

* Admin actions should be idempotent and permission-checked.
* Custom HTML in columns needs careful escaping (`format_html`).
* Overriding `get_queryset` without `super()` can drop default optimizations.
* Heavy work in `list_display` methods runs per row—annotate in `get_queryset`.

## 🔗 Related [#-related]

* [Admin](/docs/django/admin)
* [Models](/docs/django/models)
* [Forms](/docs/django/forms)
* [Authentication](/docs/django/authentication)
* [Settings](/docs/django/settings)
* [Views](/docs/django/views)


# django-allauth (/docs/django/django-allauth)



# django-allauth [#django-allauth]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

[django-allauth](https://docs.allauth.org/) adds local and social authentication: registration, email verification, password reset, and providers (Google, GitHub, etc.). Prefer it over rolling your own auth UI. Works with Django 4.2+/5.x; configure via settings and include its URLs.

## 🔧 Core concepts [#-core-concepts]

| Piece                         | Role                                    |
| ----------------------------- | --------------------------------------- |
| `allauth` / `allauth.account` | Email/username accounts                 |
| `allauth.socialaccount`       | OAuth providers                         |
| `ACCOUNT_*` settings          | Verification, login methods, adapters   |
| Templates                     | Override under `templates/account/`     |
| Adapters                      | Customize redirects and signup behavior |
| Headless / API                | Newer allauth headless APIs for SPAs    |

Install: `pip install django-allauth` (add provider extras as needed).

## 💡 Examples [#-examples]

**Settings sketch:**

```python
INSTALLED_APPS = [
    # Django contrib…
    "django.contrib.sites",
    "allauth",
    "allauth.account",
    "allauth.socialaccount",
    "allauth.socialaccount.providers.github",
]

SITE_ID = 1

AUTHENTICATION_BACKENDS = [
    "django.contrib.auth.backends.ModelBackend",
    "allauth.account.auth_backends.AuthenticationBackend",
]

MIDDLEWARE = [
    # …
    "allauth.account.middleware.AccountMiddleware",  # allauth 0.56+
]

LOGIN_REDIRECT_URL = "/"
ACCOUNT_LOGOUT_REDIRECT_URL = "/"
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_EMAIL_VERIFICATION = "mandatory"  # "optional" | "none"
ACCOUNT_AUTHENTICATION_METHOD = "email"  # or "username" / "username_email"
```

**URLs:**

```python
from django.urls import include, path

urlpatterns = [
    path("accounts/", include("allauth.urls")),
]
```

**Provider settings (GitHub):**

```python
SOCIALACCOUNT_PROVIDERS = {
    "github": {
        "APP": {
            "client_id": "…",
            "secret": "…",
            "key": "",
        },
        "SCOPE": ["user:email"],
    }
}
```

Prefer env vars / `django-environ` over hardcoding secrets.

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `django.contrib.sites` + `SITE_ID` breaks allauth.
* Email backend must work in production for verification (`EMAIL_HOST` or console in dev).
* Custom user models need correct `ACCOUNT_USER_MODEL_*` / adapter settings.
* Provider callback URLs must match the OAuth app config exactly (https, path).

## 🔗 Related [#-related]

* [Authentication](/docs/django/authentication)
* [Settings](/docs/django/settings)
* [URLs](/docs/django/urls)
* [Views](/docs/django/views)
* [Admin](/docs/django/admin)
* [REST framework](/docs/django/rest-framework)


# Email (/docs/django/email)



# Email [#email]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Send mail via `django.core.mail` using a configurable `EMAIL_BACKEND`. Dev: console or locmem; prod: SMTP or transactional providers. Prefer `EmailMessage` / `EmailMultiAlternatives` for headers, attachments, and HTML+text.

## 🔧 Core concepts [#-core-concepts]

| API                             | Role                        |
| ------------------------------- | --------------------------- |
| `send_mail`                     | Simple helper               |
| `mail_admins` / `mail_managers` | Ops alerts                  |
| `EmailMessage`                  | Full control                |
| `EmailMultiAlternatives`        | text + HTML                 |
| `get_connection`                | Explicit backend/connection |
| `EMAIL_*` settings              | Host, TLS, from address     |

Backends: SMTP, console, locmem, filebased, dummy.

## 💡 Examples [#-examples]

**Settings:**

```python
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.example.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "apikey"
EMAIL_HOST_PASSWORD = env("EMAIL_PASSWORD")
DEFAULT_FROM_EMAIL = "noreply@example.com"
```

**Simple send:**

```python
from django.core.mail import send_mail

send_mail(
    subject="Welcome",
    message="Thanks for joining.",
    from_email=None,  # DEFAULT_FROM_EMAIL
    recipient_list=["user@example.com"],
    fail_silently=False,
)
```

**HTML + attachment:**

```python
from django.core.mail import EmailMultiAlternatives

msg = EmailMultiAlternatives(
    subject="Invoice",
    body="Your invoice is attached.",
    from_email="billing@example.com",
    to=["user@example.com"],
)
msg.attach_alternative("<p>Your <strong>invoice</strong> is attached.</p>", "text/html")
msg.attach("invoice.pdf", pdf_bytes, "application/pdf")
msg.send()
```

**Tests:**

```python
from django.core import mail

self.assertEqual(len(mail.outbox), 1)
self.assertEqual(mail.outbox[0].subject, "Welcome")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Sending synchronously in request path—use a queue for volume.
* `fail_silently=True` hiding misconfiguration.
* Header injection via unsanitized subject/addresses.
* HTML-only mail without text alternative.
* Hardcoding credentials—use env / secrets manager.

## 🔗 Related [#-related]

* [Settings](/docs/django/settings)
* [Testing](/docs/django/testing)
* [Management commands](/docs/django/management-commands)
* [Security](/docs/django/security)
* [Authentication](/docs/django/authentication)


# File uploads (/docs/django/file-uploads)



# File uploads [#file-uploads]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Uploaded files arrive on `request.FILES`. Model `FileField` / `ImageField` store paths under `MEDIA_ROOT` and expose URLs via `MEDIA_URL`. Validate size/type; never trust client filenames. In production, serve media from object storage or a dedicated host—not the app process.

## 🔧 Core concepts [#-core-concepts]

| Piece                           | Role                          |
| ------------------------------- | ----------------------------- |
| `request.FILES`                 | Uploaded file mapping         |
| `FileField` / `ImageField`      | Model storage                 |
| `enctype="multipart/form-data"` | Required on forms             |
| `upload_to`                     | Path callable / string        |
| `STORAGES["default"]`           | Backend (local, S3, …)        |
| Validators                      | Size, extension, content-type |

Temporary files use `TemporaryUploadedFile` above `FILE_UPLOAD_MAX_MEMORY_SIZE`.

## 💡 Examples [#-examples]

**Model + form:**

```python
import uuid
from pathlib import Path

from django.db import models


def avatar_path(instance, filename):
    ext = Path(filename).suffix.lower()
    return f"avatars/{instance.pk}/{uuid.uuid4().hex}{ext}"


class Profile(models.Model):
    user = models.OneToOneField("auth.User", on_delete=models.CASCADE)
    avatar = models.ImageField(upload_to=avatar_path, blank=True)
```

```python
from django import forms


class ProfileForm(forms.ModelForm):
    class Meta:
        model = Profile
        fields = ("avatar",)
```

**View:**

```python
def upload_avatar(request):
    if request.method == "POST":
        form = ProfileForm(request.POST, request.FILES, instance=request.user.profile)
        if form.is_valid():
            form.save()
            return redirect("profile")
    else:
        form = ProfileForm(instance=request.user.profile)
    return render(request, "upload.html", {"form": form})
```

```html
<form method="post" enctype="multipart/form-data">
  {% csrf_token %}
  {{ form.as_p }}
  <button type="submit">Upload</button>
</form>
```

**Settings:**

```python
MEDIA_URL = "/media/"
MEDIA_ROOT = BASE_DIR / "media"
DATA_UPLOAD_MAX_MEMORY_SIZE = 5 * 1024 * 1024
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `enctype` → empty `request.FILES`.
* Serving user uploads as static executable content → XSS/RCE risk.
* Trusting `Content-Type` / extension alone—inspect content when needed.
* Not deleting old files on replace (storage orphans).
* Huge uploads without size limits or streaming.

## 🔗 Related [#-related]

* [Forms](/docs/django/forms)
* [Models](/docs/django/models)
* [Validators](/docs/django/validators)
* [Static files](/docs/django/static-files)
* [Security](/docs/django/security)
* [Settings](/docs/django/settings)


# Forms (/docs/django/forms)



# Forms [#forms]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django forms validate and clean user input, then render HTML widgets. Use `Form` for unbound data and `ModelForm` to map model fields. Always validate with `is_valid()` and read `cleaned_data`—never raw `request.POST` for business logic.

## 🔧 Core concepts [#-core-concepts]

| Piece                     | Role                                 |
| ------------------------- | ------------------------------------ |
| `forms.Form`              | Standalone fields + validation       |
| `forms.ModelForm`         | Bound to a model                     |
| `clean_<field>` / `clean` | Field-level / cross-field validation |
| Widgets                   | Control HTML input types             |
| CSRF                      | `\{% csrf_token %\}` on POST forms   |
| Formsets                  | Edit collections of forms            |

Bound form: data from request; unbound: empty for GET display.

## 💡 Examples [#-examples]

**ModelForm:**

```python
from django import forms
from .models import Article


class ArticleForm(forms.ModelForm):
    class Meta:
        model = Article
        fields = ("title", "slug", "body")
        widgets = {
            "body": forms.Textarea(attrs={"rows": 10}),
        }

    def clean_title(self):
        title = self.cleaned_data["title"].strip()
        if len(title) < 3:
            raise forms.ValidationError("Title too short.")
        return title
```

**View usage:**

```python
from django.shortcuts import redirect, render
from .forms import ArticleForm


def article_create(request):
    if request.method == "POST":
        form = ArticleForm(request.POST)
        if form.is_valid():
            article = form.save(commit=False)
            article.author = request.user
            article.save()
            return redirect(article)
    else:
        form = ArticleForm()
    return render(request, "blog/article_form.html", {"form": form})
```

**Template:**

```html
<form method="post" novalidate>
  {% csrf_token %}
  {{ form.non_field_errors }}
  {{ form.as_p }}
  <button type="submit">Save</button>
</form>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Skipping CSRF on POSTs yields 403.
* `form.save()` on invalid forms is wrong—check `is_valid()` first.
* `fields = "__all__"` may expose fields you did not intend.
* File uploads need `request.FILES` and `enctype="multipart/form-data"`.

## 🔗 Related [#-related]

* [Views](/docs/django/views)
* [Models](/docs/django/models)
* [Built-in class-based views](/docs/django/buildin-views)
* [Admin](/docs/django/admin)
* [Serializers](/docs/django/serializers)
* [Authentication](/docs/django/authentication)


# Glossary (/docs/django/glossary)



# Glossary [#glossary]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core Django terms for models, views, templates, auth, and the request/response cycle.

## 🔧 Core concepts [#-core-concepts]

| Term               | Definition                                                                |
| ------------------ | ------------------------------------------------------------------------- |
| Admin              | The built-in CRUD interface generated from registered models.             |
| App                | A self-contained Django package under `INSTALLED_APPS` with models/views. |
| ASGI               | Async server gateway interface used for async Django and Channels.        |
| Authentication     | Verifying who a user is, typically via sessions or tokens.                |
| CSRF               | Cross-Site Request Forgery protection built into Django forms/middleware. |
| Field              | A model attribute that maps to a database column and validation rules.    |
| Form               | A class that validates and cleans submitted input data.                   |
| Management command | A CLI task run with `python manage.py <command>`.                         |
| Manager            | The interface attached to models for building QuerySets (`objects`).      |
| Middleware         | Hooks that process requests and responses globally.                       |
| Migration          | A versioned schema change applied to the database.                        |
| Model              | A Python class mapping to a database table via the ORM.                   |
| MVT                | Model–View–Template, Django’s primary architectural pattern.              |
| ORM                | Object-relational mapper that turns model APIs into SQL.                  |
| Permission         | A flag controlling whether a user may perform an action.                  |
| Project            | The top-level Django configuration package created by `startproject`.     |
| QuerySet           | A lazy, chainable representation of a database query.                     |
| Request            | The `HttpRequest` object representing an incoming HTTP call.              |
| Serializer         | DRF component that converts models to/from JSON (and validates).          |
| Settings           | Project configuration module (`settings.py` / env-driven values).         |
| Signal             | A dispatcher that notifies receivers when certain actions occur.          |
| Static files       | CSS, JS, and images collected and served separately from media uploads.   |
| Template           | An HTML file with Django template language tags and filters.              |
| URLConf            | The URL routing table mapping paths to views.                             |
| View               | A callable that takes a request and returns a response.                   |
| WSGI               | Web Server Gateway Interface used by traditional sync Django deploys.     |

## 💡 Examples [#-examples]

**Model and QuerySet:**

```python
class Post(models.Model):
    title = models.CharField(max_length=200)
    published = models.BooleanField(default=False)

Post.objects.filter(published=True).order_by("-id")
```

**URL and view:**

```python
# urls.py
path("posts/<int:pk>/", views.post_detail, name="post_detail")

# views.py
def post_detail(request, pk):
    post = get_object_or_404(Post, pk=pk)
    return render(request, "posts/detail.html", {"post": post})
```

**Migration workflow:**

```shellscript
python manage.py makemigrations
python manage.py migrate
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **project** (site config) with **app** (feature package).
* Mixing **Form** validation with **Serializer** validation in DRF projects.
* Treating a **QuerySet** as immediately executed — it is lazy until evaluated.
* Equating **authentication** (who you are) with **permission** (what you may do).
* Assuming **static files** and **media uploads** are the same storage path.

## 🔗 Related [#-related]

* [models](/docs/django/models)
* [views](/docs/django/views)
* [templates](/docs/django/templates)
* [queryset](/docs/django/queryset)
* [authentication](/docs/django/authentication)
* [migrations](/docs/django/migrations)


# i18n (/docs/django/i18n)



# i18n [#i18n]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Internationalization (i18n) marks strings for translation; localization (l10n) formats dates, numbers, and timezones. Use `gettext` / `gettext_lazy`, `\{% translate %\}`, and `makemessages` / `compilemessages`. Activate languages via middleware, URLs, or explicit `activate()`.

## 🔧 Core concepts [#-core-concepts]

| Piece                           | Role                                   |
| ------------------------------- | -------------------------------------- |
| `gettext` / `_`                 | Eager translate                        |
| `gettext_lazy` / `gettext_noop` | Lazy / mark only                       |
| `ngettext`                      | Plurals                                |
| `LocaleMiddleware`              | Per-request language                   |
| `LANGUAGE_CODE` / `LANGUAGES`   | Defaults / available                   |
| `USE_I18N` / `USE_L10N`         | Feature flags (L10N always on in 5.0+) |
| `makemessages`                  | Build `.po`                            |
| `compilemessages`               | `.po` → `.mo`                          |

Timezone: `USE_TZ = True`, `timezone.now()`, activate user TZ in middleware.

## 💡 Examples [#-examples]

**Python:**

```python
from django.utils.translation import gettext as _
from django.utils.translation import gettext_lazy as _lazy
from django.db import models


class Article(models.Model):
    title = models.CharField(_lazy("Title"), max_length=200)


def greet(name: str) -> str:
    return _("Hello, %(name)s") % {"name": name}
```

**Template:**

```html
{% load i18n %}
{% translate "Welcome" %}
{% blocktranslate count counter=items|length %}
  One item
{% plural %}
  {{ counter }} items
{% endblocktranslate %}
<form action="{% url 'set_language' %}" method="post">
  {% csrf_token %}
  <input name="language" value="es">
  <button type="submit">ES</button>
</form>
```

**Commands / settings:**

```python
LANGUAGE_CODE = "en-us"
LANGUAGES = [("en", "English"), ("es", "Spanish")]
LOCALE_PATHS = [BASE_DIR / "locale"]
MIDDLEWARE = [
    ...
    "django.middleware.locale.LocaleMiddleware",
    ...
]
```

```shellscript
django-admin makemessages -l es
django-admin compilemessages
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using `_()` at module import for model `verbose_name`—prefer `_lazy`.
* Interpolating before translating breaks message catalogs.
* Missing `LocaleMiddleware` order (after Session, before Common).
* Forgetting to compile `.mo` in deploy.
* Hardcoded date formats—use `localize` / `date` filters.

## 🔗 Related [#-related]

* [Settings](/docs/django/settings)
* [Templates](/docs/django/templates)
* [Middleware](/docs/django/middleware)
* [Models](/docs/django/models)
* [URLs](/docs/django/urls)


# Django (/docs/django)



# Django [#django]

ORM, views, auth, DRF.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Management commands (/docs/django/management-commands)



# Management commands [#management-commands]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Custom `manage.py` commands live under `app/management/commands/`. Subclass `BaseCommand`, implement `handle`, and optionally declare arguments. Use for one-off jobs, cron entrypoints, data backfills, and ops scripts that need Django setup.

## 🔧 Core concepts [#-core-concepts]

| Piece                         | Role                            |
| ----------------------------- | ------------------------------- |
| `BaseCommand`                 | Base class                      |
| `add_arguments`               | `argparse`-style options        |
| `handle(*args, **options)`    | Main body                       |
| `self.stdout` / `self.stderr` | Output (respects `--verbosity`) |
| `CommandError`                | Abort with non-zero exit        |
| `requires_system_checks`      | Skip/alter system checks        |
| `help`                        | Shown in `manage.py help`       |

Package layout: `management/__init__.py`, `commands/__init__.py`, `commands/my_cmd.py`.

## 💡 Examples [#-examples]

**Command with args:**

```python
# blog/management/commands/publish_drafts.py
from django.core.management.base import BaseCommand, CommandError
from django.utils import timezone

from blog.models import Article


class Command(BaseCommand):
    help = "Publish draft articles older than N days"

    def add_arguments(self, parser):
        parser.add_argument("--days", type=int, default=7)
        parser.add_argument("--dry-run", action="store_true")

    def handle(self, *args, **options):
        days = options["days"]
        cutoff = timezone.now() - timezone.timedelta(days=days)
        qs = Article.objects.filter(is_published=False, created_at__lte=cutoff)
        count = qs.count()
        if options["dry_run"]:
            self.stdout.write(f"Would publish {count} articles")
            return
        updated = qs.update(is_published=True, published_at=timezone.now())
        self.stdout.write(self.style.SUCCESS(f"Published {updated}"))
```

**Run:**

```shellscript
python manage.py publish_drafts --days 3 --dry-run
python manage.py publish_drafts --days 3
```

**Call from code:**

```python
from django.core.management import call_command

call_command("publish_drafts", days=3, verbosity=0)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `__init__.py` files → command not discovered.
* Doing HTTP/request work without timeouts in long jobs.
* Not wrapping multi-step DB work in `transaction.atomic()`.
* Printing secrets at high verbosity.
* Blocking the web process—run via cron/worker, not inside a view.

## 🔗 Related [#-related]

* [Models](/docs/django/models)
* [Migrations](/docs/django/migrations)
* [Transactions / ORM](/docs/django/transactions-orm)
* [Settings](/docs/django/settings)
* [Testing](/docs/django/testing)


# Managers (/docs/django/managers)



# Managers [#managers]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Managers are the interface for table-level ORM operations (`Model.objects`). Customize to encapsulate reusable querysets (published, for\_user, …). Prefer chaining a custom `QuerySet` class and exposing it via `as_manager()` or `from_queryset`.

## 🔧 Core concepts [#-core-concepts]

| Piece             | Role                            |
| ----------------- | ------------------------------- |
| `models.Manager`  | Default `objects`               |
| Custom `Manager`  | Extra methods / default filters |
| Custom `QuerySet` | Chainable filters               |
| `as_manager()`    | Manager from QuerySet           |
| `from_queryset`   | Manager + QuerySet methods      |
| Multiple managers | e.g. `objects`, `published`     |

Related managers on reverse FK/M2M are separate (`article.tags`).

## 💡 Examples [#-examples]

**QuerySet + manager:**

```python
from django.db import models


class ArticleQuerySet(models.QuerySet):
    def published(self):
        return self.filter(is_published=True)

    def by_author(self, user):
        return self.filter(author=user)


class Article(models.Model):
    title = models.CharField(max_length=200)
    is_published = models.BooleanField(default=False)
    author = models.ForeignKey("auth.User", on_delete=models.CASCADE)

    objects = ArticleQuerySet.as_manager()
```

```python
Article.objects.published().by_author(request.user)
```

**Manager with default filter (use carefully):**

```python
class PublishedManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(is_published=True)


class Article(models.Model):
    ...
    objects = models.Manager()
    published = PublishedManager()
```

**from\_queryset:**

```python
ArticleManager = models.Manager.from_queryset(ArticleQuerySet)

class Article(models.Model):
    objects = ArticleManager()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Overriding `get_queryset` on the only manager hides rows in admin—keep a full `objects`.
* Soft-delete managers that break FK integrity unexpectedly.
* Putting create/update business logic only on managers without tests.
* Forgetting related name clashes when adding managers.
* Custom managers not used by `RelatedManager`—re-declare with `base_manager_name` / `default_manager_name` in Meta when needed.

## 🔗 Related [#-related]

* [Models](/docs/django/models)
* [QuerySet](/docs/django/queryset)
* [Admin](/docs/django/admin)
* [Transactions / ORM](/docs/django/transactions-orm)
* [Testing](/docs/django/testing)


# Messages framework (/docs/django/messages-framework)



# Messages framework [#messages-framework]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`django.contrib.messages` stores one-time flash messages (success, error, …) for the next request, typically in the session (or cookie). Add message in a view; display in the base template. Requires `MessageMiddleware` and the messages context processor.

## 🔧 Core concepts [#-core-concepts]

| Level   | Constant / tag     |
| ------- | ------------------ |
| Debug   | `messages.DEBUG`   |
| Info    | `messages.INFO`    |
| Success | `messages.SUCCESS` |
| Warning | `messages.WARNING` |
| Error   | `messages.ERROR`   |

APIs: `messages.add_message`, shortcuts `success` / `error` / `warning` / `info` / `debug`. Storage backends: session (default), cookie, fallback.

## 💡 Examples [#-examples]

**View:**

```python
from django.contrib import messages
from django.shortcuts import redirect


def save_article(request):
    form = ArticleForm(request.POST)
    if form.is_valid():
        form.save()
        messages.success(request, "Article saved.")
        return redirect("article-list")
    messages.error(request, "Please fix the errors below.")
    return render(request, "form.html", {"form": form})
```

**Template:**

```html
{% if messages %}
  <ul class="messages">
    {% for message in messages %}
      <li class="{{ message.tags }}">{{ message }}</li>
    {% endfor %}
  </ul>
{% endif %}
```

**Settings extras:**

```python
from django.contrib.messages import constants as message_constants

MESSAGE_LEVEL = message_constants.INFO
MESSAGE_TAGS = {
    message_constants.ERROR: "danger",  # Bootstrap-friendly
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing middleware / context processor → messages never show.
* Consuming messages twice (iterate in view and template).
* Cookie storage size limits for long messages.
* AJAX flows need JSON/toast handling—session flashes suit full page loads.
* Setting messages then returning the same template without redirect can work, but PRG (Post/Redirect/Get) avoids resubmit issues.

## 🔗 Related [#-related]

* [Sessions](/docs/django/sessions)
* [Middleware](/docs/django/middleware)
* [Context processors](/docs/django/context-processors)
* [Views](/docs/django/views)
* [Templates](/docs/django/templates)


# Middleware (/docs/django/middleware)



# Middleware [#middleware]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Middleware is a hook into Django’s request/response cycle. Each class can process the request before the view, the response after, and exceptions. Order in `MIDDLEWARE` matters—security and session middleware run early; custom logic usually sits after auth.

## 🔧 Core concepts [#-core-concepts]

| Piece                       | Role                                                     |
| --------------------------- | -------------------------------------------------------- |
| `__init__(get_response)`    | Store next callable (Django 1.10+ style)                 |
| `__call__(request)`         | Process request → call `get_response` → process response |
| `process_view`              | After URL resolve, before view (optional)                |
| `process_exception`         | On view exception (optional)                             |
| `process_template_response` | For `TemplateResponse` (optional)                        |
| Short-circuit               | Return `HttpResponse` without calling `get_response`     |

Built-ins: `SecurityMiddleware`, `SessionMiddleware`, `CommonMiddleware`, `CsrfViewMiddleware`, `AuthenticationMiddleware`, `MessageMiddleware`, `XFrameOptionsMiddleware`.

## 💡 Examples [#-examples]

**Simple timing middleware:**

```python
import time
from django.utils.deprecation import MiddlewareMixin  # avoid if possible


class TimingMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        start = time.perf_counter()
        response = self.get_response(request)
        elapsed_ms = (time.perf_counter() - start) * 1000
        response["X-Request-Duration-Ms"] = f"{elapsed_ms:.1f}"
        return response
```

**Settings:**

```python
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
    "myapp.middleware.TimingMiddleware",
]
```

**Short-circuit (maintenance mode):**

```python
from django.http import HttpResponse

class MaintenanceMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        if getattr(settings, "MAINTENANCE_MODE", False):
            return HttpResponse("Down for maintenance", status=503)
        return self.get_response(request)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Wrong order: CSRF after session; auth after session.
* Mutating `request` after the view has run does nothing useful for that response.
* Heavy work in middleware hits every request—cache or skip static paths.
* Prefer new-style `__call__` over deprecated `MiddlewareMixin` patterns.
* Async views need async-capable middleware on ASGI (Django 4.1+).

## 🔗 Related [#-related]

* [Settings](/docs/django/settings)
* [Views](/docs/django/views)
* [Sessions](/docs/django/sessions)
* [Security](/docs/django/security)
* [Authentication](/docs/django/authentication)
* [ASGI / Channels](/docs/django/asgi-channels)


# Migrations (/docs/django/migrations)



# Migrations [#migrations]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Migrations version the database schema to match models. Workflow: change models → `makemigrations` → review → `migrate`. Keep migrations in VCS; never edit applied production migrations casually—add a new one instead.

## 🔧 Core concepts [#-core-concepts]

| Command            | Role                                                           |
| ------------------ | -------------------------------------------------------------- |
| `makemigrations`   | Detect model changes, write migration files                    |
| `migrate`          | Apply / unapply migrations                                     |
| `showmigrations`   | Status per app                                                 |
| `sqlmigrate`       | Preview SQL                                                    |
| `squashmigrations` | Collapse history                                               |
| Operations         | `CreateModel`, `AddField`, `AlterField`, `RunPython`, `RunSQL` |

Dependencies graph ensures order across apps. Data migrations use `RunPython` / `RunPython.noop`.

## 💡 Examples [#-examples]

**Generate and apply:**

```shellscript
python manage.py makemigrations blog
python manage.py migrate
python manage.py showmigrations blog
python manage.py sqlmigrate blog 0003
```

**Data migration:**

```python
from django.db import migrations


def forwards(apps, schema_editor):
    Article = apps.get_model("blog", "Article")
    Article.objects.filter(slug="").update(slug="untitled")


def backwards(apps, schema_editor):
    pass


class Migration(migrations.Migration):
    dependencies = [("blog", "0002_article_slug")]

    operations = [
        migrations.RunPython(forwards, backwards),
    ]
```

**Fake / zero (careful):**

```shellscript
python manage.py migrate blog 0002
python manage.py migrate blog zero          # unapply all for app
python manage.py migrate blog 0003 --fake   # mark applied, no SQL
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using real model classes in `RunPython`—always `apps.get_model`.
* Renaming models/fields without `RenameModel` / `RenameField` drops and recreates data.
* Circular dependencies between apps—split or use `SeparateDatabaseAndState`.
* Editing already-deployed migrations breaks other environments.
* Long locks on large `AlterField`—plan downtime or online schema tools.

## 🔗 Related [#-related]

* [Models](/docs/django/models)
* [Managers](/docs/django/managers)
* [QuerySet](/docs/django/queryset)
* [Settings](/docs/django/settings)
* [Testing](/docs/django/testing)


# Models (/docs/django/models)



# Models [#models]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Models define database tables via Django ORM. Subclass `django.db.models.Model`, declare fields and `Meta`, then `makemigrations` / `migrate`. Prefer explicit `related_name`, indexes for common filters, and `get_absolute_url` for object links.

## 🔧 Core concepts [#-core-concepts]

| Piece      | Role                                                                         |
| ---------- | ---------------------------------------------------------------------------- |
| Fields     | `CharField`, `TextField`, `ForeignKey`, `ManyToManyField`, …                 |
| Options    | `null`, `blank`, `default`, `unique`, `db_index`                             |
| Relations  | FK / M2M / O2O with `on_delete`                                              |
| Managers   | `objects` / custom `Manager` + `QuerySet`                                    |
| Meta       | `ordering`, `constraints`, `indexes`, `unique_together` → `UniqueConstraint` |
| Migrations | Schema evolution under `migrations/`                                         |

`null` is DB-level; `blank` is validation/forms-level.

## 💡 Examples [#-examples]

**Typical model:**

```python
from django.conf import settings
from django.db import models
from django.urls import reverse


class Article(models.Model):
    title = models.CharField(max_length=200)
    slug = models.SlugField(unique=True)
    body = models.TextField()
    author = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="articles",
    )
    is_published = models.BooleanField(default=False)
    published_at = models.DateTimeField(null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        ordering = ("-published_at", "-pk")
        indexes = [
            models.Index(fields=["is_published", "published_at"]),
        ]

    def __str__(self) -> str:
        return self.title

    def get_absolute_url(self):
        return reverse("article-detail", kwargs={"slug": self.slug})
```

**Query patterns:**

```python
Article.objects.filter(is_published=True).select_related("author")
Article.objects.prefetch_related("tags")
Article.objects.get(slug="hello")
```

## ⚠️ Pitfalls [#️-pitfalls]

* `CharField(null=True)` usually wrong—use `blank=True` + default `""`.
* Missing `on_delete` on `ForeignKey` is required.
* N+1 queries: use `select_related` / `prefetch_related`.
* Changing fields without migrations desyncs DB and code.
* Avoid circular imports—use string references `"app.Model"`.

## 🔗 Related [#-related]

* [Admin](/docs/django/admin)
* [Forms](/docs/django/forms)
* [Serializers](/docs/django/serializers)
* [Views](/docs/django/views)
* [Settings](/docs/django/settings)
* [REST framework](/docs/django/rest-framework)


# Pagination (/docs/django/pagination)



# Pagination [#pagination]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Paginator` splits a queryset or sequence into pages. Use in function views, `ListView` (`paginate_by`), or DRF pagination classes. Prefer queryset pagination (LIMIT/OFFSET or keyset) over loading all rows into memory.

## 🔧 Core concepts [#-core-concepts]

| Piece                                            | Role          |
| ------------------------------------------------ | ------------- |
| `Paginator(object_list, per_page)`               | Build pages   |
| `page(number)`                                   | `Page` object |
| `Page.object_list`                               | Items on page |
| `has_next` / `has_previous`                      | Navigation    |
| `ListView.paginate_by`                           | CBV helper    |
| `InvalidPage` / `EmptyPage` / `PageNotAnInteger` | Errors        |

DRF: `PageNumberPagination`, `LimitOffsetPagination`, `CursorPagination`.

## 💡 Examples [#-examples]

**Function view:**

```python
from django.core.paginator import Paginator, EmptyPage, PageNotAnInteger
from django.shortcuts import render

from .models import Article


def article_list(request):
    qs = Article.objects.filter(is_published=True).order_by("-pk")
    paginator = Paginator(qs, 20)
    page_number = request.GET.get("page")
    try:
        page = paginator.page(page_number)
    except PageNotAnInteger:
        page = paginator.page(1)
    except EmptyPage:
        page = paginator.page(paginator.num_pages)
    return render(request, "blog/list.html", {"page": page})
```

**ListView:**

```python
from django.views.generic import ListView


class ArticleList(ListView):
    model = Article
    paginate_by = 20
    queryset = Article.objects.filter(is_published=True)
```

**Template:**

```html
{% for article in page %}
  <li>{{ article.title }}</li>
{% endfor %}
{% if page.has_previous %}
  <a href="?page={{ page.previous_page_number }}">Prev</a>
{% endif %}
{% if page.has_next %}
  <a href="?page={{ page.next_page_number }}">Next</a>
{% endif %}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Unordered querysets → unstable pages; always `order_by`.
* Large OFFSET is slow—consider cursor/keyset pagination for deep pages.
* Counting huge tables on every request—cache `count` or approximate.
* Mixing GET filters without preserving querystring in page links.
* Evaluating full queryset before paginating.

## 🔗 Related [#-related]

* [QuerySet](/docs/django/queryset)
* [Views](/docs/django/views)
* [Templates](/docs/django/templates)
* [REST framework](/docs/django/rest-framework)
* [buildin\_views](/docs/django/buildin-views)


# Permissions (/docs/django/permissions)



# Permissions [#permissions]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django auth permissions are `app_label.codename` triples (add/change/delete/view plus custom). Attach via groups or directly on users. Enforce with mixins, decorators, `user.has_perm`, or DRF permission classes. Object-level rules need custom checks or packages like django-guardian.

## 🔧 Core concepts [#-core-concepts]

| Piece                                            | Role                                    |
| ------------------------------------------------ | --------------------------------------- |
| Default perms                                    | Auto-created per model                  |
| Custom                                           | `Meta.permissions` or `Permission` rows |
| Groups                                           | Bundle permissions                      |
| `user_passes_test` / `permission_required`       | Function views                          |
| `PermissionRequiredMixin` / `LoginRequiredMixin` | CBVs                                    |
| `has_perm` / `has_module_perms`                  | Checks                                  |

Superusers pass all permission checks.

## 💡 Examples [#-examples]

**Model custom permission:**

```python
class Article(models.Model):
    ...

    class Meta:
        permissions = [
            ("publish_article", "Can publish article"),
        ]
```

**CBV:**

```python
from django.contrib.auth.mixins import LoginRequiredMixin, PermissionRequiredMixin
from django.views.generic import UpdateView

from .models import Article


class ArticleUpdate(LoginRequiredMixin, PermissionRequiredMixin, UpdateView):
    model = Article
    fields = ("title", "body")
    permission_required = "blog.change_article"
```

**Function view + check:**

```python
from django.contrib.auth.decorators import login_required, permission_required


@login_required
@permission_required("blog.publish_article", raise_exception=True)
def publish(request, pk):
    ...
```

**Programmatic:**

```python
from django.contrib.auth.models import Permission
from django.contrib.contenttypes.models import ContentType

ct = ContentType.objects.get_for_model(Article)
perm = Permission.objects.get(codename="publish_article", content_type=ct)
user.user_permissions.add(perm)
user.has_perm("blog.publish_article")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Checking only authentication, not authorization.
* Caching stale `user.user_permissions` after changes in the same request—refetch or clear cache.
* Object ownership ≠ model permission—implement explicitly.
* DRF: browser session auth vs token auth need matching permission classes.
* Forgetting `raise_exception=True` → silent redirect to login on 403 cases.

## 🔗 Related [#-related]

* [Authentication](/docs/django/authentication)
* [Views](/docs/django/views)
* [REST framework](/docs/django/rest-framework)
* [Testing](/docs/django/testing)
* [Security](/docs/django/security)


# QuerySet (/docs/django/queryset)



# QuerySet [#queryset]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A `QuerySet` is a lazy, chainable representation of a DB query. Evaluation happens on iteration, `list()`, `bool()`, slicing with step, or terminal methods (`get`, `count`, `exists`, `aggregate`). Optimize with `select_related` / `prefetch_related` and defer unused fields.

## 🔧 Core concepts [#-core-concepts]

| API                                             | Role                                |
| ----------------------------------------------- | ----------------------------------- |
| `filter` / `exclude`                            | Narrow rows (`Q` for OR/complex)    |
| `get`                                           | Exactly one row or raise            |
| `create` / `get_or_create` / `update_or_create` | Write helpers                       |
| `annotate` / `aggregate`                        | Per-row / whole-set aggregates      |
| `order_by` / `distinct`                         | Sort / unique                       |
| `values` / `values_list`                        | Dicts / tuples instead of models    |
| `select_related`                                | JOIN for FK / O2O                   |
| `prefetch_related`                              | Separate query for M2M / reverse FK |
| `only` / `defer`                                | Column subset                       |
| `iterator`                                      | Stream large results                |

Lookups: `field__lookup` (`exact`, `iexact`, `contains`, `in`, `gt`, `isnull`, …).

## 💡 Examples [#-examples]

**Filtering and Q objects:**

```python
from django.db.models import Q, Count

Article.objects.filter(is_published=True).exclude(author=None)

Article.objects.filter(
    Q(title__icontains="django") | Q(tags__name="python")
).distinct()
```

**Related + annotate:**

```python
qs = (
    Article.objects.filter(is_published=True)
    .select_related("author")
    .prefetch_related("tags")
    .annotate(tag_count=Count("tags"))
    .order_by("-published_at")
)
```

**Updates and existence:**

```python
Article.objects.filter(pk=1).update(is_published=True)  # no signals
Article.objects.filter(slug="hello").exists()
Article.objects.values_list("id", flat=True)
```

## ⚠️ Pitfalls [#️-pitfalls]

* N+1: accessing `.author` / `.tags.all()` in a loop without prefetch.
* Evaluating the same queryset twice unexpectedly (cache after first eval).
* `get()` raises `DoesNotExist` / `MultipleObjectsReturned`.
* Chaining after slicing can be restricted; prefer filter before slice.
* `update()` / `bulk_create` skip `save()` and most signals.

## 🔗 Related [#-related]

* [Models](/docs/django/models)
* [Managers](/docs/django/managers)
* [Transactions / ORM](/docs/django/transactions-orm)
* [Pagination](/docs/django/pagination)
* [Testing](/docs/django/testing)


# REST framework (/docs/django/rest-framework)



# REST framework [#rest-framework]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django REST framework (DRF) builds Web APIs on Django: serializers, views/viewsets, routers, authentication, and permissions. Use for JSON APIs consumed by SPAs and mobile apps. Pair with Django 4.2+/5.x; install `djangorestframework`.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                                        |
| ---------------------- | ------------------------------------------- |
| Serializers            | Validate input / render output              |
| `APIView` / generics   | Class-based API endpoints                   |
| ViewSets + Routers     | CRUD URL wiring                             |
| Authentication         | Session, Token, JWT (3rd party), etc.       |
| Permissions            | `IsAuthenticated`, `IsAdminUser`, custom    |
| Pagination / filtering | `DEFAULT_PAGINATION_CLASS`, `django-filter` |
| Browsable API          | HTML forms for debugging                    |

Settings live under `REST_FRAMEWORK = \{...\}`.

## 💡 Examples [#-examples]

**Install & settings:**

```python
INSTALLED_APPS = [
    # …
    "rest_framework",
]

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework.authentication.SessionAuthentication",
        "rest_framework.authentication.BasicAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticatedOrReadOnly",
    ],
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 20,
}
```

**ViewSet + router:**

```python
# api/views.py
from rest_framework import viewsets
from rest_framework.permissions import IsAuthenticatedOrReadOnly
from .models import Article
from .serializers import ArticleSerializer


class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.select_related("author").all()
    serializer_class = ArticleSerializer
    permission_classes = [IsAuthenticatedOrReadOnly]
    lookup_field = "slug"

    def perform_create(self, serializer):
        serializer.save(author=self.request.user)
```

```python
# config/urls.py
from django.urls import include, path
from rest_framework.routers import DefaultRouter
from api.views import ArticleViewSet

router = DefaultRouter()
router.register("articles", ArticleViewSet, basename="article")

urlpatterns = [
    path("api/", include(router.urls)),
    path("api-auth/", include("rest_framework.urls")),
]
```

**Function-style `@api_view`:**

```python
from rest_framework.decorators import api_view, permission_classes
from rest_framework.permissions import AllowAny
from rest_framework.response import Response


@api_view(["GET"])
@permission_classes([AllowAny])
def health(request):
    return Response({"status": "ok"})
```

## ⚠️ Pitfalls [#️-pitfalls]

* CSRF: SessionAuthentication requires CSRF on unsafe methods from browsers.
* Exposing `ModelViewSet` without permissions is a data leak.
* N+1 in serializers—use `select_related` on the queryset.
* Do not put secrets in browsable API responses.

## 🔗 Related [#-related]

* [Serializers](/docs/django/serializers)
* [Authentication](/docs/django/authentication)
* [URLs](/docs/django/urls)
* [Views](/docs/django/views)
* [Models](/docs/django/models)
* [Settings](/docs/django/settings)


# Security (/docs/django/security)



# Security [#security]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django provides CSRF protection, XSS escaping, clickjacking headers, host validation, and SSL redirects. Harden production settings (`DEBUG=False`, secure cookies, HSTS). Treat user input and uploads as hostile; keep secrets out of code and VCS.

## 🔧 Core concepts [#-core-concepts]

| Control      | Mechanism                          |
| ------------ | ---------------------------------- |
| CSRF         | Token + `CsrfViewMiddleware`       |
| XSS          | Template auto-escape               |
| Clickjacking | `XFrameOptionsMiddleware`          |
| Host header  | `ALLOWED_HOSTS`                    |
| HTTPS        | `SECURE_SSL_REDIRECT`, HSTS        |
| Cookies      | `SECURE` / `HTTPONLY` / `SAMESITE` |
| SQL          | ORM parameterization               |
| Passwords    | Hashers (`PBKDF2`, Argon2)         |

`django.middleware.security.SecurityMiddleware` applies many header redirects.

## 💡 Examples [#-examples]

**Production settings checklist:**

```python
DEBUG = False
ALLOWED_HOSTS = ["www.example.com"]
SECURE_SSL_REDIRECT = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True
SECURE_HSTS_PRELOAD = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_CONTENT_TYPE_NOSNIFF = True
SECURE_REFERRER_POLICY = "same-origin"
X_FRAME_OPTIONS = "DENY"
CSRF_TRUSTED_ORIGINS = ["https://www.example.com"]
```

**CSRF in AJAX:**

```javascript
const csrftoken = document.querySelector("[name=csrfmiddlewaretoken]").value;
fetch("/api/item/", {
  method: "POST",
  headers: { "X-CSRFToken": csrftoken, "Content-Type": "application/json" },
  body: JSON.stringify({ title: "Hi" }),
});
```

**Safe vs unsafe:**

```html
{{ user_bio }}           {# escaped #}
{{ user_bio|safe }}      {# only if trusted #}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `DEBUG=True` in production leaks traces and settings.
* Disabling CSRF for “API convenience” on cookie-auth browsers.
* `|safe` / `mark_safe` on user HTML.
* Open redirects via unvalidated `next=` parameters.
* Serving user uploads from the same origin with executable MIME types.

## 🔗 Related [#-related]

* [Settings](/docs/django/settings)
* [Middleware](/docs/django/middleware)
* [Authentication](/docs/django/authentication)
* [Permissions](/docs/django/permissions)
* [Sessions](/docs/django/sessions)
* [File uploads](/docs/django/file-uploads)


# Serializers (/docs/django/serializers)



# Serializers [#serializers]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

DRF serializers convert between complex types (model instances, querysets) and JSON-native Python data. They validate incoming payloads like Django forms. Prefer `ModelSerializer` for CRUD; use plain `Serializer` for custom shapes and write-only flows (e.g. password change).

## 🔧 Core concepts [#-core-concepts]

| Piece                      | Role                                |
| -------------------------- | ----------------------------------- |
| `Serializer`               | Explicit fields                     |
| `ModelSerializer`          | Auto fields from a model            |
| `validated_data`           | After `is_valid()`                  |
| Nested serializers         | Embed related objects               |
| `read_only` / `write_only` | Directional fields                  |
| `SerializerMethodField`    | Computed output                     |
| Validators                 | UniqueTogether, custom `validate_*` |

Call `serializer.save()` only after successful validation (ModelSerializer).

## 💡 Examples [#-examples]

**ModelSerializer:**

```python
from rest_framework import serializers
from .models import Article


class ArticleSerializer(serializers.ModelSerializer):
    author_name = serializers.CharField(source="author.get_username", read_only=True)

    class Meta:
        model = Article
        fields = (
            "id",
            "title",
            "slug",
            "body",
            "author",
            "author_name",
            "is_published",
            "published_at",
        )
        read_only_fields = ("author", "published_at")

    def validate_title(self, value: str) -> str:
        value = value.strip()
        if len(value) < 3:
            raise serializers.ValidationError("Title too short.")
        return value
```

**Create / update in a view:**

```python
serializer = ArticleSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
article = serializer.save(author=request.user)
return Response(ArticleSerializer(article).data, status=201)
```

**Nested / method field:**

```python
class TagSerializer(serializers.ModelSerializer):
    class Meta:
        model = Tag
        fields = ("id", "name")


class ArticleDetailSerializer(serializers.ModelSerializer):
    tags = TagSerializer(many=True, read_only=True)
    summary = serializers.SerializerMethodField()

    class Meta:
        model = Article
        fields = ("id", "title", "slug", "tags", "summary")

    def get_summary(self, obj: Article) -> str:
        return obj.body[:120]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Returning `serializer.data` before `is_valid()` on input serializers is wrong for writes.
* Writable nested serializers need custom `create`/`update`.
* Exposing sensitive model fields via `fields = "__all__"`.
* Forgetting `many=True` for lists causes cryptic errors.

## 🔗 Related [#-related]

* [REST framework](/docs/django/rest-framework)
* [Models](/docs/django/models)
* [Forms](/docs/django/forms)
* [Views](/docs/django/views)
* [Authentication](/docs/django/authentication)
* [URLs](/docs/django/urls)


# Sessions (/docs/django/sessions)



# Sessions [#sessions]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Sessions persist per-visitor data across requests via a session key (usually a cookie). Server-side backends store the payload (DB, cache, file, signed cookies). Access with `request.session` like a dict. Enable `SessionMiddleware` and `django.contrib.sessions`.

## 🔧 Core concepts [#-core-concepts]

| Piece                 | Role                 |
| --------------------- | -------------------- |
| `request.session`     | Read/write mapping   |
| `session.save()`      | Force persist        |
| `flush` / `cycle_key` | Logout / rotate key  |
| `SESSION_ENGINE`      | Backend              |
| `SESSION_COOKIE_*`    | Cookie flags         |
| `set_expiry`          | Per-session lifetime |

Backends: database (default), cache, cached\_db, file, signed\_cookies.

## 💡 Examples [#-examples]

**Usage:**

```python
def cart_add(request, product_id):
    cart = request.session.get("cart", {})
    cart[str(product_id)] = cart.get(str(product_id), 0) + 1
    request.session["cart"] = cart
    request.session.modified = True  # if mutating nested structures
    return redirect("cart")
```

**Login hygiene:**

```python
from django.contrib.auth import login

def login_view(request):
    ...
    login(request, user)  # rotates session key by default
```

**Settings:**

```python
SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SECURE = True       # HTTPS only
SESSION_COOKIE_SAMESITE = "Lax"
SESSION_COOKIE_AGE = 60 * 60 * 24 * 14
```

**Clear:**

```python
request.session.flush()       # delete data + cookie
request.session.cycle_key()   # keep data, new key
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutating nested dicts/lists without `modified = True` or reassignment.
* Storing large objects or secrets in signed-cookie sessions.
* Missing `Secure` / `HttpOnly` / `SameSite` in production.
* Session fixation—always cycle on privilege change (login does this).
* Cache-only backend: eviction loses sessions.

## 🔗 Related [#-related]

* [Middleware](/docs/django/middleware)
* [Authentication](/docs/django/authentication)
* [Caching](/docs/django/caching)
* [Messages framework](/docs/django/messages-framework)
* [Security](/docs/django/security)
* [Settings](/docs/django/settings)


# Settings (/docs/django/settings)



# Settings [#settings]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`settings.py` (or split modules) configures Django: apps, middleware, database, templates, static/media, auth, and third-party packages. Keep secrets out of source control—use environment variables. Django 4.2+/5.x: prefer `pathlib`, `django-environ`/`python-dotenv`, and explicit `DEFAULT_AUTO_FIELD`.

## 🔧 Core concepts [#-core-concepts]

| Setting                   | Purpose                   |
| ------------------------- | ------------------------- |
| `INSTALLED_APPS`          | Enabled applications      |
| `MIDDLEWARE`              | Request/response pipeline |
| `DATABASES`               | DB connections            |
| `TEMPLATES`               | Template engines          |
| `AUTH_USER_MODEL`         | Custom user               |
| `STATIC_*` / `MEDIA_*`    | Assets & uploads          |
| `ALLOWED_HOSTS` / `DEBUG` | Deployment safety         |
| `CACHES` / `EMAIL_*`      | Infra integrations        |

Access via `from django.conf import settings`—never import settings module circularly from apps at import time if avoidable.

## 💡 Examples [#-examples]

**Core project settings:**

```python
from pathlib import Path
import os

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
DEBUG = os.environ.get("DJANGO_DEBUG", "0") == "1"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1").split(",")

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "blog",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.postgresql",
        "NAME": os.environ.get("POSTGRES_DB", "app"),
        "USER": os.environ.get("POSTGRES_USER", "app"),
        "PASSWORD": os.environ.get("POSTGRES_PASSWORD", ""),
        "HOST": os.environ.get("POSTGRES_HOST", "127.0.0.1"),
        "PORT": os.environ.get("POSTGRES_PORT", "5432"),
    }
}

STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
MEDIA_URL = "media/"
MEDIA_ROOT = BASE_DIR / "media"
```

**Production hardening flags:**

```python
if not DEBUG:
    SECURE_SSL_REDIRECT = True
    SESSION_COOKIE_SECURE = True
    CSRF_COOKIE_SECURE = True
    SECURE_HSTS_SECONDS = 31536000
```

## ⚠️ Pitfalls [#️-pitfalls]

* `DEBUG=True` in production leaks stack traces and secrets in error pages.
* Empty `ALLOWED_HOSTS` with `DEBUG=False` refuses all hosts.
* Committing `SECRET_KEY`—rotate if exposed.
* Changing `AUTH_USER_MODEL` late requires complex migrations.

## 🔗 Related [#-related]

* [URLs](/docs/django/urls)
* [Authentication](/docs/django/authentication)
* [django-allauth](/docs/django/django-allauth)
* [REST framework](/docs/django/rest-framework)
* [Admin](/docs/django/admin)
* [Models](/docs/django/models)


# Signals (/docs/django/signals)



# Signals [#signals]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Signals decouple senders from receivers: when something happens (save, delete, request finished), Django notifies connected handlers. Prefer explicit calls or service functions when coupling is local; use signals for cross-app side effects (cache bust, audit log, search index).

## 🔧 Core concepts [#-core-concepts]

| Signal                                 | When                          |
| -------------------------------------- | ----------------------------- |
| `pre_save` / `post_save`               | Before / after `Model.save()` |
| `pre_delete` / `post_delete`           | Before / after delete         |
| `m2m_changed`                          | M2M set/add/remove/clear      |
| `request_started` / `request_finished` | Request lifecycle             |
| `got_request_exception`                | Unhandled exception           |

Connect with `@receiver` or `signal.connect`. Receivers live in `AppConfig.ready()` so they register once.

## 💡 Examples [#-examples]

**App config registration:**

```python
# apps.py
from django.apps import AppConfig


class BlogConfig(AppConfig):
    default_auto_field = "django.db.models.BigAutoField"
    name = "blog"

    def ready(self):
        import blog.signals  # noqa: F401
```

**post\_save receiver:**

```python
# signals.py
from django.db.models.signals import post_save
from django.dispatch import receiver
from django.conf import settings

from .models import Profile


@receiver(post_save, sender=settings.AUTH_USER_MODEL)
def create_profile(sender, instance, created, **kwargs):
    if created:
        Profile.objects.create(user=instance)
```

**Disconnect / send custom:**

```python
from django.dispatch import Signal

order_paid = Signal()  # providing_args deprecated; use kwargs

def notify(sender, **kwargs):
    print(kwargs["order_id"])

order_paid.connect(notify)
order_paid.send(sender=None, order_id=42)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Importing signals only from models can miss registration—use `AppConfig.ready()`.
* `bulk_create` / `QuerySet.update` / `bulk_update` do **not** fire save signals.
* Infinite loops: receiver calling `save()` on the same instance without guards.
* Weak refs: keep a reference or use `weak=False` if the receiver is a local function.
* Overusing signals hides control flow—harder to test and reason about.

## 🔗 Related [#-related]

* [Models](/docs/django/models)
* [Managers](/docs/django/managers)
* [Transactions / ORM](/docs/django/transactions-orm)
* [Caching](/docs/django/caching)
* [Testing](/docs/django/testing)


# Static files (/docs/django/static-files)



# Static files [#static-files]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Static files are CSS, JS, and images not uploaded by users. In development, Django can serve them; in production, collect into `STATIC_ROOT` and serve via WhiteNoise, nginx, or a CDN. Use `\{% static %\}` and `django.contrib.staticfiles`.

## 🔧 Core concepts [#-core-concepts]

| Setting            | Role                                   |
| ------------------ | -------------------------------------- |
| `STATIC_URL`       | URL prefix (`/static/`)                |
| `STATIC_ROOT`      | Collect destination for prod           |
| `STATICFILES_DIRS` | Extra project-level dirs               |
| App `static/`      | Per-app assets                         |
| `collectstatic`    | Copy/hashed files to `STATIC_ROOT`     |
| Storages           | `ManifestStaticFilesStorage`, S3, etc. |

Finders locate files; Manifest storage adds cache-busting hashes.

## 💡 Examples [#-examples]

**Settings:**

```python
STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
STATICFILES_DIRS = [BASE_DIR / "assets"]
STORAGES = {
    "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    "staticfiles": {
        "BACKEND": "django.contrib.staticfiles.storage.ManifestStaticFilesStorage",
    },
}
```

**Template:**

```html
{% load static %}
<link rel="stylesheet" href="{% static 'blog/app.css' %}">
<script src="{% static 'blog/app.js' %}"></script>
```

**Collect:**

```shellscript
python manage.py collectstatic --noinput
python manage.py findstatic blog/app.css
```

**WhiteNoise (typical):**

```python
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    ...
]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing static files with media (`MEDIA_URL` / user uploads).
* Hardcoding `/static/...` instead of `\{% static %\}`.
* Forgetting `collectstatic` in deploy pipelines.
* Putting secrets or env-specific config inside static JS—use templated bootstrapping carefully.
* App static name collisions—namespace under `static/<app_label>/`.

## 🔗 Related [#-related]

* [Templates](/docs/django/templates)
* [Settings](/docs/django/settings)
* [File uploads](/docs/django/file-uploads)
* [Security](/docs/django/security)
* [Middleware](/docs/django/middleware)


# Templates (/docs/django/templates)



# Templates [#templates]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django templates render HTML (or text) with variables, tags, and filters. Prefer thin templates: pass prepared context from views; use `\{% include %\}`, `\{% extends %\}`, and custom tags for reuse. Auto-escaping is on by default.

## 🔧 Core concepts [#-core-concepts]

| Feature                             | Role                               |
| ----------------------------------- | ---------------------------------- |
| `\{\{ var \}\}`                     | Variable output (escaped)          |
| `\{\{ var\|filter \}\}`             | Transform value                    |
| `\{% tag %\}`                       | Logic: `if`, `for`, `block`, `url` |
| `\{% extends %\}` / `\{% block %\}` | Inheritance                        |
| `\{% include %\}`                   | Partial templates                  |
| `\{% csrf_token %\}`                | CSRF for POST forms                |
| `\{% static %\}`                    | Static asset URLs                  |
| `\{% url %\}`                       | Reverse named routes               |

Engines: DjangoTemplates (default) or Jinja2 via `TEMPLATES` setting.

## 💡 Examples [#-examples]

**Base + child:**

```html
{# base.html #}
<!DOCTYPE html>
<html>
<head><title>{% block title %}Site{% endblock %}</title></head>
<body>
  {% block content %}{% endblock %}
</body>
</html>
```

```html
{# article_detail.html #}
{% extends "base.html" %}
{% load static %}

{% block title %}{{ article.title }}{% endblock %}

{% block content %}
  <h1>{{ article.title|title }}</h1>
  <p>{{ article.body|linebreaks }}</p>
  <a href="{% url 'article-list' %}">Back</a>
  <img src="{% static 'blog/hero.png' %}" alt="">
{% endblock %}
```

**View:**

```python
from django.shortcuts import render, get_object_or_404
from .models import Article


def article_detail(request, slug):
    article = get_object_or_404(Article, slug=slug)
    return render(request, "blog/article_detail.html", {"article": article})
```

**Loop and conditions:**

```html
{% for item in items %}
  <li class="{% if forloop.first %}first{% endif %}">{{ item }}</li>
{% empty %}
  <li>No items</li>
{% endfor %}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Business logic in templates—move to views, model methods, or custom tags.
* `|safe` / `mark_safe` on untrusted input → XSS.
* Forgetting `\{% csrf_token %\}` on POST forms.
* Hardcoded URLs instead of `\{% url %\}`.
* Missing `\{% load static %\}` before `\{% static %\}`.

## 🔗 Related [#-related]

* [Views](/docs/django/views)
* [Context processors](/docs/django/context-processors)
* [Static files](/docs/django/static-files)
* [Forms](/docs/django/forms)
* [URLs](/docs/django/urls)
* [i18n](/docs/django/i18n)


# Testing (/docs/django/testing)



# Testing [#testing]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Django ships `TestCase`, `SimpleTestCase`, `TransactionTestCase`, and `LiveServerTestCase` on top of `unittest`. Prefer `TestCase` for DB tests (wraps each test in a transaction). Use the test client for request/response; factories or fixtures for data.

## 🔧 Core concepts [#-core-concepts]

| Class                 | Use                             |
| --------------------- | ------------------------------- |
| `SimpleTestCase`      | No DB                           |
| `TestCase`            | DB + rollback per test          |
| `TransactionTestCase` | Real commits (signals, threads) |
| `APITestCase`         | DRF (if installed)              |
| Client                | `self.client.get/post`          |
| `override_settings`   | Temporary settings              |
| `assertNumQueries`    | Catch N+1                       |

Run: `python manage.py test` or `pytest` + `pytest-django`.

## 💡 Examples [#-examples]

**View test:**

```python
from django.test import TestCase
from django.urls import reverse
from django.contrib.auth import get_user_model

from blog.models import Article


class ArticleTests(TestCase):
    def setUp(self):
        User = get_user_model()
        self.user = User.objects.create_user("ada", password="x")
        self.article = Article.objects.create(
            title="Hi", slug="hi", body="...", author=self.user, is_published=True
        )

    def test_detail_ok(self):
        url = reverse("article-detail", kwargs={"slug": "hi"})
        response = self.client.get(url)
        self.assertEqual(response.status_code, 200)
        self.assertContains(response, "Hi")

    def test_create_requires_login(self):
        url = reverse("article-create")
        response = self.client.post(url, {"title": "X", "slug": "x", "body": "y"})
        self.assertEqual(response.status_code, 302)
```

**Query count:**

```python
def test_list_queries(self):
    with self.assertNumQueries(2):  # adjust to reality
        self.client.get(reverse("article-list"))
```

**Settings override:**

```python
from django.test import override_settings

@override_settings(EMAIL_BACKEND="django.core.mail.backends.locmem.EmailBackend")
def test_sends_mail(self):
    ...
```

## ⚠️ Pitfalls [#️-pitfalls]

* Sharing mutable state across tests without isolation.
* Hitting real email/SMS/payment APIs—mock or use locmem backends.
* `TransactionTestCase` is slower; use only when needed.
* Hardcoding absolute URLs—use `reverse`.
* Flaky time-dependent tests—freeze time or use `freezegun`.

## 🔗 Related [#-related]

* [Views](/docs/django/views)
* [Models](/docs/django/models)
* [Permissions](/docs/django/permissions)
* [Email](/docs/django/email)
* [REST framework](/docs/django/rest-framework)


# Transactions / ORM (/docs/django/transactions-orm)



# Transactions / ORM [#transactions--orm]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Wrap multi-step writes in transactions so they commit or roll back together. Use `transaction.atomic()` (decorator or context manager). Understand autocommit (default), savepoints, `on_commit` hooks, and isolation when concurrent updates matter.

## 🔧 Core concepts [#-core-concepts]

| API                   | Role                             |
| --------------------- | -------------------------------- |
| `atomic()`            | Transaction / savepoint          |
| `on_commit(func)`     | Run after successful commit      |
| `set_rollback(True)`  | Mark atomic block to roll back   |
| Autocommit            | Each query commits unless atomic |
| `select_for_update()` | Row locks inside atomic          |
| `Robust`              | Nested atomics create savepoints |

DB-specific: PostgreSQL supports durable transactions and richer locking.

## 💡 Examples [#-examples]

**Atomic block:**

```python
from django.db import transaction


@transaction.atomic
def transfer(from_acct, to_acct, amount):
    from_acct.balance -= amount
    from_acct.save(update_fields=["balance"])
    to_acct.balance += amount
    to_acct.save(update_fields=["balance"])
```

**on\_commit (side effects):**

```python
def create_order(data):
    with transaction.atomic():
        order = Order.objects.create(**data)
        transaction.on_commit(lambda: send_order_email(order.pk))
        return order
```

**Locking:**

```python
with transaction.atomic():
    item = (
        Product.objects.select_for_update()
        .get(pk=pk)
    )
    if item.stock < 1:
        raise InsufficientStock()
    item.stock -= 1
    item.save(update_fields=["stock"])
```

**Catch integrity errors:**

```python
from django.db import IntegrityError

try:
    with transaction.atomic():
        Tag.objects.create(slug=slug)
except IntegrityError:
    ...
```

## ⚠️ Pitfalls [#️-pitfalls]

* Long atomic blocks holding locks—keep them short.
* Catching exceptions inside `atomic` without re-raising can leave the transaction broken until exit.
* Side effects (email, HTTP) inside atomic that run even if later rollback—use `on_commit`.
* `select_for_update` outside `atomic` is an error on some backends.
* Assuming read-after-write visibility across connections without commit.

## 🔗 Related [#-related]

* [Models](/docs/django/models)
* [QuerySet](/docs/django/queryset)
* [Signals](/docs/django/signals)
* [Managers](/docs/django/managers)
* [Testing](/docs/django/testing)


# URLs (/docs/django/urls)



# URLs [#urls]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

URL routing maps paths to views via `urlpatterns` in `urls.py`. Use `path()` / `re_path()`, name routes for `reverse()`, and `include()` to compose per-app configs. Django 4.2+/5.x: prefer `path()` converters over complex regex unless needed.

## 🔧 Core concepts [#-core-concepts]

| Piece                         | Role                                                     |
| ----------------------------- | -------------------------------------------------------- |
| `path(route, view, name=...)` | Primary routing                                          |
| Converters                    | `<int:pk>`, `<slug:slug>`, `<uuid:id>`, `<path:subpath>` |
| `include()`                   | Nest app URLconfs                                        |
| `name`                        | Reverse lookups / `\{% url %\}`                          |
| `app_name`                    | Namespacing                                              |
| `re_path`                     | Regex routes                                             |
| `static()`                    | Dev media/static serving                                 |

`ROOT_URLCONF` points at the project URLconf module.

## 💡 Examples [#-examples]

**Project + app URLs:**

```python
# config/urls.py
from django.contrib import admin
from django.urls import include, path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("blog/", include("blog.urls")),
    path("accounts/", include("allauth.urls")),
    path("api/", include("api.urls")),
]
```

```python
# blog/urls.py
from django.urls import path
from . import views

app_name = "blog"

urlpatterns = [
    path("", views.ArticleListView.as_view(), name="list"),
    path("new/", views.ArticleCreateView.as_view(), name="create"),
    path("<slug:slug>/", views.ArticleDetailView.as_view(), name="detail"),
]
```

**Reverse:**

```python
from django.urls import reverse

reverse("blog:detail", kwargs={"slug": "hello"})
# "/blog/hello/"
```

```html
<a href="{% url 'blog:detail' slug=article.slug %}">{{ article.title }}</a>
```

**Dev media:**

```python
from django.conf import settings
from django.conf.urls.static import static

urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Trailing-slash mismatches (`APPEND_SLASH`) cause confusing redirects on POST.
* Duplicate `name`s without namespaces break `reverse`.
* Putting business logic in URLconfs—keep views thin but logic out of urls.
* Forgetting `.as_view()` for CBVs.

## 🔗 Related [#-related]

* [Views](/docs/django/views)
* [Built-in class-based views](/docs/django/buildin-views)
* [Settings](/docs/django/settings)
* [Admin](/docs/django/admin)
* [REST framework](/docs/django/rest-framework)
* [django-allauth](/docs/django/django-allauth)


# Validators (/docs/django/validators)



# Validators [#validators]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Validators are callables that raise `ValidationError` when a value is invalid. Attach to model fields (`validators=[...]`), form fields, or call `full_clean()`. Built-ins cover email, URL, regex, min/max value/length, and file extensions.

## 🔧 Core concepts [#-core-concepts]

| Validator                                   | Checks            |
| ------------------------------------------- | ----------------- |
| `EmailValidator`                            | Email shape       |
| `URLValidator`                              | URL               |
| `RegexValidator`                            | Pattern           |
| `MinValueValidator` / `MaxValueValidator`   | Numeric bounds    |
| `MinLengthValidator` / `MaxLengthValidator` | Length            |
| `FileExtensionValidator`                    | Upload extensions |
| `validate_slug` / `validate_ipv4_address`   | Common formats    |
| `ProhibitNullCharactersValidator`           | No `\0`           |

Model `clean()` / `clean_<field>()` for cross-field rules. Forms run field + form cleaning automatically; `Model.save()` does **not** call validators unless you `full_clean()`.

## 💡 Examples [#-examples]

**Field validators:**

```python
from django.core.validators import MinValueValidator, RegexValidator
from django.db import models


slug_re = RegexValidator(r"^[a-z0-9-]+$", "Lowercase letters, numbers, hyphens.")


class Product(models.Model):
    sku = models.CharField(max_length=32, validators=[slug_re])
    price = models.DecimalField(
        max_digits=8,
        decimal_places=2,
        validators=[MinValueValidator(0)],
    )
```

**Custom validator:**

```python
from django.core.exceptions import ValidationError


def validate_even(value: int) -> None:
    if value % 2 != 0:
        raise ValidationError("%(value)s is not even", params={"value": value})
```

**Model.clean:**

```python
class Event(models.Model):
    starts_at = models.DateTimeField()
    ends_at = models.DateTimeField()

    def clean(self):
        super().clean()
        if self.ends_at <= self.starts_at:
            raise ValidationError({"ends_at": "Must be after start."})
```

## ⚠️ Pitfalls [#️-pitfalls]

* Relying on DB constraints alone—validators are Python-level.
* Skipping `full_clean()` on programmatic `save()`.
* Regex DoS with pathological patterns on user input.
* Duplicating the same rules on model and form inconsistently.
* `blank=True` vs validators—empty values may skip some validators.

## 🔗 Related [#-related]

* [Models](/docs/django/models)
* [Forms](/docs/django/forms)
* [File uploads](/docs/django/file-uploads)
* [Serializers](/docs/django/serializers)
* [Testing](/docs/django/testing)


# Views (/docs/django/views)



# Views [#views]

*Django · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Views receive an `HttpRequest` and return an `HttpResponse` (or raise). Use function-based views (FBVs) for simple flows and class-based views (CBVs) for reusable patterns. Keep views thin: validate input, call services/ORM, return response or redirect.

## 🔧 Core concepts [#-core-concepts]

| Style      | Notes                                                  |
| ---------- | ------------------------------------------------------ |
| FBV        | `def view(request, **kwargs)`                          |
| CBV        | `MyView.as_view()` in URLconf                          |
| Shortcuts  | `render`, `redirect`, `get_object_or_404`              |
| Decorators | `login_required`, `require_POST`, `csrf_exempt` (rare) |
| Mixins     | Auth/permission for CBVs                               |
| Errors     | `Http404`, `PermissionDenied`, custom handlers         |

Request attributes: `method`, `GET`, `POST`, `user`, `session`, `FILES`, `headers`.

## 💡 Examples [#-examples]

**Function-based view:**

```python
from django.contrib.auth.decorators import login_required
from django.shortcuts import get_object_or_404, redirect, render
from .forms import ArticleForm
from .models import Article


def article_detail(request, slug: str):
    article = get_object_or_404(Article, slug=slug, is_published=True)
    return render(request, "blog/article_detail.html", {"article": article})


@login_required
def article_edit(request, slug: str):
    article = get_object_or_404(Article, slug=slug, author=request.user)
    if request.method == "POST":
        form = ArticleForm(request.POST, instance=article)
        if form.is_valid():
            form.save()
            return redirect(article)
    else:
        form = ArticleForm(instance=article)
    return render(request, "blog/article_form.html", {"form": form})
```

**JSON response without DRF:**

```python
import json
from django.http import JsonResponse
from django.views.decorators.http import require_GET


@require_GET
def health(request):
    return JsonResponse({"status": "ok"})
```

**CBV sketch:**

```python
from django.views import View
from django.http import HttpResponse


class PingView(View):
    def get(self, request, *args, **kwargs):
        return HttpResponse("pong")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Returning unsanitized user HTML → XSS; use templates auto-escape.
* Long-running work in a request blocks workers—use tasks/queues.
* Catching all exceptions and returning 200 hides failures.
* Mutating data on GET violates HTTP semantics—use POST/PUT/PATCH/DELETE.

## 🔗 Related [#-related]

* [Built-in class-based views](/docs/django/buildin-views)
* [URLs](/docs/django/urls)
* [Forms](/docs/django/forms)
* [Authentication](/docs/django/authentication)
* [REST framework](/docs/django/rest-framework)
* [Models](/docs/django/models)


# amend (/docs/git/amend)



# amend [#amend]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git commit --amend` rewrites the latest commit (message and/or tree). Safe only for unpushed commits you own. After amend, the commit hash changes; pushed amends require a coordinated force-push.

## 🔧 Core concepts [#-core-concepts]

* **Message only** — `git commit --amend -m "…"` or editor.
* **Include staged** — stage fixes, then `--amend --no-edit`.
* **Author / date** — `--reset-author` updates author metadata.
* **Hooks** — amend re-runs `commit-msg` / related hooks unless skipped.
* **Recovery** — old commit remains in reflog briefly.

## 💡 Examples [#-examples]

```shellscript
# Fix message
git commit --amend -m "fix: handle null session"

# Add forgotten file to last commit
git add src/missed.ts
git commit --amend --no-edit

# Edit message in editor
git commit --amend

# Reset author to current user
git commit --amend --reset-author --no-edit

# After amend of unpushed commit
git push

# If already pushed (team OK with force-with-lease)
git push --force-with-lease
```

## ⚠️ Pitfalls [#️-pitfalls]

* Amending published commits rewrites shared history — prefer a new commit.
* `--no-verify` skips hooks — avoid unless explicitly required.
* Empty amend (no changes, same message) may be rejected without `--allow-empty`.
* Merge commits / amend during rebase have extra rules — use rebase todo instead.
* Never amend someone else’s commit on a shared branch.

## 🔗 Related [#-related]

* [commit.md](/docs/git/commit)
* [reset.md](/docs/git/reset)
* [reflog.md](/docs/git/reflog)
* [squash.md](/docs/git/squash)
* [push.md](/docs/git/push)
* [hooks.md](/docs/git/hooks)


# bisect (/docs/git/bisect)



# bisect [#bisect]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git bisect` binary-searches history to find the commit that introduced a bug. Mark commits `good` / `bad` (or `old` / `new`); automate with `bisect run` and a script that exits 0 (good) or non-zero (bad).

## 🔧 Core concepts [#-core-concepts]

* **Start** — `bisect start`, then mark known bad and good endpoints.
* **Midpoints** — Git checks out a mid commit; you test and mark.
* **Terms** — `good`/`bad` or `old`/`new` (regression vs behavior change).
* **Skip** — untestable commits (`bisect skip`).
* **Run** — `git bisect run ./test.sh` automates the loop.

## 💡 Examples [#-examples]

```shellscript
git bisect start
git bisect bad HEAD
git bisect good v1.2.0

# manually test, then:
git bisect good   # or: git bisect bad

git bisect reset  # return to original branch

# Automated
git bisect start HEAD v1.2.0
git bisect run npm test
# script exit: 0 = good, 1-127 (not 125) = bad, 125 = skip

git bisect skip
git bisect log
git bisect replay bisect-log.txt
```

## ⚠️ Pitfalls [#️-pitfalls]

* Need a reliable test — flaky tests send bisect the wrong way.
* Shallow clones may lack enough history — deepen first.
* Skipped ranges can leave an ambiguous first-bad commit.
* Detached HEAD during bisect — don’t start new feature work mid-bisect.
* Build failures unrelated to the bug should `skip` or fix the script’s exit codes.

## 🔗 Related [#-related]

* [log.md](/docs/git/log)
* [blame.md](/docs/git/blame)
* [checkout via branch.md](/docs/git/branch)
* [reflog.md](/docs/git/reflog)
* [tag.md](/docs/git/tag)
* [diff.md](/docs/git/diff)


# blame (/docs/git/blame)



# blame [#blame]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git blame` annotates each line with the commit that last changed it (author, date, SHA). Use it to find when a bug was introduced, then dig with `show` / `bisect`. Ignore whitespace and move detection options reduce noise.

## 🔧 Core concepts [#-core-concepts]

* **Line attribution** — SHA, author, timestamp, line content.
* **Range** — `-L start,end` limits lines.
* **Moves/copies** — `-M` / `-C` detect moved/copied lines.
* **Ignore rev** — `--ignore-rev` / `--ignore-revs-file` skip bulk format commits.
* **GUI** — `git gui blame`, IDE blame views wrap the same data.

## 💡 Examples [#-examples]

```shellscript
git blame path/to/file.ts
git blame -L 40,80 path/to/file.ts
git blame -w path/to/file.ts          # ignore whitespace
git blame -M -C path/to/file.ts       # moves / copies

git show abcdef1
git log -L 40,80:path/to/file.ts

# Ignore noisy formatting commits
echo abcdef1 >> .git-blame-ignore-revs
git config blame.ignoreRevsFile .git-blame-ignore-revs
git blame path/to/file.ts

# Porcelain for scripts
git blame --line-porcelain path/to/file.ts | head
```

## ⚠️ Pitfalls [#️-pitfalls]

* Blame shows last *touch*, not necessarily the logical author of a design.
* Mass reformat commits pollute blame — use ignore-revs.
* Renames without follow can look like wholesale rewrites — try `-C` / history follow.
* Generated files are useless to blame — exclude them.
* Shallow clones may lack the original commit objects.

## 🔗 Related [#-related]

* [log.md](/docs/git/log)
* [bisect.md](/docs/git/bisect)
* [diff.md](/docs/git/diff)
* [gitattributes.md](/docs/git/gitattributes)
* [commit.md](/docs/git/commit)
* [show via log.md](/docs/git/log)


# Branch (/docs/git/branch)



# Branch [#branch]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Branches are movable pointers to commits. Create feature branches for isolated work, switch with `switch`/`checkout`, and delete when merged. Track remote branches with upstreams for `pull`/`push` defaults.

## 🧩 Core concepts [#-core-concepts]

* **Local branch** — ref under `refs/heads/`.
* **Remote-tracking branch** — e.g. `origin/main` under `refs/remotes/`.
* **Upstream** — `-u` / `--set-upstream-to` links local ↔ remote for defaults.
* **Detached HEAD** — checked out commit is not a branch tip; create a branch before committing.
* **Naming** — `feature/…`, `fix/…`, `chore/…` conventions help navigation.
* **Protection** — host rules may block force-push/delete on `main`.

## 💡 Examples [#-examples]

```shellscript
# List
git branch
git branch -vv
git branch -a

# Create and switch
git switch -c feature/checkout
# equivalent: git checkout -b feature/checkout

# Switch existing
git switch main

# Create from remote tip
git switch -c feature/api origin/feature/api

# Rename
git branch -m feature/checkout feature/cart

# Delete local (merged)
git branch -d feature/cart
git branch -D feature/cart   # force

# Set upstream
git push -u origin feature/cart
git branch --set-upstream-to=origin/main main
```

## ⚠️ Pitfalls [#️-pitfalls]

* Deleting a branch does not delete unmerged work until GC — recover via `reflog` soon.
* Working on detached HEAD loses easy branch pointers — `git switch -c` immediately.
* Stale remote-tracking branches linger until `git fetch --prune`.
* Long-lived branches drift — rebase or merge from main regularly.

## 🔗 Related [#-related]

* [Commit](/docs/git/commit)
* [Merge](/docs/git/merge)
* [Rebase](/docs/git/rebase)
* [Push](/docs/git/push)
* [Pull](/docs/git/pull)


# cherry-pick (/docs/git/cherry-pick)



# cherry-pick [#cherry-pick]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git cherry-pick` applies the patch of one or more existing commits onto the current branch as new commits. Use to backport fixes; avoid heavy cherry-picking as a substitute for proper merges/rebases.

## 🔧 Core concepts [#-core-concepts]

* **New SHAs** — picked commits get new hashes (same diff, new parents).
* **Ranges** — `A^..B` or `--no-walk` for explicit lists.
* **Mainline** — `-m 1` when picking merge commits.
* **Continue** — conflict → fix → `--continue` / `--abort` / `--skip`.
* **Sign-off** — `-x` records “cherry picked from” in the message.

## 💡 Examples [#-examples]

```shellscript
git checkout release/1.2
git cherry-pick abcdef1
git cherry-pick -x abcdef1   # note source SHA in message

# Multiple
git cherry-pick abcdef1 1234567
git cherry-pick A^..B

# No auto-commit
git cherry-pick --no-commit abcdef1

# During conflicts
git status
# fix files
git add -u
git cherry-pick --continue
# or
git cherry-pick --abort
```

## ⚠️ Pitfalls [#️-pitfalls]

* Duplicate commits later when merging the original branch (duplicate changes / conflicts).
* Empty cherry-pick if changes already present — `--skip` or abort.
* Merge commits need `-m`; picking merges is often the wrong tool.
* Don’t cherry-pick unpublished WIP that will be rewritten (amended/rebased).
* Binary conflicts and renames can make picks painful — prefer merge for large sets.

## 🔗 Related [#-related]

* [rebase.md](/docs/git/rebase)
* [merge.md](/docs/git/merge)
* [conflict.md](/docs/git/conflict)
* [revert.md](/docs/git/revert)
* [log.md](/docs/git/log)
* [commit.md](/docs/git/commit)


# clean (/docs/git/clean)



# clean [#clean]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git clean` deletes untracked files and directories from the working tree. Dry-run first (`-n`). It does not remove ignored files unless `-x` / `-X` is used. Irreversible for files not stored in Git.

## 🔧 Core concepts [#-core-concepts]

* **Untracked** — files not in the index (and not ignored, by default).
* **`-n` / `--dry-run`** — show what would be removed.
* **`-f`** — required unless `clean.requireForce` is false.
* **`-d`** — also remove untracked directories.
* **`-x` / `-X`** — include ignored / only ignored (build artifacts).

## 💡 Examples [#-examples]

```shellscript
git clean -n -d          # preview
git clean -f -d          # delete untracked files + dirs

# Also remove ignored (e.g. dist/, .env.local if ignored)
git clean -n -xd
git clean -f -xd

# Only ignored
git clean -f -X -d

# Interactive
git clean -i -d

# Path limited
git clean -f -d -- apps/web/tmp
```

## ⚠️ Pitfalls [#️-pitfalls]

* No recycle bin — untracked work is gone unless backed up elsewhere.
* `-x` can delete local secrets and IDE files that were gitignored on purpose.
* Don’t clean during a conflicted merge without understanding untracked conflict helpers.
* Nested other repos / submodules need care — clean won’t remove submodule gitlinks.
* Prefer targeted pathspecs over repo-wide `-xd` in large monorepos.

## 🔗 Related [#-related]

* [status.md](/docs/git/status)
* [gitignore.md](/docs/git/gitignore)
* [stash.md](/docs/git/stash)
* [reset.md](/docs/git/reset)
* [stage.md](/docs/git/stage)
* [worktree.md](/docs/git/worktree)


# clone (/docs/git/clone)



# clone [#clone]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git clone` copies a remote repository (history, branches, remotes) into a new local directory and checks out the default branch. Use shallow / sparse / filter options for large repos.

## 🔧 Core concepts [#-core-concepts]

* **URL forms** — HTTPS, SSH (`git@host:org/repo.git`), local path.
* **Default remote** — `origin`; default branch from remote HEAD.
* **Depth** — `--depth N` shallow history; `--single-branch` limits refs.
* **Recurse** — `--recurse-submodules` initializes submodules.
* **Bare / mirror** — `--bare`, `--mirror` for server-style copies.

## 💡 Examples [#-examples]

```shellscript
git clone https://github.com/org/repo.git
git clone git@github.com:org/repo.git my-app
cd my-app

# Shallow (CI)
git clone --depth 1 --branch main https://github.com/org/repo.git

# Specific branch only
git clone --single-branch --branch develop git@github.com:org/repo.git

# With submodules
git clone --recurse-submodules git@github.com:org/repo.git

# Existing empty dir
git clone https://github.com/org/repo.git .

# Sparse (partial clone + sparse-checkout)
git clone --filter=blob:none --sparse git@github.com:org/huge.git
cd huge
git sparse-checkout set apps/web
```

## ⚠️ Pitfalls [#️-pitfalls]

* Cloning into a non-empty directory fails unless the dir is empty / `.`.
* Shallow clones limit `blame` / some bisect / merge-base operations.
* Wrong protocol (HTTPS vs SSH) causes auth friction — set remotes intentionally.
* Large LFS repos need Git LFS installed before checkout of pointers.
* `--recurse-submodules` can fail if submodule URLs need credentials.

## 🔗 Related [#-related]

* [init.md](/docs/git/init)
* [remote.md](/docs/git/remote)
* [submodule.md](/docs/git/submodule)
* [sparse\_checkout.md](/docs/git/sparse-checkout)
* [fetch.md](/docs/git/fetch)
* [git\_lfs.md](/docs/git/git-lfs)


# Commit (/docs/git/commit)



# Commit [#commit]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

A commit records a snapshot of the staged index with metadata (author, message, parent). Prefer small, purposeful commits with clear messages; amend only when safe (unpushed, intentional).

## 🧩 Core concepts [#-core-concepts]

* **Snapshot model** — commit points at a tree; parents form history.
* **Message** — subject (+ optional body); conventional prefixes (`feat:`, `fix:`) are team conventions.
* **Amend** — `git commit --amend` rewrites the latest commit (changes hash).
* **Sign-off / GPG** — `-s` / `-S` for DCO or signed commits when required.
* **Empty commits** — `--allow-empty` for CI triggers or markers (rare).
* **Hooks** — `pre-commit` / `commit-msg` can block or rewrite messages.

## 💡 Examples [#-examples]

```shellscript
# Commit staged changes
git commit -m "feat: add login form validation"

# Stage tracked files and commit
git commit -am "fix: handle null user in session"

# Amend message only
git commit --amend -m "feat: add login form validation"

# Amend and include newly staged files (unpushed only)
git add src/login.ts
git commit --amend --no-edit

# Show last commit
git log -1 --stat
git show HEAD

# Skip hooks only if you must (usually avoid)
# git commit --no-verify -m "wip"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Amending a commit already pushed requires force-push — coordinate with the team.
* `-a` ignores untracked files — new files still need `git add`.
* Huge commits are hard to review and revert — split by concern.
* Never put secrets in commit messages or blobs; rewriting history later is painful.

## 🔗 Related [#-related]

* [Stage](/docs/git/stage)
* [Branch](/docs/git/branch)
* [Push](/docs/git/push)
* [Rebase](/docs/git/rebase)
* [Merge](/docs/git/merge)


# conflict (/docs/git/conflict)



# conflict [#conflict]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Conflicts occur when merge, rebase, cherry-pick, or revert can’t auto-apply changes. Git marks files with conflict markers; you resolve, `git add`, then continue the operation. Abort to return to the pre-operation state.

## 🔧 Core concepts [#-core-concepts]

* **Markers** — `&lt;&lt;&lt;&lt;&lt;&lt;&lt;`, `=======`, `>>>>>>>` (ours / theirs depend on command).
* **Ours/theirs** — merge: ours = current branch; rebase: ours = upstream (inverted mental model).
* **Tools** — `git mergetool`, IDE 3-way merge, `diff --cc`.
* **Continue** — `merge --continue` / `rebase --continue` / `cherry-pick --continue`.
* **Abort** — `--abort` restores pre-op state (if possible).

## 💡 Examples [#-examples]

```shellscript
git status   # unmerged paths
# edit files — remove markers, keep correct code
git add path/to/file.ts
git merge --continue   # or rebase / cherry-pick

# Take one side for a file
git checkout --ours -- path/to/file.ts
git checkout --theirs -- path/to/file.ts
git add path/to/file.ts

git merge --abort
git rebase --abort

git diff   # unmerged diff
git mergetool
```

```plaintext
<<<<<<< HEAD
current change
=======
incoming change
>>>>>>> feature
```

## ⚠️ Pitfalls [#️-pitfalls]

* Leaving conflict markers in committed files breaks builds — search for `&lt;&lt;&lt;&lt;&lt;&lt;&lt;`.
* Ours/theirs flip meaning during rebase vs merge — verify with `status` / content.
* Binary conflicts can’t use markers — choose one version explicitly.
* Resolving then forgetting `git add` blocks `--continue`.
* Don’t abort if you’ve already fixed a lot without backup — commit WIP or stash carefully.

## 🔗 Related [#-related]

* [merge.md](/docs/git/merge)
* [rebase.md](/docs/git/rebase)
* [cherry\_pick.md](/docs/git/cherry-pick)
* [revert.md](/docs/git/revert)
* [status.md](/docs/git/status)
* [diff.md](/docs/git/diff)


# diff (/docs/git/diff)



# diff [#diff]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git diff` shows changes between worktree, index, commits, and branches. Use it before staging/committing and in code review. Word-diff and path filters help focus on signal.

## 🔧 Core concepts [#-core-concepts]

* **Unstaged** — `git diff` (worktree vs index).
* **Staged** — `git diff --staged` / `--cached` (index vs HEAD).
* **Commits** — `git diff A B`, `git diff A..B`, `A...B` (merge-base).
* **Stats** — `--stat`, `--numstat`, `--name-only`.
* **Options** — `-w` ignore whitespace; `--word-diff`; `-M` renames.

## 💡 Examples [#-examples]

```shellscript
git diff
git diff --staged
git diff HEAD
git diff main...feature --stat

git diff abcdef1 1234567 -- apps/web
git diff --name-only origin/main

# Word / whitespace
git diff --word-diff
git diff -w

# Function context (C/JS often)
git diff -W

# Binary detection
git diff --binary

# Exit code for scripts (0 = no diff)
git diff --quiet || echo "dirty"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `A..B` vs `A...B` differ for branch comparison — `...` uses merge-base (PR-style).
* Line endings / CRLF can create noisy diffs — normalize with `.gitattributes`.
* Generated files and lockfile churn drown real changes — pathspec filter.
* `diff` of binary shows “Binary files differ” — use Git LFS or external tools.
* Submodule diffs show SHA changes only unless you diff inside the submodule.

## 🔗 Related [#-related]

* [status.md](/docs/git/status)
* [stage.md](/docs/git/stage)
* [log.md](/docs/git/log)
* [blame.md](/docs/git/blame)
* [gitattributes.md](/docs/git/gitattributes)
* [commit.md](/docs/git/commit)


# Fetch (/docs/git/fetch)



# Fetch [#fetch]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`git fetch` downloads objects and updates remote-tracking refs from a remote without changing your working tree or current branch. Use it to inspect upstream changes before merging or rebasing.

## 🧩 Core concepts [#-core-concepts]

* **Remote** — named location (`origin`) with URL(s).
* **Remote-tracking branches** — updated to match the remote (e.g. `origin/main`).
* **Prune** — remove stale remote-tracking refs deleted upstream.
* **Tags** — default fetch may omit tags; `--tags` pulls them.
* **Refspecs** — control which refs are fetched into which local names.
* **Fetch ≠ pull** — pull is fetch + integrate (merge/rebase).

## 💡 Examples [#-examples]

```shellscript
# Fetch default remote
git fetch
git fetch origin

# Fetch all remotes
git fetch --all

# Prune deleted remote branches
git fetch --prune
git fetch origin --prune

# Fetch one branch
git fetch origin main

# Include tags
git fetch --tags

# Inspect after fetch
git log --oneline HEAD..origin/main
git diff main origin/main

# Dry-run prune
git fetch --prune --dry-run
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fetch never updates your checked-out branch — you must merge/rebase/reset intentionally.
* Without prune, deleted remote branches still appear in `git branch -r`.
* Shallow clones (`--depth`) need deepen/unshallow for full history operations.
* Multiple remotes: `git fetch` alone only hits the current branch’s remote (or `origin` by config).

## 🔗 Related [#-related]

* [Pull](/docs/git/pull)
* [Push](/docs/git/push)
* [Merge](/docs/git/merge)
* [Rebase](/docs/git/rebase)
* [Branch](/docs/git/branch)


# GH CLI (/docs/git/gh-cli)



# GH CLI [#gh-cli]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

GitHub CLI (`gh`) manages repositories, pull requests, issues, releases, and Actions from the terminal. Authenticate once, then script common GitHub workflows without leaving the repo.

## 🧩 Core concepts [#-core-concepts]

* **Auth** — `gh auth login` stores credentials (HTTPS or SSH).
* **Repo context** — commands infer the GitHub remote from `origin` (override with `-R owner/repo`).
* **PRs** — create, checkout, review, merge from the CLI.
* **Issues** — list/create/close with labels and assignees.
* **API** — `gh api` for arbitrary REST/GraphQL when no subcommand exists.
* **Actions** — `gh run list/watch` for workflow runs.

## 💡 Examples [#-examples]

```shellscript
# Auth & status
gh auth login
gh auth status

# Repo
gh repo view
gh repo clone owner/name
gh repo create my-app --private --source=. --remote=origin --push

# Pull requests
gh pr status
gh pr list
gh pr create --title "feat: checkout" --body "$(cat <<'EOF'
## Summary
- Add checkout flow

## Test plan
- [ ] Pay with test card
EOF
)"
gh pr checkout 42
gh pr diff 42
gh pr review 42 --approve
gh pr merge 42 --squash --delete-branch

# Issues
gh issue list --label bug
gh issue create --title "Null ref on login" --body "Steps…"
gh issue close 7

# Actions
gh run list --limit 10
gh run watch
gh run view 123456 --log-failed

# API escape hatch
gh api user
gh api repos/{owner}/{repo}/pulls --jq '.[].title'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Wrong remote/`gh` repo context operates on a different project — confirm with `gh repo view`.
* `gh pr create` needs a pushed branch with an upstream.
* Org SSO may require `gh auth refresh -h github.com -s read:org` (or similar) after login.
* Scripting merges still respects branch protection — expect interactive or admin failures.

## 🔗 Related [#-related]

* [Push](/docs/git/push)
* [Pull](/docs/git/pull)
* [Branch](/docs/git/branch)
* [Commit](/docs/git/commit)
* [Fetch](/docs/git/fetch)


# Git LFS (/docs/git/git-lfs)



# Git LFS [#git-lfs]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Git Large File Storage (LFS) replaces large binaries in Git history with lightweight pointer files while storing blobs on an LFS server. Track patterns early — migrating after the fact requires history rewrite.

## 🧩 Core concepts [#-core-concepts]

* **Pointers** — small text files in Git; real content fetched via LFS smudge/clean filters.
* **`git lfs track`** — writes patterns into `.gitattributes`.
* **Install** — `git lfs install` sets up local hooks/filters once per user machine.
* **Fetch/pull** — LFS objects download on checkout; `git lfs pull` fetches explicitly.
* **Locks** — optional file locking for non-mergeable binaries.
* **Storage quotas** — hosts (GitHub, etc.) meter LFS bandwidth/storage.

## 💡 Examples [#-examples]

```shellscript
# Install CLI (platform-specific) then enable filters
git lfs install

# Track file types (updates .gitattributes)
git lfs track "*.psd"
git lfs track "*.mp4"
git lfs track "design/**/*.sketch"
git add .gitattributes
git commit -m "chore: track design assets with Git LFS"

# Status / list
git lfs status
git lfs ls-files

# Fetch LFS objects
git lfs fetch --all
git lfs pull

# Migrate existing history (destructive — coordinate)
git lfs migrate import --include="*.psd" --everything

# Locking (if enabled on remote)
git lfs lock path/to/file.psd
git lfs unlock path/to/file.psd
```

Pointer file shape (what Git stores):

```plaintext
version https://git-lfs.github.com/spec/v1
oid sha256:…
size 12345678
```

## ⚠️ Pitfalls [#️-pitfalls]

* Tracking after files were committed still leaves blobs in history until migrate/rewrite.
* Clones without LFS installed see pointer files instead of real assets.
* CI must install Git LFS or checkouts will be incomplete.
* Exceeding host LFS quotas breaks pushes — monitor usage and prune unused objects.

## 🔗 Related [#-related]

* [Gitattributes](/docs/git/gitattributes)
* [Gitignore](/docs/git/gitignore)
* [Push](/docs/git/push)
* [Commit](/docs/git/commit)
* [GH CLI](/docs/git/gh-cli)


# Gitattributes (/docs/git/gitattributes)



# Gitattributes [#gitattributes]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`.gitattributes` assigns attributes to paths: line-ending normalization, diff/merge drivers, linguist overrides, and Git LFS filters. Keep it committed so every clone behaves the same.

## 🧩 Core concepts [#-core-concepts]

* **`text` / `eol`** — normalize LF in the repo; checkout `lf` or `crlf` per path.
* **`binary`** — skip text conversion/diff for binaries.
* **`diff` / `merge`** — custom drivers for generated or vendor files.
* **`export-ignore`** — omit paths from `git archive`.
* **Linguist** — `linguist-language`, `linguist-vendored`, `linguist-generated` for GitHub stats.
* **LFS filter** — `filter=lfs diff=lfs merge=lfs -text` for large files.

## 💡 Examples [#-examples]

```ini
# Normalize text; force LF in working tree for these
* text=auto eol=lf
*.sh text eol=lf
*.bat text eol=crlf
*.ps1 text eol=lf

# Binaries
*.png binary
*.jpg binary
*.pdf binary
*.zip binary

# Generated / vendored (GitHub Linguist)
dist/** linguist-generated=true
vendor/** linguist-vendored=true

# Custom diff for lockfiles (optional)
package-lock.json -diff
pnpm-lock.yaml -diff

# LFS (after git lfs track)
*.psd filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

# Archives
docs/internal/** export-ignore
```

```shellscript
# Refresh working tree after attributes change
git add --renormalize .
git status
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing `eol` mid-project causes huge diffs unless you renormalize carefully.
* Marking text as `binary` hides useful diffs and can complicate merges.
* LFS patterns belong here *and* need `git lfs install` on each machine.
* Attributes are path-based — rename/move files can drop intended rules if patterns are too narrow.

## 🔗 Related [#-related]

* [Gitignore](/docs/git/gitignore)
* [Git LFS](/docs/git/git-lfs)
* [Commit](/docs/git/commit)
* [Merge](/docs/git/merge)
* [Stage](/docs/git/stage)


# Gitignore (/docs/git/gitignore)



# Gitignore [#gitignore]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`.gitignore` lists patterns Git should treat as untracked noise (build output, deps, secrets, OS junk). Patterns apply to untracked files; already-tracked files stay tracked until removed from the index.

## 🧩 Core concepts [#-core-concepts]

* **Pattern syntax** — globs (`*.log`), directories (`dist/`), negation (`!important.log`).
* **Scoped rules** — root `.gitignore`, nested ignores, and global `core.excludesFile`.
* **`/` anchoring** — leading `/` anchors to the file’s directory; trailing `/` means directory.
* **`**` recursion** — matches across directories depending on position.
* **Check-ignore** — debug why a path is ignored.
* **Un-ignore tracked files** — `git rm -r --cached` then commit.

## 💡 Examples [#-examples]

```ini
# Dependencies & build
node_modules/
dist/
build/
*.tsbuildinfo

# Env & secrets
.env
.env.*
!.env.example

# Logs & caches
*.log
.cache/
.coverage/

# OS / IDE
.DS_Store
Thumbs.db
.idea/
.vscode/*
!.vscode/extensions.json
```

```shellscript
# Test a path
git check-ignore -v path/to/file

# Stop tracking without deleting the file
git rm -r --cached node_modules
git rm --cached .env
git commit -m "chore: stop tracking local env and deps"

# Global ignores
git config --global core.excludesFile ~/.gitignore_global
```

## ⚠️ Pitfalls [#️-pitfalls]

* Ignoring after `git add` does nothing until you untrack with `--cached`.
* Negation (`!`) cannot re-include a file inside an ignored parent directory easily — un-ignore parents carefully.
* Committing `.env` once leaves secrets in history — rotate keys and consider history rewrite/BFG.
* Over-broad `*` patterns can hide files you meant to commit.

## 🔗 Related [#-related]

* [Gitattributes](/docs/git/gitattributes)
* [Stage](/docs/git/stage)
* [Commit](/docs/git/commit)
* [Git LFS](/docs/git/git-lfs)
* [GH CLI](/docs/git/gh-cli)


# Glossary (/docs/git/glossary)



# Glossary [#glossary]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core Git terms for commits, branches, remotes, history rewriting, and collaboration workflows.

## 🔧 Core concepts [#-core-concepts]

| Term          | Definition                                                                   |
| ------------- | ---------------------------------------------------------------------------- |
| Amend         | Rewriting the latest commit by adding staged changes or editing its message. |
| Branch        | A movable pointer to a commit, usually representing a line of development.   |
| Cherry-pick   | Copying a commit’s changes onto another branch as a new commit.              |
| Clone         | Creating a local copy of a remote repository including history.              |
| Commit        | A snapshot of the staged project state with metadata and a parent link.      |
| Conflict      | Overlapping changes Git cannot auto-merge and must be resolved by hand.      |
| Detached HEAD | A state where HEAD points at a commit, not a branch name.                    |
| Diff          | A patch showing line-level changes between two trees or commits.             |
| Fast-forward  | A merge that simply moves a branch pointer forward with no merge commit.     |
| Fetch         | Downloading remote commits and refs without updating local branches.         |
| HEAD          | The symbolic ref pointing at the current branch or checked-out commit.       |
| Hook          | A script Git runs on events like `pre-commit` or `pre-push`.                 |
| Index         | The staging area holding the next commit’s proposed snapshot.                |
| Merge         | Combining histories from two branches into one.                              |
| Origin        | The conventional default name for a cloned remote.                           |
| Pull          | Fetching from a remote and integrating into the current branch.              |
| Push          | Uploading local commits to a remote branch.                                  |
| Rebase        | Replaying commits onto another base to linearize history.                    |
| Reflog        | A local log of where HEAD and branch tips have pointed.                      |
| Remote        | A named URL pointing at another repository copy.                             |
| Reset         | Moving a branch pointer (and optionally index/worktree) to another commit.   |
| Revert        | Creating a new commit that undoes a previous commit’s changes.               |
| Stash         | Temporarily shelving uncommitted worktree changes.                           |
| Tag           | A named marker for a specific commit, often used for releases.               |
| Worktree      | An additional working directory attached to the same repository.             |

## 💡 Examples [#-examples]

**Stage and commit:**

```shellscript
git status
git add README.md
git commit -m "docs: clarify install steps"
```

**Branch, merge, and push:**

```shellscript
git switch -c feature/login
# ... edits ...
git switch main
git merge feature/login
git push origin main
```

**Stash and rebase:**

```shellscript
git stash push -m "wip"
git pull --rebase origin main
git stash pop
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **reset** (moves branch/history locally) with **revert** (adds an undo commit).
* Mixing **fetch** (download only) with **pull** (download + integrate).
* Treating **merge** and **rebase** as identical — history shape and conflict timing differ.
* Equating **amend** on a pushed commit with a safe local edit — rewriting published history needs force-push care.
* Assuming **stash** is a backup — it is local and easy to drop accidentally.

## 🔗 Related [#-related]

* [commit](/docs/git/commit)
* [branch](/docs/git/branch)
* [merge](/docs/git/merge)
* [rebase](/docs/git/rebase)
* [stash](/docs/git/stash)
* [remote](/docs/git/remote)


# hooks (/docs/git/hooks)



# hooks [#hooks]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Git hooks are scripts that run on events (commit, push, merge). Client hooks live in `.git/hooks/`; teams often share them via Husky, pre-commit framework, or `core.hooksPath`. Use hooks to lint, test, and block bad commits — keep them fast.

## 🔧 Core concepts [#-core-concepts]

| Hook                           | When                            |
| ------------------------------ | ------------------------------- |
| `pre-commit`                   | Before commit object is created |
| `commit-msg`                   | Validate/edit message           |
| `pre-push`                     | Before refs are pushed          |
| `post-checkout` / `post-merge` | After switch/merge              |
| `pre-receive` (server)         | Before updating remote refs     |

* **Sample hooks** — `.git/hooks/*.sample` (disabled until renamed).
* **Skip** — `--no-verify` bypasses client hooks (use sparingly).
* **Shared path** — `git config core.hooksPath .githooks`.

## 💡 Examples [#-examples]

```shellscript
# Enable a sample
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Shared hooks in repo
mkdir -p .githooks
git config core.hooksPath .githooks

# .githooks/pre-commit
#!/usr/bin/env bash
set -euo pipefail
npm run lint
npm run typecheck

# Skip once (emergency)
git commit --no-verify -m "wip"
```

```shellscript
# pre-commit framework (Python) / Husky (Node) install hooks for the team
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hooks in `.git/hooks` aren’t versioned — without `hooksPath`/tooling, teammates miss them.
* Slow `pre-commit` trains people to `--no-verify`.
* Hooks must be executable on Unix; Windows needs compatible runners.
* Server-side hooks are the real enforcement for protected repos.
* Don’t put secrets in hook scripts committed to the repo.

## 🔗 Related [#-related]

* [commit.md](/docs/git/commit)
* [amend.md](/docs/git/amend)
* [push.md](/docs/git/push)
* [init.md](/docs/git/init)
* [status.md](/docs/git/status)
* [gitignore.md](/docs/git/gitignore)


# Git (/docs/git)



# Git [#git]

Everyday Git, recovery, GitHub CLI.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# init (/docs/git/init)



# init [#init]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git init` creates a new repository (a `.git` directory) in the current or given folder. Optionally set the initial branch name and template; then add a remote and make the first commit.

## 🔧 Core concepts [#-core-concepts]

* **Repo root** — `.git/` holds objects, refs, config.
* **Initial branch** — `-b main` (or `init.defaultBranch`).
* **Bare** — `git init --bare` for remotes without a working tree.
* **Template** — `--template=<dir>` copies hooks/info.
* **Reinit** — safe to re-run; won’t overwrite existing history.

## 💡 Examples [#-examples]

```shellscript
mkdir my-app && cd my-app
git init -b main

# Or
git init
git branch -M main

echo "# my-app" > README.md
git add README.md
git commit -m "chore: initial commit"

git remote add origin git@github.com:org/my-app.git
git push -u origin main

# Bare remote-style repo
git init --bare /srv/git/my-app.git

# Shared permissions (server)
git init --shared=group
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don’t `git init` inside an existing repo unless you intend a nested repo (usually wrong).
* Forgetting `.gitignore` before the first add can commit secrets/build artifacts.
* Default branch may still be `master` on older Git — set `-b main` explicitly.
* Bare repos have no working tree — don’t develop directly in them.
* Nested `git init` in monorepo packages breaks tooling — use one root repo.

## 🔗 Related [#-related]

* [clone.md](/docs/git/clone)
* [commit.md](/docs/git/commit)
* [remote.md](/docs/git/remote)
* [gitignore.md](/docs/git/gitignore)
* [hooks.md](/docs/git/hooks)
* [stage.md](/docs/git/stage)


# log (/docs/git/log)



# log [#log]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git log` walks commit history with filters, formatting, and graphs. Use it to audit changes, find authors, and prepare release notes. Pair with `git show` for a single commit’s patch.

## 🔧 Core concepts [#-core-concepts]

* **Range** — `A..B`, `A...B` (symmetric), path-limited history.
* **Decorate** — branch/tag names on commits (`--decorate`).
* **Format** — `--oneline`, `--graph`, pretty formats (`%h %an %s`).
* **Filters** — `--author`, `--grep`, `--since` / `--until`, `-S` / `-G` pickaxe.
* **Follow** — `--follow` for single-file renames (limited).

## 💡 Examples [#-examples]

```shellscript
git log --oneline --graph --decorate -20
git log main..HEAD --oneline
git log --since="2026-01-01" --author="Ada" --oneline

# Patch for each commit
git log -p -- path/to/file.ts

# Find commits that added/removed a string
git log -S "featureFlag" --oneline
git log -G "featureFlag\s*=" --oneline

# Custom format
git log --pretty=format:"%h %ad %an %s" --date=short

# First parent only (linearize merges)
git log --first-parent main

# Tags / merges
git log --merges --oneline
git log v1.0.0..v1.1.0 --oneline
```

## ⚠️ Pitfalls [#️-pitfalls]

* `A..B` means reachable from B not from A — order matters.
* `--follow` only works with a single path.
* Shallow clones truncate history — deepen with `git fetch --unshallow`.
* Default pager may hide output — `GIT_PAGER=cat` or `--no-pager`.
* Rewritten history (rebase/amend) changes hashes — don’t rely on old SHAs.

## 🔗 Related [#-related]

* [reflog.md](/docs/git/reflog)
* [blame.md](/docs/git/blame)
* [diff.md](/docs/git/diff)
* [tag.md](/docs/git/tag)
* [bisect.md](/docs/git/bisect)
* [show via commit.md](/docs/git/commit)


# Merge (/docs/git/merge)



# Merge [#merge]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`git merge` joins histories by integrating another branch into the current one. Fast-forward moves the pointer when possible; otherwise Git creates a merge commit. Resolve conflicts, then complete the merge commit.

## 🧩 Core concepts [#-core-concepts]

* **Fast-forward** — no merge commit if current tip is ancestor of incoming.
* **True merge** — creates a commit with two parents when histories diverged.
* **`--no-ff`** — always create a merge commit (preserves feature-branch topology).
* **`--squash`** — stage combined changes without a merge commit (then commit yourself).
* **Conflict markers** — edit files, `git add`, then `git commit` / `git merge --continue`.
* **Abort** — `git merge --abort` returns to pre-merge state.

## 💡 Examples [#-examples]

```shellscript
git switch main
git fetch origin
git merge origin/main

# Feature into main
git switch main
git merge --no-ff feature/checkout

# Squash merge locally
git merge --squash feature/checkout
git commit -m "feat: checkout flow"

# During conflicts
git status
# edit files, remove <<<<<<< ======= >>>>>>> markers
git add path/to/file
git commit   # completes merge

# Abort
git merge --abort

# Prefer ff-only on release branches
git merge --ff-only origin/main
```

## ⚠️ Pitfalls [#️-pitfalls]

* Merging the wrong direction (main into feature vs feature into main) confuses PR history.
* Leaving conflict markers in committed files breaks builds — search for `&lt;&lt;&lt;&lt;&lt;&lt;&lt;`.
* Squash merges on the remote make local feature branches diverge — delete/recreate after.
* Recursive/ort strategies handle most text; binary conflicts need manual choice.

## 🔗 Related [#-related]

* [Rebase](/docs/git/rebase)
* [Pull](/docs/git/pull)
* [Branch](/docs/git/branch)
* [Commit](/docs/git/commit)
* [Fetch](/docs/git/fetch)


# Pull (/docs/git/pull)



# Pull [#pull]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`git pull` fetches from a remote and integrates into the current branch. Default integration is merge; configure or pass `--rebase` for a linear history. Prefer an explicit fetch + review when the update is risky.

## 🧩 Core concepts [#-core-concepts]

* **Fetch + integrate** — updates remote-tracking refs, then merge or rebase.
* **Upstream** — pull uses the branch’s configured remote/merge ref.
* **`--rebase`** — replay local commits on top of the updated tip.
* **`--ff-only`** — refuse non-fast-forward updates (safe default for shared mains).
* **Autostash** — `--autostash` stashes dirty worktree around rebase/merge.
* **Conflict handling** — same as merge/rebase; finish with commit or `rebase --continue`.

## 💡 Examples [#-examples]

```shellscript
# Pull current upstream (merge)
git pull

# Pull with rebase
git pull --rebase
git pull --rebase origin main

# Fast-forward only
git pull --ff-only

# Explicit remote/branch
git pull origin main

# Autostash local changes
git pull --rebase --autostash

# Safer workflow: fetch, inspect, then integrate
git fetch origin
git log --oneline HEAD..origin/main
git merge --ff-only origin/main
# or: git rebase origin/main
```

Set rebase-by-default for pulls (optional):

```shellscript
git config pull.rebase true
git config pull.ff only
```

## ⚠️ Pitfalls [#️-pitfalls]

* Blind `git pull` on a dirty tree can create messy conflict states — stash or commit first.
* Mixing merge pulls and rebase pulls on the same branch confuses history.
* Pulling with divergent histories creates merge commits unless you rebase/ff-only.
* After a rebased pull of commits already pushed, you may need a force-with-lease push.

## 🔗 Related [#-related]

* [Fetch](/docs/git/fetch)
* [Merge](/docs/git/merge)
* [Rebase](/docs/git/rebase)
* [Push](/docs/git/push)
* [Branch](/docs/git/branch)


# Push (/docs/git/push)



# Push [#push]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`git push` uploads local commits (and optionally tags) to a remote. Set an upstream once with `-u`, prefer `--force-with-lease` over `--force`, and push tags deliberately.

## 🧩 Core concepts [#-core-concepts]

* **Upstream** — `-u` records remote/branch for future `push`/`pull`.
* **Fast-forward** — remote tip must be ancestor unless forced.
* **Force-with-lease** — refuses overwrite if remote moved unexpectedly.
* **Refspecs** — `git push origin local:remote` maps branches explicitly.
* **Tags** — `git push --tags` or push a single tag by name.
* **Delete remote branch** — `git push origin --delete branch`.

## 💡 Examples [#-examples]

```shellscript
# First push of a feature branch
git push -u origin feature/checkout

# Subsequent pushes
git push

# Push to explicit remote/branch
git push origin main

# Safe force after rebase (preferred)
git push --force-with-lease origin feature/checkout

# Push one tag / all tags
git push origin v1.2.0
git push --tags

# Delete remote branch
git push origin --delete feature/checkout

# Dry run
git push --dry-run
```

## ⚠️ Pitfalls [#️-pitfalls]

* `--force` can destroy others’ commits — use `--force-with-lease` and branch protections.
* Pushing to the wrong remote/branch is common with multiple remotes — check `git remote -v`.
* Large binary blobs bloat history — use Git LFS before the first push.
* CI/CD may reject unsigned commits or unprotected force pushes on `main`.

## 🔗 Related [#-related]

* [Pull](/docs/git/pull)
* [Fetch](/docs/git/fetch)
* [Branch](/docs/git/branch)
* [Rebase](/docs/git/rebase)
* [Git LFS](/docs/git/git-lfs)


# Rebase (/docs/git/rebase)



# Rebase [#rebase]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`git rebase` replays commits onto a new base, rewriting history for a linear sequence. Use it to update a feature branch onto `main`, clean up before sharing, and avoid unnecessary merge commits. Do not rebase commits already shared unless the team agrees.

## 🧩 Core concepts [#-core-concepts]

* **Replay** — take commits after the merge-base and apply onto the upstream tip.
* **Interactive (`-i`)** — reorder, squash, reword, drop, edit commits.
* **Continue / abort / skip** — resolve conflicts then `rebase --continue`.
* **Onto** — `git rebase --onto` for advanced history surgery.
* **Autosquash** — works with `fixup!` / `squash!` commit messages.
* **Update refs** — rewritten commits get new SHAs; remotes need force-with-lease.

## 💡 Examples [#-examples]

```shellscript
# Update feature branch onto latest main
git switch feature/checkout
git fetch origin
git rebase origin/main

# Interactive cleanup
git rebase -i origin/main
# pick / reword / squash / fixup / drop

# Continue after conflicts
git add .
git rebase --continue

git rebase --abort
git rebase --skip

# Rebase onto a different cut point
git rebase --onto main old-base feature/checkout

# Pull with rebase
git pull --rebase origin main
```

## ⚠️ Pitfalls [#️-pitfalls]

* Rebasing published history rewrites SHAs — collaborators must reset/rebase carefully.
* Never rebase `main`/`master` that others base work on without coordination.
* Long conflict chains: abort and merge instead if the cost is too high.
* Avoid interactive rebase in environments that cannot provide a real editor session.

## 🔗 Related [#-related]

* [Merge](/docs/git/merge)
* [Pull](/docs/git/pull)
* [Push](/docs/git/push)
* [Commit](/docs/git/commit)
* [Branch](/docs/git/branch)


# reflog (/docs/git/reflog)



# reflog [#reflog]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The reflog records when HEAD and branch tips moved locally (commit, checkout, reset, rebase). Use it to recover “lost” commits after reset/amend/rebase. Reflogs are local and expire (default \~90 days).

## 🔧 Core concepts [#-core-concepts]

* **Entries** — `HEAD@\{n\}`, `main@\{yesterday\}`, timestamps.
* **Scope** — per-ref reflogs (`git reflog show main`) + `HEAD` reflog.
* **Recover** — find SHA → `checkout` / `branch` / `reset` to it.
* **Expire** — `gc` / `reflog expire` prune old entries.
* **Not pushed** — remotes don’t have your reflog.

## 💡 Examples [#-examples]

```shellscript
git reflog
git reflog show main
git reflog --date=iso

# Recover after hard reset
git reset --hard HEAD@{1}
# or
git branch recover-me abcdef1

# After failed rebase
git reflog | head
git reset --hard HEAD@{5}

# Relative time
git show main@{2.days.ago}

git reflog expire --expire=30.days --all
git gc --prune=now
```

## ⚠️ Pitfalls [#️-pitfalls]

* Expired / GC’d objects can’t be recovered — act sooner than later.
* Reflog doesn’t help on another machine — push recovery branches if needed.
* `@\{u\}` is upstream, not reflog — different syntax.
* Don’t confuse reflog index `HEAD@\{1\}` with commit parent `HEAD~1`.
* Sensitive SHAs in reflog remain until expiry — consider security on shared disks.

## 🔗 Related [#-related]

* [reset.md](/docs/git/reset)
* [amend.md](/docs/git/amend)
* [rebase.md](/docs/git/rebase)
* [log.md](/docs/git/log)
* [stash.md](/docs/git/stash)
* [branch.md](/docs/git/branch)


# remote (/docs/git/remote)



# remote [#remote]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Remotes are named URLs for other repositories (`origin`, `upstream`). Manage fetch/push URLs, prune stale refs, and track branches. Most day-to-day sync uses `fetch` / `pull` / `push` against remotes.

## 🔧 Core concepts [#-core-concepts]

* **Add / rename / remove** — `remote add`, `rename`, `remove`.
* **URL** — `remote set-url`, separate pushurl if needed.
* **Verbose** — `remote -v` lists fetch/push URLs.
* **Prune** — delete local remote-tracking branches removed upstream.
* **Upstream** — fork workflow: `origin` = your fork, `upstream` = canonical.

## 💡 Examples [#-examples]

```shellscript
git remote -v
git remote add origin git@github.com:you/app.git
git remote add upstream git@github.com:org/app.git

git remote rename origin old-origin
git remote remove old-origin

git remote set-url origin git@github.com:you/app.git
git remote set-url --push origin https://github.com/you/app.git

git fetch upstream
git remote prune origin
git fetch --prune

# Show details
git remote show origin

# Tracking
git branch -vv
git push -u origin HEAD
```

## ⚠️ Pitfalls [#️-pitfalls]

* Multiple remotes with similar names cause pushes to the wrong place — check `-v`.
* Changing URL doesn’t rewrite existing remote-tracking history.
* Credential helpers differ for HTTPS vs SSH — fix auth at the remote URL layer.
* `prune` deletes remote-tracking refs, not local branches — still delete locals yourself.
* Mirror / bare remotes have different push semantics.

## 🔗 Related [#-related]

* [clone.md](/docs/git/clone)
* [fetch.md](/docs/git/fetch)
* [push.md](/docs/git/push)
* [pull.md](/docs/git/pull)
* [branch.md](/docs/git/branch)
* [gh\_cli.md](/docs/git/gh-cli)


# reset (/docs/git/reset)



# reset [#reset]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git reset` moves HEAD (and optionally the index / worktree) to a target commit. Soft / mixed / hard modes control how much is discarded. Prefer `restore` for unstaging/discarding file content without moving HEAD.

## 🔧 Core concepts [#-core-concepts]

| Mode                | HEAD  | Index        | Worktree     |
| ------------------- | ----- | ------------ | ------------ |
| `--soft`            | moves | kept         | kept         |
| `--mixed` (default) | moves | matches HEAD | kept         |
| `--hard`            | moves | matches HEAD | matches HEAD |

* **Path reset** — `git reset HEAD -- file` unstages (mixed on paths).
* **vs revert** — reset rewrites history; revert adds a new undo commit.
* **vs restore** — `git restore --staged` / `--worktree` for file-level ops.

## 💡 Examples [#-examples]

```shellscript
# Unstage all / one file
git reset HEAD
git reset HEAD -- src/app.ts

# Undo last commit, keep changes staged
git reset --soft HEAD~1

# Undo last commit, keep changes unstaged
git reset HEAD~1

# Destroy local commits + changes (dangerous)
git reset --hard HEAD~1
git reset --hard origin/main

# Move branch tip to a SHA
git reset --hard abcdef1
```

## ⚠️ Pitfalls [#️-pitfalls]

* `--hard` deletes uncommitted work — confirm with `status` / stash first.
* Never reset published commits others use — use `revert` instead.
* After reset of pushed commits, force-push is required (coordinate with team).
* Detached HEAD + reset can orphan commits — recover via `reflog`.
* Pathspec reset doesn’t move branch tip — only affects index entries.

## 🔗 Related [#-related]

* [revert.md](/docs/git/revert)
* [reflog.md](/docs/git/reflog)
* [amend.md](/docs/git/amend)
* [stage.md](/docs/git/stage)
* [status.md](/docs/git/status)
* [commit.md](/docs/git/commit)


# revert (/docs/git/revert)



# revert [#revert]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git revert` creates new commits that undo the changes of prior commits. Safe for shared branches because history is not rewritten. Use for undoing merges and published mistakes.

## 🔧 Core concepts [#-core-concepts]

* **Inverse patch** — applies the opposite of the selected commit(s).
* **Non-destructive** — original commits remain in history.
* **Ranges** — can revert multiple commits (order matters).
* **Merges** — `-m 1` specifies mainline parent for merge commits.
* **No-commit** — `--no-commit` applies inverses and leaves staging for one commit.

## 💡 Examples [#-examples]

```shellscript
# Undo a single commit on main
git revert abcdef1
git revert HEAD

# Revert without auto-commit
git revert --no-commit abcdef1
git commit -m "revert: undo broken feature flag"

# Sequence (oldest..newest often clearer with -n then one commit)
git revert --no-commit bad1^..bad3
git commit -m "revert: roll back bad1..bad3"

# Revert a merge commit (keep first parent line)
git revert -m 1 mergecommitsha

# Abort conflicted revert
git revert --abort
```

## ⚠️ Pitfalls [#️-pitfalls]

* Reverting a merge without `-m` fails — pick the parent to keep.
* Re-reverting later can be confusing if the original feature is re-applied.
* Conflicts still happen when later commits touch the same lines.
* Don’t confuse with `reset` — revert is for published history.
* Empty revert (changes already undone) may need `--skip` or abort.

## 🔗 Related [#-related]

* [reset.md](/docs/git/reset)
* [conflict.md](/docs/git/conflict)
* [log.md](/docs/git/log)
* [commit.md](/docs/git/commit)
* [merge.md](/docs/git/merge)
* [cherry\_pick.md](/docs/git/cherry-pick)


# sparse-checkout (/docs/git/sparse-checkout)



# sparse-checkout [#sparse-checkout]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Sparse-checkout checks out only a subset of paths from a wide repository (monorepos). Combine with partial clone (`--filter=blob:none`) to reduce network and disk use. Cone mode is the recommended pattern.

## 🔧 Core concepts [#-core-concepts]

* **Cone mode** — directory-based patterns (default/recommended).
* **Patterns** — include dirs like `apps/web` and always root files needed.
* **Init** — `sparse-checkout init --cone` then `set` / `add`.
* **Partial clone** — fetch blobs on demand with filters.
* **Disable** — `sparse-checkout disable` restores full tree.

## 💡 Examples [#-examples]

```shellscript
git clone --filter=blob:none --sparse git@github.com:org/monorepo.git
cd monorepo
git sparse-checkout set apps/web packages/ui

# Add more paths later
git sparse-checkout add packages/utils

# List / reapply
git sparse-checkout list
git sparse-checkout reapply

# Non-cone (legacy patterns) — avoid unless needed
git sparse-checkout init --no-cone
git sparse-checkout set "/*" "!/*/" "/apps/web/"

git sparse-checkout disable
```

## ⚠️ Pitfalls [#️-pitfalls]

* Tools expecting a full tree (some codegen, IDE indexes) may break — document required paths.
* Non-cone pattern syntax is easy to get wrong — prefer cone directories.
* Sparse + submodules needs explicit submodule paths checked out.
* CI must configure the same sparse set or use full checkout.
* Narrow checkouts can hide files from `git status` that still exist in history.

## 🔗 Related [#-related]

* [clone.md](/docs/git/clone)
* [status.md](/docs/git/status)
* [submodule.md](/docs/git/submodule)
* [worktree.md](/docs/git/worktree)
* [gitignore.md](/docs/git/gitignore)
* [fetch.md](/docs/git/fetch)


# squash (/docs/git/squash)



# squash [#squash]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Squashing combines multiple commits into one (or fewer) for a cleaner history before merge. Common via interactive rebase, `merge --squash`, or soft reset. Prefer squashing on feature branches, not on shared long-lived branches.

## 🔧 Core concepts [#-core-concepts]

* **Interactive rebase** — `pick` + `squash`/`fixup` in `git rebase -i`.
* **Merge squash** — `git merge --squash feature` stages combined diff; you commit once.
* **Soft reset** — `git reset --soft main` then one new commit.
* **fixup** — like squash but discards the squashed commit’s message by default.
* **Autosquash** — `commit --fixup` + `rebase -i --autosquash`.

## 💡 Examples [#-examples]

```shellscript
# Interactive: last 5 commits
git rebase -i HEAD~5
# change pick → squash/fixup on commits to fold

# Soft reset onto main
git checkout feature
git reset --soft main
git commit -m "feat: add billing portal"

# Squash merge (keeps feature branch commits locally)
git checkout main
git merge --squash feature
git commit -m "feat: add billing portal"

# Fixup workflow
git commit --fixup abcdef1
git rebase -i --autosquash abcdef1^
```

## ⚠️ Pitfalls [#️-pitfalls]

* Squashing rewritten commits that were pushed needs force-with-lease.
* Losing detailed commit messages — keep a good final message / notes.
* Squash-merge on GitHub makes the PR branch diverge — delete/rebuild branches.
* Don’t squash commits that are merge bases for other work still in flight.
* Conflicts during rebase squash still need resolution per step.

## 🔗 Related [#-related]

* [rebase.md](/docs/git/rebase)
* [merge.md](/docs/git/merge)
* [amend.md](/docs/git/amend)
* [reset.md](/docs/git/reset)
* [commit.md](/docs/git/commit)
* [log.md](/docs/git/log)


# Stage (/docs/git/stage)



# Stage [#stage]

**Git · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Staging selects which changes enter the next commit via the index (staging area). Use pathspecs and patch mode to craft focused commits instead of dumping the whole working tree.

## 🧩 Core concepts [#-core-concepts]

* **Index / staging area** — snapshot between working tree and `HEAD`.
* **`git add`** — stage new/modified files; `git add -u` stages tracked updates/deletes.
* **`git restore --staged`** — unstage while keeping working-tree edits.
* **Patch staging** — `git add -p` stages hunks interactively.
* **Intent to add** — `git add -N` tracks a new file as empty for diffing.
* **Status** — `git status` / `git diff --cached` inspect staged vs unstaged.

## 💡 Examples [#-examples]

```shellscript
# Stage specific paths
git add README.md src/app.ts
git add src/

# Stage all tracked modifications + deletes (not untracked)
git add -u

# Stage everything under the repo (respects .gitignore)
git add -A

# Interactive hunks
git add -p src/app.ts

# Unstage
git restore --staged src/app.ts
git restore --staged .

# Review
git status
git diff            # unstaged
git diff --cached   # staged vs HEAD
```

## ⚠️ Pitfalls [#️-pitfalls]

* `git add .` from a subdirectory only stages under that path — use repo-root awareness.
* Staging secrets (`.env`) is easy to miss — keep `.gitignore` current.
* `git add -A` can stage deletions you did not intend — review `git status` first.
* Partial staging can leave a file both staged and unstaged with different hunks.

## 🔗 Related [#-related]

* [Commit](/docs/git/commit)
* [Gitignore](/docs/git/gitignore)
* [Branch](/docs/git/branch)
* [Merge](/docs/git/merge)
* [Rebase](/docs/git/rebase)


# stash (/docs/git/stash)



# stash [#stash]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git stash` shelves uncommitted changes so you can switch branches cleanly, then restore them later. Prefer named stashes and explicit `pop`/`apply`; include untracked files when needed.

## 🔧 Core concepts [#-core-concepts]

* **Default** — stashes tracked modified + staged; working tree matches HEAD.
* **Untracked** — `-u` / `--include-untracked`; `-a` also ignored.
* **List / show** — `stash list`, `stash show -p`.
* **Restore** — `apply` keeps stash; `pop` applies and drops.
* **Branch** — `stash branch <name>` creates a branch from the stash base.

## 💡 Examples [#-examples]

```shellscript
git stash push -m "wip: login form"
git stash list
git stash show -p stash@{0}

git stash pop
git stash apply stash@{1}
git stash drop stash@{1}
git stash clear   # delete all — irreversible

# Include untracked
git stash push -u -m "wip: new files"

# Stash only some paths
git stash push -m "partial" -- src/a.ts src/b.ts

# Keep index (stash unstaged only)
git stash push --keep-index -m "keep staged"

git stash branch recover-wip stash@{0}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `pop` can conflict; the stash entry may remain if apply fails (version-dependent).
* Stashing doesn’t include ignored files unless `-a`.
* Binary / submodule changes can make stash awkward — verify with `show -p`.
* Don’t rely on stash as backup — commit to a WIP branch instead for long work.
* `clear` / `drop` are hard to undo (reflog may help briefly).

## 🔗 Related [#-related]

* [status.md](/docs/git/status)
* [branch.md](/docs/git/branch)
* [conflict.md](/docs/git/conflict)
* [reflog.md](/docs/git/reflog)
* [clean.md](/docs/git/clean)
* [commit.md](/docs/git/commit)


# status (/docs/git/status)



# status [#status]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git status` shows the working tree vs index vs HEAD: staged, unstaged, and untracked files. Use short and porcelain formats in scripts; branch tracking info shows ahead/behind remotes.

## 🔧 Core concepts [#-core-concepts]

* **Sections** — staged (index), unstaged (worktree), untracked.
* **Branch** — current branch, upstream, ahead/behind counts.
* **Short** — `-s` / `--short`; `--branch` adds branch header.
* **Porcelain** — `-z` / `--porcelain=v1|v2` stable for scripts.
* **Ignore** — `--ignored` lists ignored files; respect `.gitignore`.

## 💡 Examples [#-examples]

```shellscript
git status
git status -sb              # short + branch
git status --porcelain=v1   # scripting

# Only untracked
git status -u

# Show ignored
git status --ignored

# Path limited
git status -- apps/web

# Useful aliases
# st = status -sb
git config alias.st "status -sb"
```

```plaintext
## main...origin/main [ahead 1]
M  staged-file.ts
 M unstaged-file.ts
?? new-file.ts
```

## ⚠️ Pitfalls [#️-pitfalls]

* “Clean” status doesn’t mean pushed — check ahead/behind or `git log @\{u\}..`.
* Renames show as delete+add unless similarity detection kicks in (`status` / `diff -M`).
* Submodule dirty state appears as modified content — inspect inside the submodule.
* Assume-unchanged / skip-worktree files can hide local edits.
* CRLF warnings may appear without listing as modified — check `core.autocrlf`.

## 🔗 Related [#-related]

* [stage.md](/docs/git/stage)
* [diff.md](/docs/git/diff)
* [commit.md](/docs/git/commit)
* [branch.md](/docs/git/branch)
* [clean.md](/docs/git/clean)
* [gitignore.md](/docs/git/gitignore)


# submodule (/docs/git/submodule)



# submodule [#submodule]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Submodules embed another Git repo at a fixed commit inside a parent repo. The parent stores the submodule URL and pinned SHA. Prefer packages/monorepos when possible; use submodules for true multi-repo version pins.

## 🔧 Core concepts [#-core-concepts]

* **Record** — `.gitmodules` + gitlink (mode 160000) at a commit SHA.
* **Init/update** — after clone: `submodule update --init --recursive`.
* **Move forward** — cd into submodule, pull/commit, then commit new SHA in parent.
* **Remote clone** — `git clone --recurse-submodules`.
* **Deinit / remove** — deinit, remove config + gitlink + `.gitmodules` entry.

## 💡 Examples [#-examples]

```shellscript
git submodule add git@github.com:org/lib.git libs/lib
git commit -m "chore: add lib submodule"

git clone --recurse-submodules git@github.com:org/app.git
# or later:
git submodule update --init --recursive

# Update submodule to latest remote tracking branch
git submodule update --remote libs/lib
git add libs/lib
git commit -m "chore: bump lib submodule"

# Status
git submodule status
git submodule foreach 'git status -sb'

# Remove (high level)
git submodule deinit -f libs/lib
git rm -f libs/lib
rm -rf .git/modules/libs/lib
git commit -m "chore: remove lib submodule"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fresh clones without `--recurse-submodules` leave empty directories.
* Parent CI must init submodules or builds miss code.
* Detached HEAD inside submodule is normal — create a branch before committing there.
* Nested submodules need `--recursive`.
* Mixing submodule edits with parent WIP confuses reviews — bump SHA in a dedicated commit.

## 🔗 Related [#-related]

* [clone.md](/docs/git/clone)
* [remote.md](/docs/git/remote)
* [status.md](/docs/git/status)
* [commit.md](/docs/git/commit)
* [worktree.md](/docs/git/worktree)
* [sparse\_checkout.md](/docs/git/sparse-checkout)


# tag (/docs/git/tag)



# tag [#tag]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Tags mark specific commits (releases, milestones). Lightweight tags are refs; annotated tags store message, author, and date (preferred for releases). Push tags explicitly to remotes.

## 🔧 Core concepts [#-core-concepts]

* **Lightweight** — `git tag v1.0.0` → pointer only.
* **Annotated** — `git tag -a v1.0.0 -m "…"` → full object (signing with `-s`).
* **List / show** — `git tag -l`, `git show v1.0.0`.
* **Move** — delete + recreate, or `-f` (force) carefully.
* **Remote** — tags don’t push by default; `git push origin v1.0.0` or `--tags`.

## 💡 Examples [#-examples]

```shellscript
git tag v1.2.0
git tag -a v1.2.0 -m "Release 1.2.0"
git tag -a v1.2.0 abcdef1 -m "Release 1.2.0"

git tag -l "v1.2.*"
git show v1.2.0

# Push one / all
git push origin v1.2.0
git push origin --tags

# Delete local + remote
git tag -d v1.2.0
git push origin :refs/tags/v1.2.0
# or: git push origin --delete v1.2.0

# Checkout (detached)
git switch --detach v1.2.0
```

## ⚠️ Pitfalls [#️-pitfalls]

* Moving a published tag confuses CI/CD and consumers — treat as immutable.
* `git push --tags` can push unintended local tags — push named tags instead.
* Lightweight tags lack metadata — use annotated for releases.
* Tagging the wrong commit — verify with `git log -1` before tagging.
* Signed tags need GPG/SSH signing configured.

## 🔗 Related [#-related]

* [log.md](/docs/git/log)
* [commit.md](/docs/git/commit)
* [push.md](/docs/git/push)
* [remote.md](/docs/git/remote)
* [branch.md](/docs/git/branch)
* [checkout via branch.md](/docs/git/branch)


# worktree (/docs/git/worktree)



# worktree [#worktree]

*Git · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`git worktree` adds extra working directories linked to the same repository. Use them for parallel branches (hotfix while feature WIP continues) without stashing or cloning again.

## 🔧 Core concepts [#-core-concepts]

* **Main + linked** — one `.git` data store; each worktree has its own checkout.
* **Add** — `git worktree add <path> <branch>` (creates branch with `-b`).
* **List / remove** — `worktree list`, `worktree remove`, `prune`.
* **Lock** — prevent accidental prune of portable drives.
* **Constraint** — a branch can be checked out in only one worktree at a time.

## 💡 Examples [#-examples]

```shellscript
git worktree list

# New branch in sibling folder
git worktree add -b hotfix/login ../app-hotfix main
cd ../app-hotfix
# … fix, commit, push …
cd ../app
git worktree remove ../app-hotfix

# Existing branch
git worktree add ../app-review review/pr-42

# Detached
git worktree add --detach ../app-bisect abcdef1

git worktree prune
git worktree lock ../app-hotfix --reason "on USB"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Can’t check out the same branch in two worktrees — use a new branch or detach.
* Deleting folders manually leaves stale records — run `worktree prune` / `remove`.
* IDE may open the wrong root — open the specific worktree path.
* Shared `node_modules` isn’t automatic — install per worktree or use shared caches carefully.
* Submodules need init/update inside each worktree.

## 🔗 Related [#-related]

* [branch.md](/docs/git/branch)
* [stash.md](/docs/git/stash)
* [clone.md](/docs/git/clone)
* [status.md](/docs/git/status)
* [bisect.md](/docs/git/bisect)
* [submodule.md](/docs/git/submodule)


# Artifacts (/docs/github-actions/artifacts)



# Artifacts [#artifacts]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Artifacts persist files between jobs or after a workflow finishes (logs, builds, test reports). Upload with `actions/upload-artifact`, download with `actions/download-artifact`. Retention is limited; use releases or external storage for long-term binaries.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                         |
| ------------------- | ---------------------------- |
| `upload-artifact`   | Store paths from a job       |
| `download-artifact` | Restore into another job/run |
| `retention-days`    | Override default retention   |
| `name`              | Artifact identifier          |
| `path`              | File/glob to store           |
| `if-no-files-found` | `warn` / `error` / `ignore`  |

Artifacts are per-workflow-run. Jobs that need build outputs from another job must download explicitly—workspace is not shared.

## 💡 Examples [#-examples]

**Build → test jobs:**

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7

  verify:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist
      - run: ls -R dist
```

**Multiple paths:**

```yaml
- uses: actions/upload-artifact@v4
  with:
    name: reports
    path: |
      coverage/
      test-results/
```

## ⚠️ Pitfalls [#️-pitfalls]

* Artifact v3/v4 APIs differ—match upload/download major versions.
* Uploading huge `node_modules` wastes storage—upload only build outputs.
* Name collisions across matrix cells—include `$\{\{ matrix.* \}\}` in the name.
* Expired artifacts disappear—don’t rely on them as a package registry.
* Sensitive files in artifacts are downloadable by users with permission—filter carefully.
* Compression and path layout differ; always `ls` after download in CI once.

## 🔗 Related [#-related]

* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [caching.md](/docs/github-actions/caching)
* [matrix.md](/docs/github-actions/matrix)
* [github\_pages.md](/docs/github-actions/github-pages)
* [docker.md](/docs/github-actions/docker)


# Caching (/docs/github-actions/caching)



# Caching [#caching]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Caching restores dependencies between runs with `actions/cache` or setup-action built-in caches (`setup-node`, `setup-python`). Good keys save minutes; bad keys cause stale builds. Caches are scoped per branch with restore fallbacks.

## 🔧 Core concepts [#-core-concepts]

| Piece          | Role                                 |
| -------------- | ------------------------------------ |
| `key`          | Exact cache identity                 |
| `restore-keys` | Prefix fallbacks                     |
| `path`         | Directories to save                  |
| Hit / miss     | Logged in step output                |
| Branch scope   | Default branch caches more shareable |
| Size limits    | Eviction when over quota             |

Prefer official setup actions’ `cache: true` / `cache-dependency-path` when available—they encode good defaults.

## 💡 Examples [#-examples]

**Node via setup-node:**

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: npm
    cache-dependency-path: package-lock.json
- run: npm ci
```

**Explicit actions/cache:**

```yaml
- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-
```

**Go modules sketch:**

```yaml
- uses: actions/cache@v4
  with:
    path: |
      ~/.cache/go-build
      ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don’t cache build outputs that must be clean—cache package managers, not `dist`, unless intentional.
* Overly broad `restore-keys` can restore wrong versions and cause subtle bugs.
* Post-job save fails if the job was canceled early—understand when saves run.
* OS must be part of the key when paths differ across runners.
* Secrets in cached paths can persist—exclude credential dirs.
* Cache is not a secure artifact store or substitute for lockfiles.

## 🔗 Related [#-related]

* [setup\_node.md](/docs/github-actions/setup-node)
* [setup\_python.md](/docs/github-actions/setup-python)
* [artifacts.md](/docs/github-actions/artifacts)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [runners.md](/docs/github-actions/runners)


# Checkout (/docs/github-actions/checkout)



# Checkout [#checkout]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`actions/checkout` clones your repository into the runner workspace. It is usually the first step. Configure depth, ref, submodules, and credentials for push or private dependencies.

## 🔧 Core concepts [#-core-concepts]

| Input                 | Role                                    |
| --------------------- | --------------------------------------- |
| `ref`                 | Branch, tag, or SHA                     |
| `fetch-depth`         | `0` = full history; `1` default shallow |
| `submodules`          | `true` / `recursive`                    |
| `token`               | PAT or `GITHUB_TOKEN`                   |
| `persist-credentials` | Leave creds for later git ops           |
| `path`                | Clone into subdirectory                 |
| `lfs`                 | Fetch Git LFS files                     |

Default checkout uses the triggering commit SHA for most events. For PRs, it checks out the merge commit unless configured otherwise.

## 💡 Examples [#-examples]

**Standard:**

```yaml
- uses: actions/checkout@v4
```

**Full history + tags (changelogs):**

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0
    fetch-tags: true
```

**Push commits back:**

```yaml
- uses: actions/checkout@v4
  with:
    token: ${{ secrets.GH_PAT }}
    persist-credentials: true
- run: |
    git config user.name "github-actions[bot]"
    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
    # … commit …
    git push
```

**Subdirectory:**

```yaml
- uses: actions/checkout@v4
  with:
    path: app
```

## ⚠️ Pitfalls [#️-pitfalls]

* Shallow clones break `git describe` / some version tools—raise `fetch-depth`.
* `persist-credentials: true` + write token can allow unexpected pushes.
* Private submodules need a token with access.
* `pull_request_target` + checkout of PR head is a classic secret-exfiltration risk.
* LFS failures are silent if not enabled—set `lfs: true` when needed.
* Multiple checkouts need distinct `path` values.

## 🔗 Related [#-related]

* [permissions.md](/docs/github-actions/permissions)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [secrets\_env.md](/docs/github-actions/secrets-env)
* [composite\_actions.md](/docs/github-actions/composite-actions)
* [events\_triggers.md](/docs/github-actions/events-triggers)


# Composite Actions (/docs/github-actions/composite-actions)



# Composite Actions [#composite-actions]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Composite actions bundle multiple steps into a reusable `action.yml` with `runs.using: composite`. Unlike reusable workflows (job-level), composites plug in as a single step. Ideal for shared setup sequences within or across repos.

## 🔧 Core concepts [#-core-concepts]

| Piece                   | Role                                            |
| ----------------------- | ----------------------------------------------- |
| `action.yml`            | Metadata + inputs/outputs                       |
| `runs.using: composite` | Step bundle                                     |
| `runs.steps`            | Same shape as workflow steps                    |
| `inputs`                | Parameters from `with:`                         |
| `outputs`               | Mapped from step outputs                        |
| Location                | `org/repo/path@ref` or `./.github/actions/name` |

JavaScript and Docker actions are alternatives when you need richer logic or containers.

## 💡 Examples [#-examples]

**`.github/actions/setup-app/action.yml`:**

```yaml
name: Setup app
description: Checkout deps already assumed; install toolchains
inputs:
  node-version:
    required: true
    default: '22'
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash
```

**Use it:**

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/setup-app
    with:
      node-version: '22'
  - run: npm test
```

**Output pattern:**

```yaml
outputs:
  version:
    value: ${{ steps.meta.outputs.version }}
runs:
  using: composite
  steps:
    - id: meta
      shell: bash
      run: echo "version=1.2.3" >> "$GITHUB_OUTPUT"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Every `run` step in a composite **must** set `shell:`.
* Composites can’t directly grant extra `permissions`—caller workflow controls token.
* Nested `uses` of other actions is fine; keep versions pinned.
* Don’t confuse with reusable workflows—composites don’t create jobs.
* Local path actions require checkout first.
* Outputs must be declared and wired explicitly.

## 🔗 Related [#-related]

* [reusable\_workflows.md](/docs/github-actions/reusable-workflows)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [checkout.md](/docs/github-actions/checkout)
* [setup\_node.md](/docs/github-actions/setup-node)
* [expressions.md](/docs/github-actions/expressions)


# Docker (/docs/github-actions/docker)



# Docker [#docker]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

GitHub Actions can build/push images, run jobs inside containers, and use service containers (Postgres, Redis). Authenticate to GHCR or Docker Hub with secrets or `GITHUB_TOKEN`. Keep tags immutable for releases.

## 🔧 Core concepts [#-core-concepts]

| Pattern                    | Use                           |
| -------------------------- | ----------------------------- |
| `container:` on job        | Run all steps in an image     |
| `services:`                | Sidecar containers with ports |
| `docker build` / buildx    | Image builds                  |
| `docker/login-action`      | Registry auth                 |
| `docker/build-push-action` | Build + push                  |
| GHCR                       | `ghcr.io/owner/name`          |

Job containers still need checkout and careful volume/workspace handling. Services are reachable by hostname = service id.

## 💡 Examples [#-examples]

**Service container:**

```yaml
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      db:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: postgres
        ports: ['5432:5432']
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/postgres
    steps:
      - uses: actions/checkout@v4
      - run: npm test
```

**Build and push GHCR:**

```yaml
permissions:
  contents: read
  packages: write
steps:
  - uses: actions/checkout@v4
  - uses: docker/login-action@v3
    with:
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}
  - uses: docker/build-push-action@v6
    with:
      push: true
      tags: ghcr.io/${{ github.repository }}:latest
```

## ⚠️ Pitfalls [#️-pitfalls]

* `localhost` from a **job container** to a service may need the service name, not localhost—topology differs.
* Layer caching needs explicit buildx cache config.
* Publishing `:latest` only is fragile—also tag SHAs/versions.
* Rootless / permission issues writing workspace files from containers.
* Don’t bake secrets into images; use runtime env.
* Windows containers are a separate ecosystem from Linux images.

## 🔗 Related [#-related]

* [runners.md](/docs/github-actions/runners)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [secrets\_env.md](/docs/github-actions/secrets-env)
* [permissions.md](/docs/github-actions/permissions)
* [artifacts.md](/docs/github-actions/artifacts)


# Environments (/docs/github-actions/environments)



# Environments [#environments]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Environments (`environment: production`) gate deployments with protection rules: required reviewers, wait timers, and branch restrictions. Each environment can hold dedicated secrets and variables. Use them to separate staging and production credentials.

## 🔧 Core concepts [#-core-concepts]

| Feature                    | Role                        |
| -------------------------- | --------------------------- |
| `environment:`             | Bind job to named env       |
| `environment.name` / `url` | Name + deployment URL       |
| Protection rules           | Approvals, wait timer       |
| Deployment branches        | Limit which refs can deploy |
| Env secrets/vars           | Scoped credentials          |
| Deployment history         | Visible in repo UI          |

Environments are configured in repo **Settings → Environments**. Public repos have limitations on private env secrets for forks.

## 💡 Examples [#-examples]

**Simple environment:**

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh
        env:
          TOKEN: ${{ secrets.DEPLOY_TOKEN }}
```

**Dynamic name:**

```yaml
environment: ${{ inputs.target }}
```

**With concurrency:**

```yaml
concurrency:
  group: deploy-production
  cancel-in-progress: false
jobs:
  deploy:
    environment: production
    …
```

## ⚠️ Pitfalls [#️-pitfalls]

* Job waits indefinitely for approval—communicate SLAs to reviewers.
* Environment secrets aren’t available until the job is approved (by design).
* Misnamed environments create new empty envs silently—match Settings names.
* Protection rules don’t replace proper authz in your deploy scripts.
* `url` is informational for the UI; it doesn’t verify the deployment.
* Combining matrix + environment can create many deployment records—name carefully.

## 🔗 Related [#-related]

* [secrets\_env.md](/docs/github-actions/secrets-env)
* [permissions.md](/docs/github-actions/permissions)
* [events\_triggers.md](/docs/github-actions/events-triggers)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [github\_pages.md](/docs/github-actions/github-pages)


# Events & Triggers (/docs/github-actions/events-triggers)



# Events & Triggers [#events--triggers]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `on` map selects which GitHub events start a workflow. Filter by branches, paths, tags, activity types, and cron schedules. Choose the narrowest trigger to save minutes and reduce noise.

## 🔧 Core concepts [#-core-concepts]

| Event                      | Typical use        |
| -------------------------- | ------------------ |
| `push`                     | CI on commits      |
| `pull_request`             | PR checks          |
| `workflow_dispatch`        | Manual run         |
| `schedule`                 | Cron (UTC)         |
| `release`                  | Publish on release |
| `workflow_call`            | Reusable callee    |
| `repository_dispatch`      | External webhook   |
| `issues` / `issue_comment` | Issue automation   |

Filters: `branches`, `branches-ignore`, `paths`, `paths-ignore`, `tags`, `types`. For PRs, `pull_request` runs in the merge context; `pull_request_target` is privileged—use carefully.

## 💡 Examples [#-examples]

**Push / PR with path filters:**

```yaml
on:
  push:
    branches: [main]
    paths: ['src/**', 'package.json']
  pull_request:
    paths: ['src/**']
```

**Manual + inputs:**

```yaml
on:
  workflow_dispatch:
    inputs:
      environment:
        description: Target
        required: true
        default: staging
        type: choice
        options: [staging, prod]
```

**Cron (every day 06:00 UTC):**

```yaml
on:
  schedule:
    - cron: '0 6 * * *'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Scheduled workflows only run if the default branch contains the file and the repo is active.
* Cron is UTC; expect delays under load.
* `paths` filters don’t apply the way you expect for some events—read docs per event.
* `pull_request_target` + checkout of PR code is a security footgun.
* Fork PRs get a read-only `GITHUB_TOKEN` with restricted secrets.
* Duplicate runs: `push` + `pull_request` both fire for same change—use concurrency or conditionals.

## 🔗 Related [#-related]

* [workflow\_syntax.md](/docs/github-actions/workflow-syntax)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [secrets\_env.md](/docs/github-actions/secrets-env)
* [permissions.md](/docs/github-actions/permissions)
* [environments.md](/docs/github-actions/environments)


# Expressions (/docs/github-actions/expressions)



# Expressions [#expressions]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Expressions (`$\{\{ \}\}`) evaluate values for `if`, `env`, `with`, and names. Contexts expose github metadata, secrets, vars, matrix, needs, and steps outputs. Functions like `contains`, `hashFiles`, and `success()` power conditionals.

## 🔧 Core concepts [#-core-concepts]

| Context            | Contents                              |
| ------------------ | ------------------------------------- |
| `github`           | Event, ref, sha, actor, repository    |
| `env`              | Environment variables                 |
| `secrets` / `vars` | Config                                |
| `matrix`           | Strategy values                       |
| `needs`            | Upstream job results/outputs          |
| `steps`            | Step outputs                          |
| `runner`           | OS, arch, temp                        |
| `inputs`           | `workflow_dispatch` / `workflow_call` |

Common functions: `success()`, `failure()`, `cancelled()`, `always()`, `contains()`, `startsWith()`, `format()`, `toJSON()`, `hashFiles()`, `fromJSON()`.

## 💡 Examples [#-examples]

**Conditionals:**

```yaml
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
if: failure()
if: always() && needs.build.result == 'success'
```

**hashFiles + format:**

```yaml
key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
name: Build ${{ format('{0} ({1})', matrix.os, matrix.node) }}
```

**FromJSON for dynamic matrices:**

```yaml
strategy:
  matrix: ${{ fromJSON(needs.setup.outputs.matrix) }}
```

**Step output consumption:**

```yaml
if: steps.changes.outputs.app == 'true'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Inside `if:`, the `$\{\{ \}\}` wrapper is optional but mixing quotes is error-prone.
* Secrets are not available in some contexts (e.g. `hashFiles` inputs)—don’t try to hash secrets.
* `github.head_ref` is empty outside PRs—guard with event checks.
* Boolean strings: `'false'` is truthy as a non-empty string—compare carefully.
* `hashFiles` returns empty if no match—keys may collide unexpectedly.
* Multi-line expressions and YAML parsing—prefer single-line `if` when possible.

## 🔗 Related [#-related]

* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [matrix.md](/docs/github-actions/matrix)
* [secrets\_env.md](/docs/github-actions/secrets-env)
* [workflow\_syntax.md](/docs/github-actions/workflow-syntax)
* [events\_triggers.md](/docs/github-actions/events-triggers)


# GitHub Pages (/docs/github-actions/github-pages)



# GitHub Pages [#github-pages]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Deploy static sites to GitHub Pages with Actions using `actions/upload-pages-artifact` and `actions/deploy-pages`. Configure the repo to deploy from **GitHub Actions** (not the classic branch). Grant `pages: write` and `id-token: write`.

## 🔧 Core concepts [#-core-concepts]

| Piece                       | Role                                |
| --------------------------- | ----------------------------------- |
| Pages source                | Settings → Pages → GitHub Actions   |
| `upload-pages-artifact`     | Package static files                |
| `deploy-pages`              | Publish artifact                    |
| `environment: github-pages` | Standard env + URL output           |
| Custom domain               | Repo Pages settings + DNS           |
| Project vs user site        | `/\{repo\}` vs `username.github.io` |

Build with any static generator (Next export, Vite, Hugo, MkDocs). Only static assets are served.

## 💡 Examples [#-examples]

**Classic static deploy:**

```yaml
name: Deploy Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
concurrency:
  group: pages
  cancel-in-progress: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci && npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `id-token: write` breaks OIDC-based Pages deploy.
* Wrong artifact `path` uploads empty/wrong site—verify build output dir.
* SPA routing needs `404.html` tricks or platform rules—Pages is static only.
* Base path for project sites (`/repo-name/`) must match bundler `base` config.
* Custom domains require both DNS and Pages settings; HTTPS provisioning takes time.
* Don’t commit secrets into static JS—anything in `dist` is public.

## 🔗 Related [#-related]

* [permissions.md](/docs/github-actions/permissions)
* [artifacts.md](/docs/github-actions/artifacts)
* [environments.md](/docs/github-actions/environments)
* [setup\_node.md](/docs/github-actions/setup-node)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)


# Glossary (/docs/github-actions/glossary)



# Glossary [#glossary]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core GitHub Actions terms for workflows, jobs, runners, secrets, and reusable automation.

## 🔧 Core concepts [#-core-concepts]

| Term              | Definition                                                                            |
| ----------------- | ------------------------------------------------------------------------------------- |
| Action            | A reusable unit of work published for use as a step (`uses:`).                        |
| Artifact          | A file set uploaded from a job and downloadable later in the workflow.                |
| Cache             | Stored dependencies keyed for faster restores across runs.                            |
| Checkout          | The common first step that clones the repository onto the runner.                     |
| Composite action  | An action defined as a sequence of steps in an `action.yml`.                          |
| Concurrency       | Controls that cancel or queue overlapping workflow runs.                              |
| Context           | Built-in objects such as `github`, `env`, `secrets`, and `steps` used in expressions. |
| Environment       | A named deployment target with protection rules and secrets.                          |
| Event             | A repository activity that can trigger a workflow, such as `push`.                    |
| Expression        | A `$\{\{ \}\}` expression evaluated for conditions, inputs, and contexts.             |
| Job               | A set of steps that runs on the same runner.                                          |
| Matrix            | A strategy that expands one job into many variants of inputs.                         |
| Needs             | A job dependency declaring that another job must succeed first.                       |
| OIDC              | Federated auth letting workflows obtain cloud tokens without long-lived keys.         |
| Permission        | Token scopes limiting what `GITHUB_TOKEN` may do.                                     |
| Reusable workflow | A callable workflow invoked by other workflows with `uses:`.                          |
| Runner            | The machine (GitHub-hosted or self-hosted) that executes a job.                       |
| Secret            | An encrypted value exposed to workflows as an environment variable.                   |
| Service container | A Docker service (e.g. Postgres) attached to a job for tests.                         |
| Step              | A single command or action invocation inside a job.                                   |
| Trigger           | The `on:` configuration that starts a workflow for matching events.                   |
| Workflow          | A YAML automation file under `.github/workflows/`.                                    |
| Workflow call     | The event that allows one workflow to be invoked by another.                          |
| Workflow dispatch | A manual trigger that can accept typed inputs.                                        |
| Workflow run      | One execution instance of a workflow.                                                 |

## 💡 Examples [#-examples]

**Workflow trigger and job:**

```yaml
name: CI
on:
  push:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
      - run: npm ci && npm test
```

**Matrix strategy:**

```yaml
strategy:
  matrix:
    node: [20, 22]
    os: [ubuntu-latest, windows-latest]
runs-on: ${{ matrix.os }}
```

**Secrets and expressions:**

```yaml
env:
  API_KEY: ${{ secrets.API_KEY }}
if: ${{ github.ref == 'refs/heads/main' }}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **job** (runner-scoped) with **step** (sequential unit inside a job).
* Mixing **secrets** (encrypted) with ordinary **env** vars committed in YAML.
* Treating **cache** as an artifact store — caches are best-effort and can miss.
* Equating **reusable workflows** with **composite actions** — different call sites and capabilities.
* Assuming **matrix** failures always fail-fast the same way — `fail-fast` is configurable.

## 🔗 Related [#-related]

* [workflow\_syntax](/docs/github-actions/workflow-syntax)
* [jobs\_steps](/docs/github-actions/jobs-steps)
* [events\_triggers](/docs/github-actions/events-triggers)
* [matrix](/docs/github-actions/matrix)
* [secrets\_env](/docs/github-actions/secrets-env)
* [caching](/docs/github-actions/caching)


# GitHub Actions (/docs/github-actions)



# GitHub Actions [#github-actions]

CI/CD workflows.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Jobs & Steps (/docs/github-actions/jobs-steps)



# Jobs & Steps [#jobs--steps]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Jobs run in parallel by default on separate runners. Steps within a job run sequentially and share the workspace. Use `needs` for dependencies, `if` for conditions, and map outputs between jobs.

## 🔧 Core concepts [#-core-concepts]

| Key                 | Role                  |
| ------------------- | --------------------- |
| `jobs.<id>.runs-on` | Runner label          |
| `needs`             | Job dependencies      |
| `if`                | Conditional execution |
| `steps[].uses`      | Run an action         |
| `steps[].run`       | Shell command         |
| `steps[].name`      | UI label              |
| `steps[].id`        | Reference outputs     |
| `outputs`           | Job-level outputs     |
| `continue-on-error` | Soft-fail step        |
| `timeout-minutes`   | Cap duration          |

Each step can set `working-directory`, `env`, and `shell`. Failures cancel dependent jobs unless configured otherwise.

## 💡 Examples [#-examples]

**Dependent jobs + outputs:**

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.meta.outputs.version }}
    steps:
      - uses: actions/checkout@v4
      - id: meta
        run: echo "version=$(node -p 'require("./package.json").version')" >> "$GITHUB_OUTPUT"

  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "Deploying ${{ needs.build.outputs.version }}"
```

**Multi-line script:**

```yaml
- name: Build
  run: |
    npm ci
    npm run build
```

## ⚠️ Pitfalls [#️-pitfalls]

* Jobs don’t share filesystem—pass data via artifacts or outputs.
* `needs` + `if: always()` patterns are easy to get wrong for cleanup jobs.
* Step outputs must be written to `$GITHUB_OUTPUT` (not deprecated `set-output`).
* Matrix jobs expand into many jobs—watch billing and `fail-fast`.
* `working-directory` doesn’t apply to `uses:` the same way—check action docs.
* Shell differences: bash on Linux/macOS, PowerShell default on Windows.

## 🔗 Related [#-related]

* [runners.md](/docs/github-actions/runners)
* [matrix.md](/docs/github-actions/matrix)
* [artifacts.md](/docs/github-actions/artifacts)
* [expressions.md](/docs/github-actions/expressions)
* [workflow\_syntax.md](/docs/github-actions/workflow-syntax)


# Matrix (/docs/github-actions/matrix)



# Matrix [#matrix]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A strategy matrix expands one job into many combinations (OS, language version, flags). Use `include` / `exclude` to refine, `fail-fast` to control cancellation, and `max-parallel` to limit concurrency.

## 🔧 Core concepts [#-core-concepts]

| Key                    | Role                                      |
| ---------------------- | ----------------------------------------- |
| `strategy.matrix`      | Axes of values                            |
| `$\{\{ matrix.os \}\}` | Reference a cell                          |
| `include`              | Add/override combos                       |
| `exclude`              | Remove combos                             |
| `fail-fast`            | Cancel siblings on failure (default true) |
| `max-parallel`         | Cap simultaneous matrix jobs              |

Matrix context is available in `runs-on`, `env`, step `name`, and `if`. Nested objects in matrix are allowed.

## 💡 Examples [#-examples]

**OS × Node:**

```yaml
jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [20, 22]
        exclude:
          - os: windows-latest
            node: 20
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      - run: npm test
```

**Include extra job:**

```yaml
strategy:
  matrix:
    shard: [1, 2, 3]
    include:
      - shard: 1
        extra_flag: '--coverage'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Combinatorial explosion burns minutes—keep axes small.
* `fail-fast: true` can hide sibling failures when debugging flakes.
* Expression errors in matrix values fail the whole job graph.
* Windows vs bash shell differences across OS matrix cells.
* Job names collide in UI—set dynamic `name:` including matrix values.
* Reusable workflows have limits on matrix passthrough—check docs.

## 🔗 Related [#-related]

* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [runners.md](/docs/github-actions/runners)
* [setup\_node.md](/docs/github-actions/setup-node)
* [setup\_python.md](/docs/github-actions/setup-python)
* [expressions.md](/docs/github-actions/expressions)


# Permissions (/docs/github-actions/permissions)



# Permissions [#permissions]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`permissions` limits what `GITHUB_TOKEN` can do. Default token permissions have tightened over time—set least privilege explicitly at workflow or job level. Extra access for packages, PRs, or Pages must be granted deliberately.

## 🔧 Core concepts [#-core-concepts]

| Scope examples    | Values                              |
| ----------------- | ----------------------------------- |
| `contents`        | `read` / `write` / `none`           |
| `actions`         | Manage artifacts/workflows metadata |
| `checks`          | Status checks                       |
| `pull-requests`   | Comment / label PRs                 |
| `id-token`        | `write` for OIDC                    |
| `pages`           | GitHub Pages deploy                 |
| `packages`        | GHCR / packages                     |
| `security-events` | Code scanning uploads               |

Workflow-level permissions apply to all jobs unless a job overrides. `permissions: \{\}` denies all (then grant per job).

## 💡 Examples [#-examples]

**Read-only CI:**

```yaml
permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
```

**PR bot job:**

```yaml
jobs:
  comment:
    permissions:
      contents: read
      pull-requests: write
    runs-on: ubuntu-latest
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              ...context.issue,
              body: 'Thanks for the PR!'
            })
```

**OIDC to cloud:**

```yaml
permissions:
  id-token: write
  contents: read
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `pull-requests: write` causes cryptic API 403s when commenting.
* Elevating `contents: write` on untrusted PR workflows is dangerous.
* Org/repo settings can restrict maximum token permissions—workflow can’t exceed them.
* Fork PRs still have reduced secret access regardless of permissions block.
* `actions/checkout` with persist-credentials + write token can push—disable when unused.
* Document why each write scope exists in comments.

## 🔗 Related [#-related]

* [secrets\_env.md](/docs/github-actions/secrets-env)
* [workflow\_syntax.md](/docs/github-actions/workflow-syntax)
* [checkout.md](/docs/github-actions/checkout)
* [github\_pages.md](/docs/github-actions/github-pages)
* [environments.md](/docs/github-actions/environments)


# Reusable Workflows (/docs/github-actions/reusable-workflows)



# Reusable Workflows [#reusable-workflows]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Reusable workflows let one workflow call another with `workflow_call` / `uses: org/repo/.github/workflows/file.yml@ref`. Share CI patterns across repos while keeping callers thin. Pass inputs, secrets, and read outputs from called jobs.

## 🔧 Core concepts [#-core-concepts]

| Piece                             | Role                       |
| --------------------------------- | -------------------------- |
| `on.workflow_call`                | Define a callable workflow |
| `inputs` / `secrets`              | Contract for callers       |
| `uses: ./.github/workflows/x.yml` | Same-repo call             |
| `uses: org/repo/...@v1`           | Cross-repo call            |
| `with:` / `secrets:`              | Pass values                |
| `jobs.*.outputs`                  | Return data to caller      |

Called workflows run as jobs from the caller’s perspective (`needs` works). Nesting depth and some features (e.g. certain matrix cases) have limits.

## 💡 Examples [#-examples]

**Callee (`_ci.yml`):**

```yaml
name: Reusable CI
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '22'
    secrets:
      NPM_TOKEN:
        required: false

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
      - run: npm ci
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
      - run: npm test
```

**Caller:**

```yaml
jobs:
  call-ci:
    uses: ./.github/workflows/_ci.yml
    with:
      node-version: '20'
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Caller must explicitly pass secrets—`secrets: inherit` only when appropriate.
* Version-pin `@ref` for cross-repo reuse; floating branches can break you.
* Not everything is supported inside reusable workflows (check current limits).
* Debugging spans two files—add clear job names.
* Permissions are evaluated carefully across caller/callee—set both as needed.
* Avoid deep nesting; prefer one reusable layer.

## 🔗 Related [#-related]

* [composite\_actions.md](/docs/github-actions/composite-actions)
* [workflow\_syntax.md](/docs/github-actions/workflow-syntax)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [secrets\_env.md](/docs/github-actions/secrets-env)
* [expressions.md](/docs/github-actions/expressions)


# Runners (/docs/github-actions/runners)



# Runners [#runners]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Runners execute jobs. GitHub-hosted runners (`ubuntu-latest`, `windows-latest`, `macos-latest`) are ephemeral VMs. Self-hosted runners persist on your hardware—isolate them carefully. Labels select where a job lands.

## 🔧 Core concepts [#-core-concepts]

| Label                       | Notes                         |
| --------------------------- | ----------------------------- |
| `ubuntu-latest`             | Default Linux; version floats |
| `ubuntu-24.04` / `22.04`    | Pin OS image                  |
| `windows-latest`            | PowerShell default shell      |
| `macos-latest`              | Scarcer / costlier            |
| `[self-hosted, linux, x64]` | Custom labels                 |

| Topic      | Detail                                           |
| ---------- | ------------------------------------------------ |
| Tool cache | Preinstalled SDKs on hosted images               |
| Specs      | CPU/RAM vary by label (larger runners available) |
| Networking | Outbound internet; inbound limited               |
| Ephemeral  | Hosted disk resets each job                      |

Image software lists live in `actions/runner-images`.

## 💡 Examples [#-examples]

**Hosted job:**

```yaml
jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - run: lsb_release -a
      - run: node -v || true
```

**Self-hosted:**

```yaml
jobs:
  build:
    runs-on: [self-hosted, linux, gpu]
    steps:
      - uses: actions/checkout@v4
      - run: ./build.sh
```

**Larger runners (org feature):**

```yaml
runs-on: ubuntu-latest-4-cores
```

## ⚠️ Pitfalls [#️-pitfalls]

* `*-latest` moves—pin versions for reproducibility when it matters.
* Self-hosted runners can retain secrets/workspace—use ephemeral runners or strict cleanup.
* Never attach self-hosted runners to public repos without hardening (fork PR risk).
* macOS minutes cost more—use only when required.
* Custom container jobs (`container:`) change the environment vs bare VM.
* Software may be missing—use setup actions instead of assuming host tools.

## 🔗 Related [#-related]

* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [docker.md](/docs/github-actions/docker)
* [matrix.md](/docs/github-actions/matrix)
* [setup\_node.md](/docs/github-actions/setup-node)
* [setup\_python.md](/docs/github-actions/setup-python)


# Secrets & Environment Variables (/docs/github-actions/secrets-env)



# Secrets & Environment Variables [#secrets--environment-variables]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Use repository/org/environment **secrets** for sensitive values and **variables** for non-sensitive config. Map them into `env` at workflow, job, or step scope. Secrets are masked in logs but not a full security boundary—avoid echoing them.

## 🔧 Core concepts [#-core-concepts]

| Source              | Access                         |
| ------------------- | ------------------------------ |
| Secrets             | `$\{\{ secrets.NAME \}\}`      |
| Vars                | `$\{\{ vars.NAME \}\}`         |
| `GITHUB_TOKEN`      | Auto-provided job token        |
| `env:`              | Static or expression-based env |
| Environment secrets | Bound via `environment:`       |
| Org secrets         | Shared with selected repos     |

Never commit `.env` with real credentials. Prefer OIDC/`token` exchange over long-lived cloud keys when possible.

## 💡 Examples [#-examples]

**Wire secrets to env:**

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    env:
      APP_ENV: ${{ vars.APP_ENV }}
      API_KEY: ${{ secrets.API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: ./deploy.sh
```

**Step-level only:**

```yaml
- name: Publish
  env:
    NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
  run: npm publish
```

**Set env dynamically:**

```yaml
- run: echo "SHA_SHORT=${GITHUB_SHA::8}" >> "$GITHUB_ENV"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fork PRs usually cannot read repo secrets.
* Masking is best-effort—partial prints / base64 may leak.
* `pull_request_target` can expose secrets to untrusted code if you check out PR SHA unsafely.
* Empty secrets fail differently than missing vars—validate early.
* Don’t store huge blobs in secrets; use OIDC or encrypted storage.
* `GITHUB_TOKEN` permissions are limited by workflow `permissions:` and defaults.

## 🔗 Related [#-related]

* [permissions.md](/docs/github-actions/permissions)
* [environments.md](/docs/github-actions/environments)
* [events\_triggers.md](/docs/github-actions/events-triggers)
* [expressions.md](/docs/github-actions/expressions)
* [workflow\_syntax.md](/docs/github-actions/workflow-syntax)


# Setup Node (/docs/github-actions/setup-node)



# Setup Node [#setup-node]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`actions/setup-node` installs a Node.js version, optionally adds registry auth, and can cache npm/yarn/pnpm dependencies. Pair with `npm ci` for reproducible CI installs.

## 🔧 Core concepts [#-core-concepts]

| Input                   | Role                                        |
| ----------------------- | ------------------------------------------- |
| `node-version`          | e.g. `22`, `22.11.0`, `lts/*`               |
| `node-version-file`     | `.nvmrc` / `.node-version` / `package.json` |
| `cache`                 | `npm` / `yarn` / `pnpm`                     |
| `cache-dependency-path` | Lockfile path(s)                            |
| `registry-url`          | Scoped registry                             |
| `scope`                 | npm scope for auth                          |

Matrix Node versions to catch compatibility issues. Prefer lockfiles committed to the repo.

## 💡 Examples [#-examples]

**npm CI:**

```yaml
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'
    cache: npm
- run: npm ci
- run: npm test
```

**Matrix:**

```yaml
strategy:
  matrix:
    node: [20, 22]
steps:
  - uses: actions/setup-node@v4
    with:
      node-version: ${{ matrix.node }}
      cache: npm
```

**Publish with auth:**

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: 22
    registry-url: 'https://registry.npmjs.org'
- run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `npm install` mutates lockfiles—use `npm ci` in CI.
* Cache key misses when lockfile path is wrong (monorepos need `cache-dependency-path`).
* pnpm/yarn need their own install steps and often `packageManager` / corepack.
* Global tools installed in one job aren’t in another—reinstall or use artifacts.
* Windows path lengths / script shells differ—test matrix cells.
* Don’t commit `.npmrc` with tokens; inject via env/secrets.

## 🔗 Related [#-related]

* [setup\_python.md](/docs/github-actions/setup-python)
* [caching.md](/docs/github-actions/caching)
* [matrix.md](/docs/github-actions/matrix)
* [checkout.md](/docs/github-actions/checkout)
* [secrets\_env.md](/docs/github-actions/secrets-env)


# Setup Python (/docs/github-actions/setup-python)



# Setup Python [#setup-python]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`actions/setup-python` installs Python, exposes `python`/`pip`, and can cache pip dependencies. Use version files or matrices for multi-version testing. Prefer `pip install -r` with hashed requirements or lock tools (pip-tools, poetry, uv) for reproducibility.

## 🔧 Core concepts [#-core-concepts]

| Input                   | Role                        |
| ----------------------- | --------------------------- |
| `python-version`        | `3.12`, `3.12.x`            |
| `python-version-file`   | `.python-version`           |
| `cache`                 | `pip` / `pipenv` / `poetry` |
| `cache-dependency-path` | Requirements/lock paths     |
| `architecture`          | `x64` / `arm64`             |

Virtualenvs are optional on clean runners; still useful for clarity. Tox/nox/pytest fit naturally after setup.

## 💡 Examples [#-examples]

**pip + cache:**

```yaml
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
    cache: pip
    cache-dependency-path: requirements*.txt
- run: pip install -r requirements.txt
- run: pytest -q
```

**Matrix:**

```yaml
strategy:
  matrix:
    python: ['3.11', '3.12', '3.13']
steps:
  - uses: actions/setup-python@v5
    with:
      python-version: ${{ matrix.python }}
```

**Poetry sketch:**

```yaml
- uses: actions/setup-python@v5
  with:
    python-version-file: '.python-version'
    cache: poetry
- run: pipx install poetry
- run: poetry install --no-interaction
- run: poetry run pytest
```

## ⚠️ Pitfalls [#️-pitfalls]

* System Python on the image ≠ your setup-python version—always run setup first.
* Cache won’t help if dependency files aren’t hashed correctly.
* Compiled wheels differ by OS—matrix Linux/macOS/Windows when shipping binaries.
* `PYTHONPATH` / editable installs can hide packaging issues—test the sdist/wheel occasionally.
* Secrets for private indexes belong in env, not committed `pip.conf`.
* Match black/ruff/mypy versions to local tooling via pins.

## 🔗 Related [#-related]

* [setup\_node.md](/docs/github-actions/setup-node)
* [caching.md](/docs/github-actions/caching)
* [matrix.md](/docs/github-actions/matrix)
* [checkout.md](/docs/github-actions/checkout)
* [runners.md](/docs/github-actions/runners)


# Workflow Syntax (/docs/github-actions/workflow-syntax)



# Workflow Syntax [#workflow-syntax]

*GitHub Actions · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Workflows live in `.github/workflows/*.yml` and define when automation runs (`on`), what it does (`jobs`), and how steps execute. YAML indentation matters. Start from a minimal workflow, then add permissions, concurrency, and reuse.

## 🔧 Core concepts [#-core-concepts]

| Key           | Role                                  |
| ------------- | ------------------------------------- |
| `name`        | UI label                              |
| `on`          | Events / schedules                    |
| `permissions` | Token scopes                          |
| `env`         | Workflow-level env                    |
| `defaults`    | Default `run` shell/working-directory |
| `concurrency` | Cancel/queue overlapping runs         |
| `jobs`        | Map of job IDs                        |
| `run-name`    | Dynamic run title                     |

Top-level `jobs.<id>` contains `runs-on`, `steps`, `needs`, `strategy`, `environment`, etc. Comments use `#`.

## 💡 Examples [#-examples]

**Minimal CI:**

```yaml
name: CI
on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Test
        run: npm test
```

**Defaults:**

```yaml
defaults:
  run:
    shell: bash
    working-directory: ./app
```

## ⚠️ Pitfalls [#️-pitfalls]

* Tabs break YAML—use spaces only.
* Unquoted `on: on` / special values may parse oddly; quote strings when unsure.
* Workflow must be on the default branch to run `pull_request` from forks with some constraints—know fork PR token limits.
* `actions/checkout` and other actions should be pinned to versions/SHAs for supply-chain safety.
* Invalid expressions fail at runtime—validate with act or a dry PR.
* Large monolithic workflows are hard to debug—split jobs.

## 🔗 Related [#-related]

* [events\_triggers.md](/docs/github-actions/events-triggers)
* [jobs\_steps.md](/docs/github-actions/jobs-steps)
* [permissions.md](/docs/github-actions/permissions)
* [expressions.md](/docs/github-actions/expressions)
* [reusable\_workflows.md](/docs/github-actions/reusable-workflows)


# Accessibility (/docs/html/accessibility)



# Accessibility [#accessibility]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Accessible HTML works with keyboards, screen readers, zoom, and captions. Start with semantic elements, keyboard focus, sufficient contrast, and text alternatives. ARIA supplements — it doesn’t replace — native HTML. Aim for WCAG 2.2 AA as a practical baseline.

## 🔧 Core concepts [#-core-concepts]

* **Perceivable**: `alt`, captions, contrast, don’t rely on color alone.
* **Operable**: keyboard access, focus visible, no keyboard traps, enough time.
* **Understandable**: clear labels, consistent nav, error identification.
* **Robust**: valid markup, appropriate roles/names/states.
* **Name, Role, Value**: every control needs an accessible name.
* **Prefer native**: `button`, `a`, `label`, `dialog`, inputs over custom widgets.

```html
<label for="email">Email</label>
<input id="email" name="email" type="email" autocomplete="email" required />

<button type="button" aria-expanded="false" aria-controls="menu">Menu</button>
<ul id="menu" hidden>...</ul>
```

## 💡 Examples [#-examples]

```html
<!-- Skip link -->
<a class="skip-link" href="#main">Skip to content</a>

<!-- Form errors -->
<input id="user" aria-invalid="true" aria-describedby="user-err" />
<p id="user-err" role="alert">Username is taken</p>

<!-- Decorative image -->
<img src="/flourish.svg" alt="" />

<!-- Meaningful image -->
<img src="/chart.png" alt="Sales rose 20% from March to June" />

<!-- Dialog -->
<dialog aria-labelledby="d-title">
  <h2 id="d-title">Confirm delete</h2>
  <button type="button">Cancel</button>
</dialog>

<!-- Reduced motion respect is CSS; live regions: -->
<div aria-live="polite" aria-atomic="true" class="status"></div>
```

```html
<!-- Focus order follows DOM — don’t reorder only with CSS -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* `outline: none` without `:focus-visible` styles excludes keyboard users.
* Icon-only controls without names are silent in AT.
* `aria-hidden="true"` on focusable elements creates traps — also disable/hide from focus.
* Fake placeholders as only labels disappear and hurt UX.
* Auto-playing media with sound violates operable guidelines.

## 🔗 Related [#-related]

* [aria.md](/docs/html/aria) — ARIA patterns
* [semantic.md](/docs/html/semantic) — semantics
* [button.md](/docs/html/button) — controls
* [dialog.md](/docs/html/dialog) — modals
* [../Javascript/DOM/focus\_blur.md](/docs/html/../javascript/dom/focus-blur) — focus


# ARIA (/docs/html/aria)



# ARIA [#aria]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

ARIA (Accessible Rich Internet Applications) adds roles, states, and properties when native HTML can’t express behavior. First rule: **don’t use ARIA if a native element works**. Bad ARIA is worse than none. Focus on accessible name, role, and value.

## 🔧 Core concepts [#-core-concepts]

| Category | Examples                                                                      |          |
| -------- | ----------------------------------------------------------------------------- | -------- |
| Roles    | `button` `dialog` `listbox` `tab` `switch` (prefer native when possible)      |          |
| Names    | `aria-label` `aria-labelledby` `aria-describedby`                             |          |
| Widgets  | `aria-expanded` `aria-selected` `aria-checked` `aria-pressed` `aria-controls` |          |
| Live     | `aria-live` `aria-atomic` `aria-relevant` \`role="status                      | alert"\` |
| Hidden   | `aria-hidden` (never on focusable content)                                    |          |

* **Naming precedence**: `aria-labelledby` > `aria-label` > content > `title` (roughly).
* **Relationships**: `aria-controls`, `aria-owns`, `aria-activedescendant`.
* **HTML parity**: prefer `<button>`, `<dialog>`, `<input>` over role clones.

```html
<button type="button" aria-expanded="false" aria-controls="panel">
  Filters
</button>
<div id="panel" hidden>...</div>
```

## 💡 Examples [#-examples]

```html
<!-- Labelledby -->
<div role="dialog" aria-modal="true" aria-labelledby="t" aria-describedby="d">
  <h2 id="t">Confirm</h2>
  <p id="d">This cannot be undone.</p>
</div>

<!-- Tabs (simplified) -->
<div role="tablist" aria-label="Sections">
  <button role="tab" aria-selected="true" aria-controls="p1" id="t1">One</button>
  <button role="tab" aria-selected="false" aria-controls="p2" id="t2">Two</button>
</div>
<div role="tabpanel" id="p1" aria-labelledby="t1">...</div>
<div role="tabpanel" id="p2" aria-labelledby="t2" hidden>...</div>

<!-- Live region -->
<div role="status" aria-live="polite" id="save-status"></div>

<!-- Switch (or use checkbox) -->
<button type="button" role="switch" aria-checked="false">Notifications</button>
```

```html
<!-- Anti-pattern -->
<div role="button" onclick="...">Save</div>
<!-- Use <button> -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing role without keyboard behavior (e.g. `role="button"` on div without Enter/Space) fails a11y.
* `aria-hidden="true"` on a parent hides all descendants from AT — dangerous with focusable kids.
* Redundant ARIA (`<button role="button">`) adds noise.
* `aria-label` overrides visible text for AT — keep them in sync.
* Don’t use ARIA to “fix” invalid HTML structure.

## 🔗 Related [#-related]

* [accessibility.md](/docs/html/accessibility) — a11y principles
* [semantic.md](/docs/html/semantic) — native first
* [button.md](/docs/html/button) — native controls
* [dialog.md](/docs/html/dialog) — native dialog
* [../Javascript/DOM/focus\_blur.md](/docs/html/../javascript/dom/focus-blur) — focus patterns


# Attributes Basics (/docs/html/attributes-basics)



# Attributes Basics [#attributes-basics]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Attributes** add information to elements: where a link goes, which image to load, an id for CSS/JS, accessibility labels, and more. They appear in the opening tag as `name="value"`.

## 🔧 Core concepts [#-core-concepts]

| Attribute     | Common on                         | Purpose                              |
| ------------- | --------------------------------- | ------------------------------------ |
| `id`          | Most                              | Unique identifier in the page        |
| `class`       | Most                              | Styling / scripting hooks (reusable) |
| `href`        | `a`, `link`                       | URL target                           |
| `src` / `alt` | `img`                             | Image URL and accessible description |
| `lang`        | `html`                            | Document language                    |
| `type`        | `script`, `input`                 | Variant / input kind                 |
| Boolean attrs | `disabled`, `checked`, `required` | Presence means true                  |

Prefer double quotes around values. One `id` per document; classes can repeat.

## 💡 Examples [#-examples]

**Links and images:**

```html
<a href="https://example.com" title="Example site">Visit example</a>
<img src="dog.png" alt="A dog in a park" width="400" height="300" />
```

**id and class:**

```html
<p id="intro" class="lead highlight">Welcome</p>
<button class="btn btn-primary" type="button">Save</button>
```

**Form-related attributes:**

```html
<label for="email">Email</label>
<input
  id="email"
  name="email"
  type="email"
  placeholder="you@example.com"
  required
/>
```

**Boolean attributes:**

```html
<input type="checkbox" checked disabled />
<!-- checked and disabled are true because they are present -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* Duplicate `id` values break `getElementById` and fragment links.
* Missing `alt` on meaningful images fails accessibility.
* `class` is not `Class` / `CLASS` in XHTML-like tooling — use lowercase in HTML.
* Putting raw `&` in attribute URLs should be escaped as `&amp;` in HTML text.

## 🔗 Related [#-related]

* [elements\_basics.md](/docs/html/elements-basics)
* [hello\_world.md](/docs/html/hello-world)
* [links.md](/docs/html/links)
* [data\_attributes.md](/docs/html/data-attributes)


# Button (/docs/html/button)



# Button [#button]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<button>` element performs actions. Prefer it over clickable `<div>`s. Inside forms, `type` defaults to `submit` — set `type="button"` for non-submit actions. Links navigate; buttons act.

## 🔧 Core concepts [#-core-concepts]

| Attribute                       | Role                                               |
| ------------------------------- | -------------------------------------------------- |
| `type`                          | `submit` (default in forms) \| `button` \| `reset` |
| `name` / `value`                | submitted with form when type=submit               |
| `disabled`                      | non-interactive                                    |
| `autofocus`                     | focus on load (use sparingly)                      |
| `form`                          | associate with a form by id                        |
| `formaction` / `formmethod` / … | override form submit attrs                         |

* Content: phrasing content; can include icons + text.
* Keyboard: Enter/Space activate.
* Don’t nest interactive elements inside buttons.

```html
<button type="button" onclick="doThing()">Do thing</button>
<button type="submit">Save</button>
```

## 💡 Examples [#-examples]

```html
<form method="post" action="/save">
  <button type="submit">Save</button>
  <button type="submit" name="intent" value="draft">Save draft</button>
  <button type="reset">Reset</button>
  <button type="button" id="preview">Preview</button>
</form>

<!-- Icon + accessible name -->
<button type="button" aria-label="Close">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

<!-- Toggle -->
<button type="button" aria-pressed="false" aria-expanded="false">
  Menu
</button>

<!-- External form attribute -->
<input id="q" name="q" form="search" />
<button type="submit" form="search">Search</button>
<form id="search" action="/search"></form>

<!-- Disabled with explanation -->
<button type="submit" disabled aria-describedby="why">Pay</button>
<p id="why">Complete shipping first.</p>
```

```html
<!-- Anti-pattern -->
<div onclick="...">Click me</div>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `type="button"` inside forms accidentally submits.
* Disabled buttons are not focusable and may skip errors — explain why.
* Styling `<a>` as a button is fine for navigation; don’t use `<button>` for in-app routes that should be shareable URLs without JS (prefer links).
* `button` with only an icon needs an accessible name (`aria-label` or visually present text).
* `reset` often harms UX — rare in modern apps.

## 🔗 Related [#-related]

* [links.md](/docs/html/links) — links vs buttons
* [form.md](/docs/html/form) — form submission
* [input.md](/docs/html/input) — inputs
* [accessibility.md](/docs/html/accessibility) — names/states
* [aria.md](/docs/html/aria) — aria-pressed/expanded
* [../CSS/button.md](/docs/html/../css/button) — button CSS


# Canvas (/docs/html/canvas)



# Canvas [#canvas]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<canvas>` element provides a blank bitmap drawing surface for 2D graphics, animations, charts, and games via the Canvas API (`CanvasRenderingContext2D`) or WebGL (`WebGLRenderingContext` / `WebGL2RenderingContext`). Markup alone draws nothing—JavaScript obtains a context and paints pixels.

Canvas is a **replaced element**: it has intrinsic width/height attributes (default 300×150 CSS pixels) that define the **bitmap resolution**, separate from CSS display size. Prefer canvas for dynamic, pixel-level drawing; prefer SVG for scalable, DOM-accessible vector graphics.

Accessibility: a canvas is opaque to assistive tech by default. Provide fallback content inside the element, expose meaning with `aria-*` / `role`, or mirror critical UI in the DOM.

## 🔧 Core concepts [#-core-concepts]

### Markup and sizing [#markup-and-sizing]

```html
<canvas id="chart" width="640" height="360" role="img" aria-label="Sales chart">
  Chart unavailable. Sales rose 12% this quarter.
</canvas>
```

* `width` / `height` attributes set the **backing store** in CSS pixels (not CSS `width`/`height`).
* Scaling with CSS without matching attributes blurs the bitmap—multiply by `devicePixelRatio` for sharp retina output.
* Fallback text or HTML between tags shows when canvas is unsupported or for AT.

### Getting a context [#getting-a-context]

```js
const canvas = document.getElementById("chart");
const ctx = canvas.getContext("2d"); // or "webgl", "webgl2", "bitmaprenderer"
if (!ctx) {
  // Fallback UI
}
```

Common 2D operations: `fillRect`, `stroke`, `fillText`, `drawImage`, paths (`beginPath`, `arc`, `lineTo`), transforms, and `requestAnimationFrame` loops.

### Hit testing and interaction [#hit-testing-and-interaction]

Canvas has no DOM nodes for shapes. Track geometry yourself (bounding boxes, path `isPointInPath`) or use libraries. Keyboard focus requires `tabindex="0"` and custom key handlers.

### Offscreen and workers [#offscreen-and-workers]

`OffscreenCanvas` and `createImageBitmap` move heavy drawing off the main thread. Transfer a canvas with `transferControlToOffscreen()` when supported.

### When not to use canvas [#when-not-to-use-canvas]

| Need                      | Prefer        |
| ------------------------- | ------------- |
| Semantic text / links     | HTML          |
| Scalable icons / diagrams | SVG           |
| Form controls             | Native inputs |
| SEO-critical content      | Real DOM text |

## 💡 Examples [#-examples]

### Basic 2D drawing [#basic-2d-drawing]

```html
<canvas id="box" width="200" height="100" aria-label="Blue rectangle"></canvas>
<script>
  const ctx = document.getElementById("box").getContext("2d");
  ctx.fillStyle = "#2563eb";
  ctx.fillRect(20, 20, 160, 60);
</script>
```

### High-DPI setup [#high-dpi-setup]

```html
<canvas id="hi" role="img" aria-label="Sharp circle"></canvas>
<script>
  const canvas = document.getElementById("hi");
  const dpr = window.devicePixelRatio || 1;
  const cssW = 300;
  const cssH = 150;
  canvas.width = Math.round(cssW * dpr);
  canvas.height = Math.round(cssH * dpr);
  canvas.style.width = cssW + "px";
  canvas.style.height = cssH + "px";
  const ctx = canvas.getContext("2d");
  ctx.scale(dpr, dpr);
  ctx.beginPath();
  ctx.arc(150, 75, 40, 0, Math.PI * 2);
  ctx.fillStyle = "#0f766e";
  ctx.fill();
</script>
```

### Accessible chart pattern [#accessible-chart-pattern]

```html
<figure>
  <canvas id="sales" width="480" height="240"
    role="img"
    aria-labelledby="sales-caption"
    aria-describedby="sales-desc"></canvas>
  <figcaption id="sales-caption">Q1–Q4 revenue</figcaption>
  <p id="sales-desc" class="visually-hidden">
    Q1 40k, Q2 55k, Q3 48k, Q4 70k. Peak in Q4.
  </p>
  <table class="visually-hidden">
    <caption>Same data as the chart</caption>
    <thead><tr><th>Quarter</th><th>Revenue</th></tr></thead>
    <tbody>
      <tr><td>Q1</td><td>40000</td></tr>
      <tr><td>Q2</td><td>55000</td></tr>
    </tbody>
  </table>
</figure>
```

### Animation loop sketch [#animation-loop-sketch]

```html
<canvas id="anim" width="320" height="180" aria-hidden="true"></canvas>
<script>
  const c = document.getElementById("anim");
  const ctx = c.getContext("2d");
  let x = 0;
  function frame(t) {
    ctx.clearRect(0, 0, c.width, c.height);
    ctx.fillRect(x % 320, 80, 40, 40);
    x += 2;
    requestAnimationFrame(frame);
  }
  requestAnimationFrame(frame);
</script>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **CSS size ≠ bitmap size** — Stretching a 300×150 canvas to full viewport without resetting `width`/`height` causes blurry drawing and wrong mouse coordinates.
* **Forgotten `clearRect`** — Animation trails accumulate unless you clear or redraw the full frame.
* **Security / tainted canvas** — Cross-origin images without CORS taint the canvas; `toDataURL` / `getImageData` then throw.
* **No built-in a11y** — Screen readers ignore drawn text; always provide a text alternative or live DOM summary.
* **Memory** — Large canvases (especially × DPR) are expensive; dispose contexts and avoid unbounded offscreen buffers.
* **`getContext` once** — Calling with a different type after the first successful call returns `null`.

## 🔗 Related [#-related]

* [Media](/docs/html/media) — `<img>`, `<video>`, `<audio>` as drawable sources
* [Script](/docs/html/script) — loading drawing code
* [Style](/docs/html/style) — CSS sizing vs canvas attributes
* [Div](/docs/html/div) — layout wrappers around canvas
* [Section](/docs/html/section) — structuring figure/chart regions
* [URL](/docs/html/url) — blob/object URLs for exports


# Data Attributes (/docs/html/data-attributes)



# Data Attributes [#data-attributes]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`data-*` attributes store custom private data on HTML elements. Access them via `getAttribute`/`setAttribute` or the `element.dataset` map (camelCase). Prefer data attributes for hooks and progressive enhancement state — not for CSS-critical styling when a class or ARIA state fits better.

## 🔧 Core concepts [#-core-concepts]

* **HTML**: `data-user-id="42"` → `el.dataset.userId`.
* **Naming**: only lowercase letters, digits, hyphens in the attribute; multi-word becomes camelCase in `dataset`.
* **Values**: always strings — parse numbers/JSON yourself.
* **Presence**: `data-open` without value → `dataset.open === ""` (truthy string).
* **CSS**: attribute selectors `[data-state="on"]` or `.x[data-active]`.
* **Not for**: accessible names/roles — use ARIA/semantics.

```html
<button type="button" data-action="add" data-product-id="123">Add</button>
<script>
  btn.addEventListener("click", () => {
    cart.add(Number(btn.dataset.productId));
  });
</script>
```

## 💡 Examples [#-examples]

```html
<div
  id="chart"
  data-endpoint="/api/stats"
  data-refresh-ms="30000"
  data-theme="dark"
></div>

<script>
  const el = document.getElementById("chart");
  const url = el.dataset.endpoint;
  const ms = Number(el.dataset.refreshMs);
  el.dataset.theme = "light"; // sets data-theme="light"
  delete el.dataset.theme; // removes attribute
</script>

<!-- CSS hooks -->
<style>
  .tab[data-active] {
    font-weight: 700;
  }
  .toast[data-variant="danger"] {
    border-color: crimson;
  }
</style>

<!-- JSON in data (keep small) -->
<div data-config='{"lang":"en","n":3}'></div>
<script>
  const cfg = JSON.parse(el.dataset.config);
</script>
```

```html
<!-- Validation: data-userId is invalid — use data-user-id -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* `dataset` values are strings — `"false"` is truthy; compare explicitly or use presence toggles carefully.
* Large JSON in attributes bloats HTML and XSS surface — prefer `<script type="application/json">` or fetch.
* Don’t put secrets in `data-*` — visible in DOM.
* Mixing `data-id` with real `id` confuses mental models — name clearly.
* CSS-only state often better as classes; a11y state better as ARIA.

## 🔗 Related [#-related]

* [aria.md](/docs/html/aria) — accessibility state
* [../Javascript/DOM/attributes.md](/docs/html/../javascript/dom/attributes) — attribute APIs
* [button.md](/docs/html/button) — action hooks
* [semantic.md](/docs/html/semantic) — prefer semantics first
* [../CSS/selectors.md](/docs/html/../css/selectors) — attribute selectors


# Details & Summary (/docs/html/details-summary)



# Details & Summary [#details--summary]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`<details>` creates a disclosure widget; `<summary>` is the visible toggle label. Native, keyboard-accessible expand/collapse without JS. Use for FAQs, optional advanced settings, and progressive disclosure. The `open` attribute controls expanded state.

## 🔧 Core concepts [#-core-concepts]

* **Structure**: `<details>` wraps `<summary>` plus any content.
* **`open`**: present when expanded; toggle via UI or JS property `details.open`.
* **Events**: `toggle` fires after open state changes.
* **Name grouping**: `name` attribute on multiple details makes an exclusive accordion (modern browsers).
* **Styling**: limited marker styling via `::marker` / `summary::-webkit-details-marker`.
* Only one summary per details.

```html
<details>
  <summary>Shipping times</summary>
  <p>Orders ship in 2–3 business days.</p>
</details>
```

## 💡 Examples [#-examples]

```html
<!-- FAQ -->
<details>
  <summary>What is your refund policy?</summary>
  <p>Full refunds within 30 days.</p>
</details>

<!-- Open by default -->
<details open>
  <summary>Release notes</summary>
  <ul>
    <li>Bug fixes</li>
  </ul>
</details>

<!-- Accordion via name -->
<details name="faq">
  <summary>A</summary>
  <p>...</p>
</details>
<details name="faq">
  <summary>B</summary>
  <p>...</p>
</details>

<!-- Styled -->
<style>
  details {
    border: 1px solid #ddd;
    padding: 0.5rem 0.75rem;
  }
  summary {
    cursor: pointer;
    font-weight: 600;
  }
  details[open] summary {
    margin-bottom: 0.5rem;
  }
</style>

<script>
  document.querySelector("details").addEventListener("toggle", (e) => {
    console.log(e.target.open);
  });
</script>
```

```html
<!-- summary can contain heading -->
<details>
  <summary><h3>Advanced</h3></summary>
  ...
</details>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don’t put interactive content that fights the summary click target poorly — keep summary clear.
* Search engines / AT support is good but content in closed details may be less discoverable visually — don’t hide critical legal text only there without care.
* Exclusive `name` accordion support is newer — test targets.
* Animating open height still needs CSS tricks; `open` is discrete.
* Missing `summary` yields UA default “Details” label — always provide one.

## 🔗 Related [#-related]

* [semantic.md](/docs/html/semantic) — structure
* [accessibility.md](/docs/html/accessibility) — disclosures
* [dialog.md](/docs/html/dialog) — modals vs disclosures
* [button.md](/docs/html/button) — custom toggles
* [../CSS/pseudo\_elements.md](/docs/html/../css/pseudo-elements) — markers


# Dialog (/docs/html/dialog)



# Dialog [#dialog]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<dialog>` element provides native modal and non-modal dialogs with built-in focus management, backdrop, and Esc handling (for modal). Prefer it over custom `div` modals. Use `showModal()` for modals and `show()` for non-modals; `close()` or form `method="dialog"` to dismiss.

## 🔧 Core concepts [#-core-concepts]

* **API**: `show()`, `showModal()`, `close(returnValue?)`, `open` property, `returnValue`.
* **Events**: `close`, `cancel` (Esc).
* **Backdrop**: `::backdrop` pseudo-element when modal.
* **Forms**: `<form method="dialog">` closes and sets `returnValue` from submitter.
* **Light dismiss**: click backdrop doesn’t close by default — listen if desired.
* **Top layer**: modal dialogs render in the top layer above `z-index` wars.

```html
<dialog id="confirm">
  <form method="dialog">
    <p>Delete item?</p>
    <button value="cancel">Cancel</button>
    <button value="ok">Delete</button>
  </form>
</dialog>
<script>
  const d = document.getElementById("confirm");
  openBtn.onclick = () => d.showModal();
  d.addEventListener("close", () => console.log(d.returnValue));
</script>
```

## 💡 Examples [#-examples]

```html
<dialog id="dlg" aria-labelledby="dlg-title">
  <header>
    <h2 id="dlg-title">Settings</h2>
    <button type="button" class="close" aria-label="Close">&times;</button>
  </header>
  <form id="settings">...</form>
  <menu>
    <button type="button" class="close">Close</button>
    <button type="submit" form="settings">Save</button>
  </menu>
</dialog>

<style>
  dialog::backdrop {
    background: rgb(0 0 0 / 0.45);
  }
  dialog[open] {
    border: 0;
    border-radius: 12px;
    padding: 1.25rem;
  }
</style>

<script>
  const dlg = document.getElementById("dlg");
  dlg.querySelectorAll(".close").forEach((b) =>
    b.addEventListener("click", () => dlg.close()),
  );
  // Optional: light dismiss
  dlg.addEventListener("click", (e) => {
    const rect = dlg.getBoundingClientRect();
    const inDialog =
      rect.top <= e.clientY &&
      e.clientY <= rect.top + rect.height &&
      rect.left <= e.clientX &&
      e.clientX <= rect.left + rect.width;
    if (!inDialog) dlg.close();
  });
</script>
```

## ⚠️ Pitfalls [#️-pitfalls]

* `open` attribute shows non-modal; prefer `showModal()` for true modals.
* Don’t forget an initial focusable control and a clear close action.
* Nested dialogs are tricky — avoid when possible.
* Polyfills still needed for very old browsers — know your baseline.
* Removing `open` via JS isn’t the same as `close()` for return values/events.

## 🔗 Related [#-related]

* [accessibility.md](/docs/html/accessibility) — modal a11y
* [button.md](/docs/html/button) — triggers
* [form.md](/docs/html/form) — method=dialog
* [../Javascript/DOM/focus\_blur.md](/docs/html/../javascript/dom/focus-blur) — focus restore
* [../CSS/pseudo\_elements.md](/docs/html/../css/pseudo-elements) — ::backdrop


# Div (/docs/html/div)



# Div [#div]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<div>` element is a generic **flow content** container with no semantic meaning. It groups elements for styling, scripting, or layout when no more specific HTML element fits. Overusing `<div>` (div soup) harms accessibility and maintainability—prefer landmarks and sectioning elements first.

Use `<div>` when you need a box without implying article, navigation, complementary, or other roles. Pair with classes, IDs, and ARIA only when semantics cannot be expressed natively.

## 🔧 Core concepts [#-core-concepts]

### Default behavior [#default-behavior]

* Display: `block` (full width of containing block).
* No default margins (unlike headings/paragraphs).
* Valid almost anywhere flow content is allowed; may contain flow content.
* Does **not** create a landmark or outline entry by itself.

### Prefer semantic alternatives [#prefer-semantic-alternatives]

| Instead of…                 | Prefer…     |
| --------------------------- | ----------- |
| Page header block           | `<header>`  |
| Main content wrapper        | `<main>`    |
| Sidebar                     | `<aside>`   |
| Site/footer chrome          | `<footer>`  |
| Primary nav                 | `<nav>`     |
| Standalone story            | `<article>` |
| Thematic group with heading | `<section>` |
| Inline grouping             | `<span>`    |

### Legitimate uses [#legitimate-uses]

* CSS Grid / Flexbox layout shells
* Script hooks (`id`, `data-*`) without implying meaning
* Presentational wrappers required by a design system
* Grouping for `display: contents` or sticky positioning contexts

### ARIA on divs [#aria-on-divs]

If a `<div>` must act as a widget, add the correct `role`, keyboard support, and labels (`aria-label` / `aria-labelledby`). Prefer native elements (`button`, `a`, `input`) over `role="button"` on a div.

```html
<!-- Avoid when a button works -->
<div role="button" tabindex="0">Save</div>

<!-- Prefer -->
<button type="button">Save</button>
```

## 💡 Examples [#-examples]

### Layout shell (after semantics) [#layout-shell-after-semantics]

```html
<body>
  <header>…</header>
  <div class="layout">
    <main id="content">…</main>
    <aside>…</aside>
  </div>
  <footer>…</footer>
</body>
```

### Flex / grid wrapper [#flex--grid-wrapper]

```html
<div class="card-grid">
  <article class="card">…</article>
  <article class="card">…</article>
  <article class="card">…</article>
</div>
```

```css
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(16rem, 1fr));
  gap: 1rem;
}
```

### Script target without fake semantics [#script-target-without-fake-semantics]

```html
<div id="toast-root" aria-live="polite" aria-atomic="true"></div>
```

### Dialog pattern (prefer `<dialog>` when possible) [#dialog-pattern-prefer-dialog-when-possible]

```html
<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dlg-title"
  hidden>
  <h2 id="dlg-title">Confirm delete</h2>
  <p>This cannot be undone.</p>
  <button type="button">Cancel</button>
  <button type="button">Delete</button>
</div>
```

Native `<dialog>` with `.showModal()` is usually better for focus trapping and `Escape`.

## ⚠️ Pitfalls [#️-pitfalls]

* **Div soup** — Nested anonymous divs make outlines and CSS brittle; name regions with real tags.
* **Clickable divs** — Missing `tabindex`, Enter/Space handlers, and roles break keyboard and AT users.
* **`div` for text** — Use `<p>`, lists, or headings for prose; divs do not convey paragraph structure.
* **Landmark overload** — Do not put `role="main"` on every wrapper; one `<main>` per page.
* **`display: contents`** — Can remove the box from a11y trees in some browsers; test carefully.
* **Styling only** — If the only reason is “I need a class,” check whether a semantic parent already exists.

## 🔗 Related [#-related]

* [Section](/docs/html/section) — thematic grouping with headings
* [Nav](/docs/html/nav) — navigation landmark
* [Footer](/docs/html/footer) — footer / contentinfo
* [Form](/docs/html/form) — form layout containers
* [Style](/docs/html/style) — styling hooks
* [Canvas](/docs/html/canvas) — wrapping drawing surfaces
* [Language](/docs/html/language) — `lang` on containers


# Elements Basics (/docs/html/elements-basics)



# Elements Basics [#elements-basics]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

An **element** is a node in the page tree, usually written with an opening tag, content, and a closing tag. Some elements are **void** (no closing tag), like `img` and `br`.

## 🔧 Core concepts [#-core-concepts]

| Kind       | Examples                           | Notes                                          |
| ---------- | ---------------------------------- | ---------------------------------------------- |
| Block-ish  | `h1`–`h6`, `p`, `ul`, `section`    | Start on a new line by default (CSS dependent) |
| Inline-ish | `a`, `strong`, `em`, `span`        | Flow within text                               |
| Void       | `img`, `br`, `hr`, `input`, `meta` | No child content                               |
| Semantic   | `header`, `main`, `nav`, `footer`  | Meaning for humans & assistive tech            |

Elements nest to form a tree; the browser builds the DOM from that tree.

## 💡 Examples [#-examples]

**Headings and text:**

```html
<h1>Site title</h1>
<h2>Section</h2>
<p>A paragraph of text with <strong>bold</strong> and <em>emphasis</em>.</p>
```

**Lists:**

```html
<ul>
  <li>Apples</li>
  <li>Bananas</li>
</ul>
<ol>
  <li>Install editor</li>
  <li>Write HTML</li>
</ol>
```

**Void elements:**

```html
<p>Line one<br />Line two</p>
<hr />
<img src="cat.jpg" alt="A cat sitting on a laptop" />
```

**Document landmarks:**

```html
<body>
  <header><h1>Notes</h1></header>
  <main>
    <article>
      <h2>Elements</h2>
      <p>Content goes here.</p>
    </article>
  </main>
  <footer><p>© 2026</p></footer>
</body>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Overusing `<div>` when a semantic tag fits better.
* Putting block elements inside `<p>` incorrectly.
* Self-closing `/>` is optional in HTML5 for void tags but fine to use.
* Tag names are case-insensitive; lowercase is the convention.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/html/getting-started)
* [hello\_world.md](/docs/html/hello-world)
* [attributes\_basics.md](/docs/html/attributes-basics)
* [semantic.md](/docs/html/semantic)


# Embedding (/docs/html/embedding)



# Embedding [#embedding]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

HTML offers several ways to embed external or nested content: `<iframe>`, `<embed>`, `<object>`, and media elements. Prefer modern, specific elements (`iframe` for documents, `video`/`audio`/`img` for media). Treat embeds as a security and performance boundary — sandbox and size them deliberately.

## 🔧 Core concepts [#-core-concepts]

| Element           | Typical use                                          |
| ----------------- | ---------------------------------------------------- |
| `iframe`          | HTML documents, apps, maps, PDFs (browser-dependent) |
| `embed`           | Plugin-like resources (PDF/legacy); limited API      |
| `object`          | Fallback-capable embed with nested content           |
| `img` / `picture` | images                                               |
| `video` / `audio` | media                                                |
| `fencedframe`     | privacy-bounded ads (emerging)                       |

* **Fallback**: nested content inside `<object>` shows if embedding fails.
* **Security**: `sandbox`, CSP `frame-src`, Permissions Policy `allow`.
* **A11y**: provide `title` / text fallback links.

```html
<iframe title="Terms PDF" src="/terms.pdf" width="100%" height="600"></iframe>

<object data="/diagram.svg" type="image/svg+xml" role="img" aria-label="Architecture diagram">
  <p><a href="/diagram.svg">Download diagram</a></p>
</object>
```

## 💡 Examples [#-examples]

```html
<!-- object with fallback -->
<object data="/poster.pdf" type="application/pdf" width="800" height="600">
  <p>PDF unavailable. <a href="/poster.pdf">Download</a>.</p>
</object>

<!-- embed (simple) -->
<embed src="/clip.swf" />
<!-- prefer video nowadays -->

<!-- Responsive iframe -->
<div style="aspect-ratio: 16 / 9">
  <iframe
    title="Demo"
    src="/embed/demo"
    style="width: 100%; height: 100%; border: 0"
    loading="lazy"
    sandbox="allow-scripts allow-same-origin"
  ></iframe>
</div>

<!-- Inline SVG often better than object for icons -->
```

```html
<!-- Prefer -->
<video src="/a.mp4" controls></video>
<!-- Over generic embed for video -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* `embed`/`object` for video/audio are outdated — use dedicated media elements.
* Combining `sandbox` tokens `allow-scripts` + `allow-same-origin` can allow sandbox escape.
* PDFs in iframes vary by browser/OS — always offer a download link.
* Each embed costs memory/threads — lazy-load offscreen content.
* Accessibility: unlabeled frames fail audits — set `title`.

## 🔗 Related [#-related]

* [iframe.md](/docs/html/iframe) — iframe deep dive
* [video\_audio.md](/docs/html/video-audio) — media elements
* [images.md](/docs/html/images) — images
* [svg\_inline.md](/docs/html/svg-inline) — inline SVG
* [accessibility.md](/docs/html/accessibility) — titles/fallbacks


# Footer (/docs/html/footer)



# Footer [#footer]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<footer>` element represents a footer for its nearest ancestor **sectioning content** or **sectioning root** (`article`, `aside`, `nav`, `section`, `blockquote`, `body`, `fieldset`, `figure`, `td`). Typical content: authorship, copyright, related links, or document metadata.

A footer is **not** limited to the bottom of the page. Nested footers belong to nested sections (e.g. an article’s byline). When `<footer>` is a direct descendant of `<body>`, browsers expose it as a `contentinfo` landmark—use **one** page-level footer for site-wide info.

## 🔧 Core concepts [#-core-concepts]

### Sectioning relationship [#sectioning-relationship]

```html
<body>
  <main>
    <article>
      <h1>Title</h1>
      <p>…</p>
      <footer>Posted by Ada · 2026-07-10</footer>
    </article>
  </main>
  <footer>
    <p>© 2026 Example Co.</p>
    <nav aria-label="Legal">…</nav>
  </footer>
</body>
```

* Article footer → scoped to that article (not `contentinfo`).
* Body footer → site `contentinfo` landmark.

### Allowed content [#allowed-content]

Flow content, but **no** nested `<footer>` or `<header>` descendants that would confuse sectioning. Contact info often uses `<address>` inside the footer for the document or article contact.

### Accessibility [#accessibility]

* Page footer: landmark `contentinfo` (implicit).
* Do not duplicate with `role="contentinfo"` on another element.
* Label multiple navs inside the footer (`aria-label="Legal"`, `aria-label="Social"`).
* Keep landmark count low—avoid wrapping every widget in its own footer.

### Common patterns [#common-patterns]

| Pattern        | Contents                     |
| -------------- | ---------------------------- |
| Site chrome    | Logo, legal, sitemap, social |
| Article        | Author, dates, tags, share   |
| Card / section | Secondary actions, meta      |

## 💡 Examples [#-examples]

### Site-wide footer [#site-wide-footer]

```html
<footer>
  <p>
    <small>© <time datetime="2026">2026</time> Acme Inc.</small>
  </p>
  <nav aria-label="Legal">
    <ul>
      <li><a href="/privacy">Privacy</a></li>
      <li><a href="/terms">Terms</a></li>
    </ul>
  </nav>
  <address>
    Contact: <a href="mailto:hello@acme.example">hello@acme.example</a>
  </address>
</footer>
```

### Article footer [#article-footer]

```html
<article>
  <header>
    <h2>Semantic footers</h2>
    <p><time datetime="2026-07-10">July 10, 2026</time></p>
  </header>
  <p>Body copy…</p>
  <footer>
    <p>By <a rel="author" href="/authors/ada">Ada</a></p>
    <ul>
      <li><a href="/tags/html">HTML</a></li>
      <li><a href="/tags/a11y">a11y</a></li>
    </ul>
  </footer>
</article>
```

### Footer with secondary navigation [#footer-with-secondary-navigation]

```html
<footer class="site-footer">
  <nav aria-label="Footer">
    <a href="/docs">Docs</a>
    <a href="/status">Status</a>
    <a href="/support">Support</a>
  </nav>
  <p lang="en">Built with semantic HTML.</p>
</footer>
```

### Figure / media credit [#figure--media-credit]

```html
<figure>
  <img src="/photo.jpg" alt="Harbor at dawn">
  <figcaption>Morning light over the harbor.</figcaption>
  <footer><small>Photo © Jordan Lee</small></footer>
</figure>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Multiple `contentinfo` landmarks** — Extra body-level footers or redundant `role="contentinfo"` confuse navigation shortcuts.
* **Footer as layout only** — Do not use `<footer>` merely to stick content to the bottom; use CSS on a non-landmark wrapper if it is not footer content.
* **Nested header/footer rules** — Avoid putting `<header>` inside `<footer>` and vice versa in ways that break the outline.
* **Missing labels on inner nav** — Several unlabeled `<nav>` elements in a footer are hard to distinguish.
* **Copyright-only div** — A bare `<div class="footer">` loses the landmark; use the real element when appropriate.
* **Forms in footers** — Newsletter forms are fine; ensure labels, `autocomplete`, and error messaging still meet a11y standards.

## 🔗 Related [#-related]

* [Nav](/docs/html/nav) — footer link groups
* [Section](/docs/html/section) — sectioning ancestors
* [Div](/docs/html/div) — non-semantic layout
* [Form](/docs/html/form) — newsletter signup patterns
* [Meta](/docs/html/meta) — document-level metadata (not a substitute for visible footer)
* [Language](/docs/html/language) — `lang` on footer snippets


# Forms (/docs/html/form)



# Forms [#forms]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<form>` element represents a document section that collects user input and submits it to a server or handles it with script. Native forms give you validation, keyboard behavior, autofill, and accessibility for free—prefer them over custom div-based “forms.”

A form owns **associated controls**: descendants plus elements linked via the `form="id"` attribute. Submission builds a payload from **successful controls** (named, enabled, and meeting type rules).

## 🔧 Core concepts [#-core-concepts]

### Essential attributes [#essential-attributes]

| Attribute      | Role                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------ |
| `action`       | URL that receives the submission (defaults to current URL)                                 |
| `method`       | `get` (query string) or `post` (body); `dialog` closes a `<dialog>`                        |
| `enctype`      | `application/x-www-form-urlencoded` (default), `multipart/form-data` (files), `text/plain` |
| `novalidate`   | Skip built-in constraint validation on submit                                              |
| `autocomplete` | `on` / `off` for the form; controls can override                                           |
| `name`         | Identifies the form in `document.forms`                                                    |
| `target`       | Browsing context for response (`_blank`, iframe name, …)                                   |
| `rel`          | Link types for the submission request                                                      |

### Association and structure [#association-and-structure]

```html
<form id="signup" action="/api/signup" method="post" autocomplete="on">
  <fieldset>
    <legend>Account</legend>
    <label for="email">Email</label>
    <input id="email" name="email" type="email" required autocomplete="email">
  </fieldset>
  <button type="submit">Create account</button>
</form>
```

* Every control needs an accessible **name** (`<label for>`, wrapping label, or `aria-label`).
* Use `<fieldset>` / `<legend>` for related groups (radios, address blocks).
* `button` without `type` inside a form defaults to `submit`—set `type="button"` for non-submit actions.

### Constraint validation [#constraint-validation]

Built-in checks: `required`, `min`/`max`, `minlength`/`maxlength`, `pattern`, `type` (email, url, …), `step`. APIs: `checkValidity()`, `reportValidity()`, `setCustomValidity()`.

Listen to `invalid` and `submit`; call `event.preventDefault()` when handling with `fetch`.

### GET vs POST [#get-vs-post]

* **GET** — bookmarkable, idempotent filters/search; do not send secrets.
* **POST** — mutations, passwords, large bodies, file uploads (`multipart/form-data`).

## 💡 Examples [#-examples]

### Accessible login form [#accessible-login-form]

```html
<form action="/login" method="post">
  <div>
    <label for="user">Username</label>
    <input id="user" name="username" required
      autocomplete="username" autocapitalize="none">
  </div>
  <div>
    <label for="pass">Password</label>
    <input id="pass" name="password" type="password" required
      autocomplete="current-password">
  </div>
  <button type="submit">Sign in</button>
</form>
```

### File upload [#file-upload]

```html
<form action="/upload" method="post" enctype="multipart/form-data">
  <label for="avatar">Profile photo</label>
  <input id="avatar" name="avatar" type="file" accept="image/*">
  <button type="submit">Upload</button>
</form>
```

### External control with `form` attribute [#external-control-with-form-attribute]

```html
<form id="filters" method="get" action="/search"></form>

<label for="q">Query</label>
<input form="filters" id="q" name="q" type="search">

<button form="filters" type="submit">Search</button>
```

### Client-side submit with validation [#client-side-submit-with-validation]

```html
<form id="contact" action="/contact" method="post" novalidate>
  <label for="msg">Message</label>
  <textarea id="msg" name="message" required minlength="10"></textarea>
  <button type="submit">Send</button>
</form>
<script>
  document.getElementById("contact").addEventListener("submit", async (e) => {
    e.preventDefault();
    const form = e.target;
    if (!form.reportValidity()) return;
    const body = new FormData(form);
    await fetch(form.action, { method: "POST", body });
  });
</script>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Missing labels** — Placeholder is not a label; AT and click-to-focus suffer.
* **Unnamed controls** — Without `name`, values are omitted from submission.
* **Disabling validation silently** — `novalidate` without custom checks ships bad data.
* **CSRF** — Browser POSTs need server tokens/SameSite cookies; HTML alone is not enough.
* **Nested forms** — Invalid HTML; browsers repair unpredictably.
* **`div` buttons** — Lose default submit-on-Enter behavior in text fields.
* **Autofill ignored** — Wrong `autocomplete` tokens break password managers.

## 🔗 Related [#-related]

* [Input](/docs/html/input) — control types and attributes
* [Label / lists](/docs/html/list) — structuring options (see also fieldset patterns here)
* [Script](/docs/html/script) — progressive enhancement of submit handlers
* [URL](/docs/html/url) — `action` URLs and query strings
* [Meta](/docs/html/meta) — CSRF tokens sometimes injected via meta + JS
* [Nav](/docs/html/nav) — do not confuse search forms with navigation landmarks
* [Footer](/docs/html/footer) — newsletter forms in footers


# Getting Started with HTML (/docs/html/getting-started)



# Getting Started with HTML [#getting-started-with-html]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

HTML (HyperText Markup Language) describes the **structure** of a web page: headings, paragraphs, links, images, forms. Browsers parse HTML into the DOM. CSS styles it; JavaScript makes it interactive.

## 🔧 Core concepts [#-core-concepts]

| Idea      | Meaning                                        |
| --------- | ---------------------------------------------- |
| Element   | A piece of structure: `<p>text&lt;/p>`         |
| Tag       | The `<p>` / `&lt;/p>` markers                  |
| Attribute | Extra info on a tag: `href`, `src`, `alt`      |
| Document  | A full page starting with `&lt;!DOCTYPE html>` |
| Nesting   | Elements inside elements form a tree           |

Files use the `.html` extension. Double-click or serve them locally to view in a browser.

## 💡 Examples [#-examples]

**Minimal page:**

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My first page</title>
  </head>
  <body>
    <h1>Hello, HTML</h1>
    <p>This is a paragraph.</p>
  </body>
</html>
```

**Save as `index.html` and open in a browser.**

**Common early tags:**

```html
<h1>Title</h1>
<p>Paragraph with a <a href="https://example.com">link</a>.</p>
<img src="photo.jpg" alt="A descriptive alt text" width="300" />
<ul>
  <li>One</li>
  <li>Two</li>
</ul>
```

**Validate structure mentally:** open tags should close (except void elements like `<img>`).

## ⚠️ Pitfalls [#️-pitfalls]

* Skipping `alt` on images hurts accessibility.
* Invalid nesting (`<p><div>&lt;/div>&lt;/p>`) confuses browsers.
* Viewing via `file://` is fine for basics; some APIs need a local server.
* HTML is not a programming language — logic lives in JavaScript.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/html/hello-world)
* [elements\_basics.md](/docs/html/elements-basics)
* [attributes\_basics.md](/docs/html/attributes-basics)
* [semantic.md](/docs/html/semantic)


# Glossary (/docs/html/glossary)



# Glossary [#glossary]

*Html · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core HTML terms for document structure, semantics, forms, media, and accessibility.

## 🔧 Core concepts [#-core-concepts]

| Term           | Definition                                                                   |
| -------------- | ---------------------------------------------------------------------------- |
| Accessibility  | Designing markup so assistive technologies can perceive and operate content. |
| Anchor         | An `<a>` element that creates a hyperlink to a URL or page fragment.         |
| ARIA           | Attributes that expose roles, states, and properties to assistive tech.      |
| Attribute      | A name/value pair on a start tag that configures an element.                 |
| Block element  | An element that typically starts on a new line and fills available width.    |
| Body           | The `<body>` element containing visible page content.                        |
| Canvas         | An `<canvas>` element providing a drawing surface via JavaScript.            |
| Doctype        | The `&lt;!DOCTYPE html>` declaration that puts browsers in standards mode.   |
| Document       | The full HTML tree rooted at `<html>` and represented as the DOM.            |
| DOM            | The in-memory tree of nodes browsers build from HTML.                        |
| Element        | A node created by a start tag, optional content, and an end tag.             |
| Form           | An `<form>` that collects controls and submits data to a server or script.   |
| Head           | The `<head>` section for metadata, links, scripts, and title.                |
| Heading        | Ranked titles `<h1>`–`<h6>` that outline document structure.                 |
| Iframe         | An `<iframe>` that embeds another browsing context/document.                 |
| Inline element | An element that flows within text without forcing a new line.                |
| Input          | A form control (`<input>`) whose behavior depends on its `type`.             |
| Landmark       | A region role such as `nav`, `main`, or `aside` for page navigation.         |
| Meta           | Metadata elements describing charset, viewport, SEO, and more.               |
| Semantic HTML  | Using elements whose meaning matches content, not just presentation.         |
| Slot           | A placeholder in a shadow tree filled by light-DOM children.                 |
| SVG            | Scalable vector graphics markup embeddable in HTML.                          |
| Table          | Markup (`<table>`, `<tr>`, `<th>`, `<td>`) for tabular data.                 |
| Template       | An inert `<template>` whose content can be cloned into the document.         |
| Void element   | An element that cannot have children, such as `<img>` or `<br>`.             |
| Web component  | Custom elements, shadow DOM, and templates used as reusable widgets.         |

## 💡 Examples [#-examples]

**Semantic landmarks:**

```html
<header>
  <nav aria-label="Primary">
    <a href="/">Home</a>
  </nav>
</header>
<main>
  <h1>Docs</h1>
  <article>...</article>
</main>
```

**Form controls:**

```html
<form action="/signup" method="post">
  <label>
    Email
    <input type="email" name="email" required />
  </label>
  <button type="submit">Join</button>
</form>
```

**Picture and responsive images:**

```html
<picture>
  <source srcset="hero.avif" type="image/avif" />
  <img src="hero.jpg" alt="Product hero" width="1200" height="600" />
</picture>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing &#x2A;*`<div>`** (generic box) with **semantic** elements like `<section>` or `<article>`.
* Mixing **block** and **inline** mental models with modern CSS `display` — HTML defaults are only defaults.
* Using **ARIA** to “fix” bad markup instead of preferring native semantics.
* Treating &#x2A;*`<iframe>`** like a simple include — it is a separate document with security boundaries.
* Equating &#x2A;*`<template>`** content with live DOM — it stays inert until cloned.

## 🔗 Related [#-related]

* [semantic](/docs/html/semantic)
* [form](/docs/html/form)
* [accessibility](/docs/html/accessibility)
* [aria](/docs/html/aria)
* [meta](/docs/html/meta)
* [web\_components](/docs/html/web-components)


# Head (/docs/html/head)



# Head [#head]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<head>` element holds **document metadata**—information about the page that is mostly not rendered as page content. Typical children: `<title>`, `<meta>`, `<link>`, `<style>`, `<script>`, and `<base>`. Browsers, crawlers, and social platforms read the head to configure charset, viewport, SEO, icons, and resource loading.

There must be exactly one `<head>` per document, as a child of `<html>`, before `<body>`. Visible UI belongs in `<body>`; the head configures how that body is interpreted and presented.

## 🔧 Core concepts [#-core-concepts]

### Minimal document [#minimal-document]

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Page title</title>
  <link rel="stylesheet" href="/styles.css">
</head>
<body>…</body>
</html>
```

### Key children [#key-children]

| Element      | Purpose                                                             |
| ------------ | ------------------------------------------------------------------- |
| `<title>`    | Document title (tabs, bookmarks, SERP); **required** for valid HTML |
| `<meta>`     | Charset, viewport, description, Open Graph, robots, etc.            |
| `<link>`     | Stylesheets, icons, preconnect, canonical, alternate                |
| `<style>`    | Document-level CSS                                                  |
| `<script>`   | JS (prefer `defer` / module in head)                                |
| `<base>`     | Base URL for relative links (use sparingly—global side effects)     |
| `<noscript>` | Fallback when scripting is off (also allowed in body)               |

### Order matters [#order-matters]

1. **Charset** early (`<meta charset="utf-8">` within first 1024 bytes).
2. **Viewport** for responsive mobile layout.
3. **Title** and descriptive meta.
4. **Preconnect / preload** hints before heavy assets.
5. **CSS** (blocking by default—critical CSS strategies apply).
6. **Scripts** with `defer` or `type="module"` so parsing is not blocked unnecessarily.

### Title guidelines [#title-guidelines]

* Unique per page, human-readable, \~50–60 characters for SERPs.
* Put distinctive info first: `Pricing — Acme` not `Acme — Pricing` if tabs truncate.
* Do not stuff keywords; match the primary `<h1>` topic.

## 💡 Examples [#-examples]

### SEO and social basics [#seo-and-social-basics]

```html
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Canvas API — HTML Reference</title>
  <meta name="description" content="Cheat sheet for the HTML canvas element and drawing API.">
  <link rel="canonical" href="https://example.com/html/canvas">
  <meta property="og:title" content="Canvas API — HTML Reference">
  <meta property="og:type" content="article">
  <meta property="og:url" content="https://example.com/html/canvas">
  <meta property="og:image" content="https://example.com/og/canvas.png">
</head>
```

### Performance hints [#performance-hints]

```html
<head>
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://cdn.example.com" crossorigin>
  <link rel="preload" href="/fonts/Inter.woff2" as="font" type="font/woff2" crossorigin>
  <link rel="stylesheet" href="/app.css">
  <script src="/app.js" defer></script>
</head>
```

### Icons and theme [#icons-and-theme]

```html
<head>
  <link rel="icon" href="/favicon.ico" sizes="any">
  <link rel="icon" href="/icon.svg" type="image/svg+xml">
  <link rel="apple-touch-icon" href="/apple-touch-icon.png">
  <meta name="theme-color" content="#0f766e">
  <link rel="manifest" href="/manifest.webmanifest">
</head>
```

### Alternate languages [#alternate-languages]

```html
<head>
  <link rel="alternate" hreflang="en" href="https://example.com/en/docs">
  <link rel="alternate" hreflang="es" href="https://example.com/es/docs">
  <link rel="alternate" hreflang="x-default" href="https://example.com/docs">
</head>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Late charset** — Can cause mojibake; keep UTF-8 meta first.
* **Missing viewport** — Mobile browsers may zoom out to a desktop width.
* **Blocking scripts in head** — Without `defer`/`async`/module, parsing stalls.
* **Multiple titles** — Invalid; only one `<title>` should exist.
* **Secrets in head** — Meta tags are public; never put API keys there.
* **`<base>` surprises** — Changes every relative URL, including anchors and forms.
* **Duplicate canonicals** — Conflicting signals hurt SEO.

## 🔗 Related [#-related]

* [Meta](/docs/html/meta) — meta element details
* [Script](/docs/html/script) — loading JS from head or body
* [Style](/docs/html/style) — `<style>` and linked CSS
* [URL](/docs/html/url) — canonical and alternate URLs
* [Language](/docs/html/language) — `lang` on `<html>`, hreflang
* [XML](/docs/html/xml) — XHTML / polyglot considerations


# Hello World (/docs/html/hello-world)



# Hello World [#hello-world]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

An HTML Hello World is a complete minimal document that shows a heading or paragraph in the browser. It confirms your file is saved correctly and the browser can render markup.

## 🔧 Core concepts [#-core-concepts]

| Piece                | Role                                    |
| -------------------- | --------------------------------------- |
| `&lt;!DOCTYPE html>` | Tells the browser to use standards mode |
| `<html>`             | Root element                            |
| `<head>`             | Metadata (title, charset, CSS links)    |
| `<body>`             | Visible content                         |
| `<h1>` / `<p>`       | Heading and paragraph                   |

Always set `lang` on `<html>` and `charset` in `<head>`.

## 💡 Examples [#-examples]

**Classic hello page:**

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Hello</title>
  </head>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
```

**Hello with a paragraph and link:**

```html
<body>
  <h1>Hello, World!</h1>
  <p>Welcome to <strong>HTML</strong>.</p>
  <p><a href="https://developer.mozilla.org/">Learn more on MDN</a></p>
</body>
```

**Inline emphasis:**

```html
<p>Hello, <em>World</em>!</p>
```

**Comment in HTML:**

```html
<!-- This is not shown on the page -->
<p>Hello, World!</p>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Saving as `.txt` may open as plain text — use `.html`.
* Forgetting `&lt;/h1>` can make the rest of the page inherit heading styles.
* Using multiple `<h1>` without thought hurts document outline clarity.
* Fancy Word-processor HTML is messy — write markup in a code editor.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/html/getting-started)
* [elements\_basics.md](/docs/html/elements-basics)
* [attributes\_basics.md](/docs/html/attributes-basics)
* [links.md](/docs/html/links)


# iframe (/docs/html/iframe)



# iframe [#iframe]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`<iframe>` embeds another browsing context (page, PDF, map, video player). Powerful but costly for performance and security — sandbox aggressively, size explicitly, and prefer lighter embeds when possible. Use `title` for accessibility.

## 🔧 Core concepts [#-core-concepts]

| Attribute          | Role                                   |
| ------------------ | -------------------------------------- |
| `src`              | embedded URL                           |
| `srcdoc`           | inline HTML document                   |
| `title`            | accessible name (required in practice) |
| `width` / `height` | layout size                            |
| `allow`            | Permissions Policy features            |
| `sandbox`          | restrictions token list                |
| `loading`          | `lazy` / `eager`                       |
| `referrerpolicy`   | referrer sent to embed                 |
| `allowfullscreen`  | legacy; prefer `allow="fullscreen"`    |

* Cross-origin frames limit DOM access (same-origin policy).
* Communicate via `postMessage`.

```html
<iframe
  title="Map of office location"
  src="https://maps.example.com/embed?..."
  width="600"
  height="400"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allow="geolocation 'none'"
></iframe>
```

## 💡 Examples [#-examples]

```html
<!-- Sandboxed untrusted HTML -->
<iframe
  title="User preview"
  sandbox="allow-scripts"
  srcdoc="<p>Hello</p>"
></iframe>

<!-- Strict sandbox (no scripts/forms) -->
<iframe title="Static preview" sandbox src="/preview.html"></iframe>

<!-- YouTube-style -->
<iframe
  title="Product demo video"
  src="https://www.youtube-nocookie.com/embed/VIDEO_ID"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowfullscreen
  loading="lazy"
></iframe>

<!-- postMessage -->
<script>
  frame.contentWindow.postMessage({ type: "ping" }, "https://trusted.example");
  window.addEventListener("message", (e) => {
    if (e.origin !== "https://trusted.example") return;
    console.log(e.data);
  });
</script>
```

```html
<!-- Aspect ratio wrapper -->
<div class="frame" style="aspect-ratio:16/9">
  <iframe title="Demo" src="..." style="width:100%;height:100%;border:0"></iframe>
</div>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `sandbox` on untrusted content is dangerous (`allow-scripts` + `allow-same-origin` together can escape sandbox).
* Each iframe is expensive (memory/network) — lazy-load offscreen ones.
* Empty or missing `title` fails a11y checks.
* Assuming you can read `iframe.contentDocument` cross-origin throws.
* CSP `frame-src` / `child-src` may block embeds — coordinate headers.

## 🔗 Related [#-related]

* [embedding.md](/docs/html/embedding) — embed/object
* [video\_audio.md](/docs/html/video-audio) — native media
* [accessibility.md](/docs/html/accessibility) — titles
* [../Javascript/web\_workers.md](/docs/html/../javascript/web-workers) — other isolation
* [../CSS/aspect\_ratio.md](/docs/html/../css/aspect-ratio) — responsive frames


# Images (/docs/html/images)



# Images [#images]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<img>` element embeds images. Always provide meaningful `alt` (or empty `alt=""` for decorative). Use `width`/`height` or CSS aspect-ratio to reduce layout shift, and `srcset`/`sizes` for responsive resolution switching. For art direction, prefer `<picture>`.

## 🔧 Core concepts [#-core-concepts]

| Attribute          | Role                                          |
| ------------------ | --------------------------------------------- |
| `src`              | image URL                                     |
| `alt`              | text alternative                              |
| `width` / `height` | intrinsic layout hints                        |
| `srcset`           | candidate URLs with density/width descriptors |
| `sizes`            | layout width for `w` descriptors              |
| `loading`          | `lazy` / `eager`                              |
| `decoding`         | `async` / `sync` / `auto`                     |
| `fetchpriority`    | `high` / `low` / `auto`                       |
| `crossorigin`      | CORS for canvas use                           |

```html
<img
  src="/hero.jpg"
  alt="Team collaborating at a whiteboard"
  width="1200"
  height="800"
  loading="lazy"
  decoding="async"
/>
```

## 💡 Examples [#-examples]

```html
<!-- Decorative -->
<img src="/divider.svg" alt="" role="presentation" />

<!-- Responsive density -->
<img
  src="/logo.png"
  srcset="/logo.png 1x, /logo@2x.png 2x"
  alt="Acme"
  width="120"
  height="40"
/>

<!-- Width descriptors -->
<img
  src="/photo-800.jpg"
  srcset="/photo-400.jpg 400w, /photo-800.jpg 800w, /photo-1200.jpg 1200w"
  sizes="(max-width: 600px) 100vw, 600px"
  alt="Mountain lake at dawn"
  width="1200"
  height="800"
  loading="lazy"
/>

<!-- LCP hero: eager + high priority -->
<img
  src="/hero.avif"
  alt="Product screenshot"
  width="1600"
  height="900"
  fetchpriority="high"
/>

<!-- Map -->
<img src="/map.png" alt="Campus map" usemap="#campus" width="600" height="400" />
```

```html
<!-- Always pair with CSS max-width -->
<!-- img { max-width: 100%; height: auto; } -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `alt` is worse than empty decorative `alt=""` — decide intentionally.
* Lazy-loading the LCP image hurts performance — keep heroes eager.
* Wrong `sizes` picks huge or tiny candidates — match real CSS layout.
* Hotlinking / missing CORS breaks canvas `getImageData`.
* Putting text only in images harms a11y and SEO — use real text.

## 🔗 Related [#-related]

* [picture\_source.md](/docs/html/picture-source) — art direction
* [svg\_inline.md](/docs/html/svg-inline) — SVG
* [media.md](/docs/html/media) — media overview
* [../CSS/object\_fit.md](/docs/html/../css/object-fit) — fitting
* [accessibility.md](/docs/html/accessibility) — alt text


# HTML (/docs/html)



# HTML [#html]

Semantic markup, media, a11y.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Input (/docs/html/input)



# Input [#input]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<input>` element creates interactive controls for forms. Behavior depends on the `type` attribute: text fields, checkboxes, radios, files, dates, range sliders, buttons, and more. Inputs participate in constraint validation, autofill, and keyboard accessibility when properly labeled.

Always associate a visible `<label>` (or accessible name). Choose the most specific `type` so mobile keyboards, validation, and password managers work correctly.

## 🔧 Core concepts [#-core-concepts]

### Common types [#common-types]

| `type`                                            | Use                                                        |
| ------------------------------------------------- | ---------------------------------------------------------- |
| `text`                                            | Single-line text (default)                                 |
| `email`, `url`, `tel`, `search`                   | Semantic text with validation / keyboards                  |
| `password`                                        | Obscured text; use `autocomplete`                          |
| `number`                                          | Numeric; `min`/`max`/`step`                                |
| `checkbox`                                        | Independent on/off                                         |
| `radio`                                           | One of a named group                                       |
| `file`                                            | File picker; needs `enctype="multipart/form-data"` on form |
| `hidden`                                          | Not shown; still submitted                                 |
| `date`, `time`, `datetime-local`, `month`, `week` | Temporal pickers (support varies)                          |
| `range`, `color`                                  | Visual pickers                                             |
| `submit`, `reset`, `button`, `image`              | Form actions                                               |

### Critical attributes [#critical-attributes]

* `name` — key in submitted data
* `value` — current / default value; for checkbox/radio, the value when selected
* `required`, `disabled`, `readonly`
* `placeholder` — hint only, **not** a label
* `autocomplete` — tokens like `email`, `new-password`, `street-address`
* `inputmode` — virtual keyboard hint (`decimal`, `numeric`, `email`, …)
* `pattern` — regex for text-like types
* `accept`, `multiple` — file inputs
* `checked` — initial state for checkbox/radio
* `min`, `max`, `step`, `minlength`, `maxlength`

### Labels and grouping [#labels-and-grouping]

```html
<label for="email">Email</label>
<input id="email" name="email" type="email" required autocomplete="email">

<fieldset>
  <legend>Shipping</legend>
  <label><input type="radio" name="ship" value="std" checked> Standard</label>
  <label><input type="radio" name="ship" value="exp"> Express</label>
</fieldset>
```

Radios sharing the same `name` form one tab stop group; arrows move between options.

### Events and values [#events-and-values]

* `input` — value changing; `change` — committed change
* Read via `element.value`, `checked`, or `FormData`
* Files: `input.files` (`FileList`); not available in plain Form URL encoding without multipart

## 💡 Examples [#-examples]

### Text with validation [#text-with-validation]

```html
<label for="username">Username</label>
<input
  id="username"
  name="username"
  type="text"
  required
  minlength="3"
  maxlength="32"
  pattern="[a-zA-Z0-9_]+"
  autocomplete="username"
  aria-describedby="username-hint">
<p id="username-hint">Letters, numbers, and underscore only.</p>
```

### Checkbox and switch-like pattern [#checkbox-and-switch-like-pattern]

```html
<label>
  <input type="checkbox" name="tos" value="yes" required>
  I agree to the terms
</label>
```

### Number and range [#number-and-range]

```html
<label for="qty">Quantity</label>
<input id="qty" name="qty" type="number" min="1" max="99" step="1" value="1">

<label for="vol">Volume</label>
<input id="vol" name="volume" type="range" min="0" max="100" value="50"
  aria-valuemin="0" aria-valuemax="100">
```

### File input [#file-input]

```html
<label for="docs">Attachments</label>
<input
  id="docs"
  name="docs"
  type="file"
  accept=".pdf,image/*"
  multiple
  aria-describedby="docs-help">
<p id="docs-help">PDF or images, up to 5 files.</p>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Placeholder as label** — Disappears on input; bad for a11y and memory.
* **`type="number"` for IDs** — Spinners and parsing issues; use `inputmode="numeric"` + `pattern` for digit strings.
* **Missing `name` on radios** — Grouping breaks; all can appear selected independently.
* **Styling away focus** — Never remove outlines without a visible `:focus-visible` replacement.
* **Hidden required fields** — Can block submit with no visible error.
* **Date formats** — Wire format is ISO-like; display is locale-dependent—do not parse as local free text.
* **Disabled vs readonly** — `disabled` controls are **not** submitted; `readonly` text still is.

## 🔗 Related [#-related]

* [Forms](/docs/html/form) — submission, `FormData`, validation API
* [List](/docs/html/list) — `<datalist>` options for inputs
* [Script](/docs/html/script) — enhancing input behavior
* [Table](/docs/html/table) — inputs in data grids (label carefully)
* [URL](/docs/html/url) — `type="url"` and query encoding
* [Meta](/docs/html/meta) — CSRF / tokens often paired with hidden inputs


# Language (/docs/html/language)



# Language [#language]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Language in HTML is declared primarily with the **`lang` attribute**. It tells browsers, search engines, and assistive technologies which natural language (and optionally dialect) the content uses. Correct language tags improve screen-reader pronunciation, hyphenation, spell-check, font selection, and SEO.

Set `lang` on the root `<html>` element for the document default, then override on elements that switch language. Pair with `hreflang` on links and `<link rel="alternate">` for translated URLs.

## 🔧 Core concepts [#-core-concepts]

### BCP 47 language tags [#bcp-47-language-tags]

Use standard tags, not free-form names:

| Tag          | Meaning                      |
| ------------ | ---------------------------- |
| `en`         | English                      |
| `en-US`      | English (United States)      |
| `en-GB`      | English (United Kingdom)     |
| `es`         | Spanish                      |
| `zh-Hans`    | Chinese, Simplified script   |
| `zh-Hant-TW` | Chinese, Traditional, Taiwan |
| `und`        | Undetermined (rare)          |

Primary language subtag is required; region and script are optional. Prefer the shortest tag that is still useful (`en` vs `en-US` when dialect matters for spelling/voice).

### Document and fragment language [#document-and-fragment-language]

```html
<html lang="en">
…
<blockquote lang="fr">
  <p>Liberté, égalité, fraternité.</p>
</blockquote>
```

* Inheritance: children inherit language unless overridden.
* Empty `lang=""` means unknown / no language (e.g. some proper nouns)—use sparingly.
* `xml:lang` appears in XHTML; in HTML5, `lang` is preferred (both may match in polyglot docs).

### Related attributes and elements [#related-attributes-and-elements]

* **`hreflang`** — language of the linked resource (`<a>`, `<link>`, `<area>`).
* **`translate`** — `yes` / `no` hint for translation tools.
* **`<title>` / meta description** — should match page language.
* **CSS `hyphens` / `:lang()`** — style per language.

```css
:lang(de) { quotes: "„" "“" "‚" "‘"; }
```

### Accessibility [#accessibility]

Screen readers switch voice models based on `lang`. Wrong or missing `lang` causes mispronunciation. Mark inline phrases in another language; do not mark decorative icons or code as a human language unless appropriate (`lang` on `<code>` is often omitted or set to empty).

## 💡 Examples [#-examples]

### Root declaration [#root-declaration]

```html
<!DOCTYPE html>
<html lang="en-GB">
<head>
  <meta charset="utf-8">
  <title>Colour systems</title>
</head>
<body>
  <h1>Colour systems</h1>
</body>
</html>
```

### Inline language switch [#inline-language-switch]

```html
<p>
  The French motto
  <span lang="fr">Liberté, égalité, fraternité</span>
  appears on many public buildings.
</p>
```

### Multilingual navigation with hreflang [#multilingual-navigation-with-hreflang]

```html
<nav aria-label="Languages">
  <ul>
    <li><a href="/en/guide" hreflang="en" lang="en">English</a></li>
    <li><a href="/es/guia" hreflang="es" lang="es">Español</a></li>
    <li><a href="/ja/guide" hreflang="ja" lang="ja">日本語</a></li>
  </ul>
</nav>
```

### Alternate links in head [#alternate-links-in-head]

```html
<head>
  <link rel="alternate" hreflang="en" href="https://example.com/en/docs">
  <link rel="alternate" hreflang="fr" href="https://example.com/fr/docs">
  <link rel="alternate" hreflang="x-default" href="https://example.com/docs">
</head>
```

### Opt out of translation [#opt-out-of-translation]

```html
<p>
  Product code
  <span translate="no">XR-2040-B</span>
  must stay unchanged.
</p>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Missing `lang` on `<html>`** — Validators flag it; AT guesses poorly.
* **Wrong tag** — `eng` or `english` is invalid; use `en`.
* **Over-tagging** — Do not set `lang` on every element when the root already applies.
* **Machine-translated pages** — Keep `lang` accurate to the visible text, not the source CMS locale.
* **`hreflang` mismatches** — Reciprocal alternates should form a consistent set; include `x-default` when appropriate.
* **Direction vs language** — `dir="rtl"` is separate from `lang`; set both for Arabic/Hebrew content (`lang="ar" dir="rtl"`).

## 🔗 Related [#-related]

* [Head](/docs/html/head) — document setup and alternate links
* [Meta](/docs/html/meta) — content-language meta (legacy; prefer `lang`)
* [XML](/docs/html/xml) — `xml:lang` in XML/XHTML
* [Nav](/docs/html/nav) — language switchers
* [Section](/docs/html/section) — scoping translated regions
* [URL](/docs/html/url) — locale prefixes in paths


# Links (/docs/html/links)



# Links [#links]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<a>` element creates hyperlinks to URLs, fragments, email/tel schemes, and downloadable files. Accessible links need clear text (not “click here”), meaningful `href`, and honest `target`/`rel` usage. Prefer real links for navigation so middle-click and progressive enhancement work.

## 🔧 Core concepts [#-core-concepts]

| Attribute  | Role                                                              |
| ---------- | ----------------------------------------------------------------- |
| `href`     | destination URL or `#fragment`                                    |
| `target`   | `_self` `_blank` `_parent` `_top` or frame name                   |
| `rel`      | link relationship (`noopener`, `noreferrer`, `nofollow`, `me`, …) |
| `download` | suggest download filename                                         |
| `hreflang` | language of target                                                |
| `type`     | MIME hint                                                         |
| `ping`     | tracking URLs (privacy-sensitive)                                 |

* Without `href`, `<a>` is a placeholder (not in tab order the same way).
* `target="_blank"` should include `rel="noopener noreferrer"` (modern browsers imply noopener for `_blank`, still good practice).

```html
<a href="/docs/intro">Introduction</a>
<a href="https://example.com" target="_blank" rel="noopener noreferrer">External</a>
<a href="#faq">Jump to FAQ</a>
```

## 💡 Examples [#-examples]

```html
<!-- Email / phone -->
<a href="mailto:hello@example.com">Email us</a>
<a href="tel:+15551234567">Call</a>

<!-- Download -->
<a href="/files/report.pdf" download="report.pdf">Download PDF</a>

<!-- Fragment + id -->
<a href="#shipping">Shipping</a>
<section id="shipping">...</section>

<!-- Skip link -->
<a class="skip" href="#main">Skip to content</a>
<main id="main">...</main>

<!-- Button-looking link vs button -->
<a class="btn" href="/signup">Sign up</a>
<button type="button">Open dialog</button>

<!-- Nav -->
<nav aria-label="Primary">
  <a href="/" aria-current="page">Home</a>
  <a href="/pricing">Pricing</a>
</nav>
```

```html
<!-- Empty href="#" is a smell — use button for actions -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using `<a href="#">` or omitting `href` for JS actions breaks accessibility — use `<button>`.
* Vague link text fails screen reader users scanning links lists.
* `target="_blank"` without context surprises users — warn when needed.
* Nested interactive content (`a` inside `a`, or `a` wrapping `button`) is invalid.
* `javascript:` URLs are obsolete and unsafe.

## 🔗 Related [#-related]

* [nav.md](/docs/html/nav) — navigation landmarks
* [button.md](/docs/html/button) — buttons vs links
* [url.md](/docs/html/url) — URL concepts
* [accessibility.md](/docs/html/accessibility) — a11y
* [aria.md](/docs/html/aria) — aria-current


# Lists (/docs/html/list)



# Lists [#lists]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

HTML provides three primary list types: **ordered** (`<ol>`), **unordered** (`<ul>`), and **description** (`<dl>`). Lists convey structure to assistive technologies—use them for genuine sequences and name/value groups, not merely for indentation. Navigation menus are typically lists inside `<nav>`.

Related helpers: `<li>` for list items, `<dt>` / `<dd>` for terms and descriptions, and `<datalist>` for input suggestions (not a visible list widget by itself).

## 🔧 Core concepts [#-core-concepts]

### Unordered lists (`<ul>`) [#unordered-lists-ul]

Bulleted collections where order is not significant (features, tags, nav links).

```html
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>
```

### Ordered lists (`<ol>`) [#ordered-lists-ol]

Numbered sequences. Attributes:

| Attribute  | Effect                                                 |
| ---------- | ------------------------------------------------------ |
| `type`     | `1`, `a`, `A`, `i`, `I` (prefer CSS `list-style-type`) |
| `start`    | Starting number                                        |
| `reversed` | Count downward                                         |

```html
<ol start="3" reversed>
  <li>Third</li>
  <li>Second</li>
  <li>First</li>
</ol>
```

### Description lists (`<dl>`) [#description-lists-dl]

Groups of terms (`<dt>`) and descriptions (`<dd>`). One term may have multiple descriptions and vice versa.

```html
<dl>
  <dt>HTML</dt>
  <dd>HyperText Markup Language</dd>
  <dt>CSS</dt>
  <dd>Cascading Style Sheets</dd>
</dl>
```

### Nesting and content model [#nesting-and-content-model]

* Only `<li>` may be direct children of `<ul>` / `<ol>` (plus script-supporting elements).
* Nest lists **inside** `<li>`, not as siblings of `<li>`.
* Flow content is allowed inside `<li>`, `<dt>`, `<dd>`.

### Accessibility [#accessibility]

* Lists announce item counts in many screen readers.
* Do not fake lists with `<div>` + bullets; rebuild as real lists.
* For nav: `<nav><ul><li><a>…&lt;/a>&lt;/li>&lt;/ul>&lt;/nav>`.
* Flat vs nested: reflect real hierarchy; avoid deep nesting without need.
* Custom markers via CSS still keep list semantics if the elements remain.

## 💡 Examples [#-examples]

### Nested navigation list [#nested-navigation-list]

```html
<nav aria-label="Docs">
  <ul>
    <li><a href="/html">HTML</a>
      <ul>
        <li><a href="/html/forms">Forms</a></li>
        <li><a href="/html/tables">Tables</a></li>
      </ul>
    </li>
    <li><a href="/css">CSS</a></li>
  </ul>
</nav>
```

### Steps with ordered list [#steps-with-ordered-list]

```html
<ol>
  <li>Add the <code>lang</code> attribute to <code>&lt;html&gt;</code>.</li>
  <li>Provide a unique <code>&lt;title&gt;</code>.</li>
  <li>Include a viewport meta tag.</li>
</ol>
```

### Glossary with description list [#glossary-with-description-list]

```html
<dl>
  <dt id="term-landmark">Landmark</dt>
  <dd>
    A region role that assistive tech can jump to
    (e.g. <code>main</code>, <code>navigation</code>).
  </dd>
  <dt>Focus visible</dt>
  <dd>Clear indication of the keyboard-focused element.</dd>
</dl>
```

### Datalist for input suggestions [#datalist-for-input-suggestions]

```html
<label for="browser">Browser</label>
<input id="browser" name="browser" list="browsers" autocomplete="off">
<datalist id="browsers">
  <option value="Firefox">
  <option value="Chrome">
  <option value="Safari">
  <option value="Edge">
</datalist>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Div lists** — Breaking list semantics loses count announcements and list shortcuts.
* **Invalid children** — Putting `<p>` or `<div>` directly in `<ul>` is invalid; wrap with `<li>`.
* **Using tables for layout lists** — Prefer lists or CSS grid.
* **Empty bullets for spacing** — Use margin/gap, not empty `<li>` elements.
* **`type` on `<ul>`** — Deprecated presentational habit; use CSS.
* **Description list misuse** — Dialogues or random pairs may fit better as headings + paragraphs or cards.
* **ARIA `role="list"` on styled lists** — Some browsers drop list semantics when `list-style: none` is applied; restoring with explicit roles may be needed—test with AT.

## 🔗 Related [#-related]

* [Nav](/docs/html/nav) — menus built from lists
* [Input](/docs/html/input) — `list` + `<datalist>`
* [Section](/docs/html/section) — grouping list-heavy content
* [Table](/docs/html/table) — when tabular data beats lists
* [Div](/docs/html/div) — avoid replacing lists with divs
* [Form](/docs/html/form) — option groups vs lists


# Media (/docs/html/media)



# Media [#media]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

HTML media elements embed images, audio, video, and responsive picture sources. Core tags: `<img>`, `<picture>`, `<audio>`, `<video>`, `<source>`, `<track>`, and older embeds (`<iframe>`, `<object>`). Prefer native elements for playback controls, captions, and performance hints (`loading`, `decoding`, `preload`).

Accessible media needs **text alternatives** (alt text, transcripts, captions) and must not autoplay with sound. Decorative images use empty `alt=""`.

## 🔧 Core concepts [#-core-concepts]

### Images (`<img>`) [#images-img]

Required: `src` (or `srcset` with sizes) and `alt`.

| Attribute          | Role                                     |
| ------------------ | ---------------------------------------- |
| `alt`              | Short equivalent; `alt=""` if decorative |
| `width` / `height` | Reduce CLS; match aspect ratio           |
| `loading="lazy"`   | Defer offscreen images                   |
| `decoding="async"` | Decode without blocking                  |
| `srcset` / `sizes` | Responsive resolution candidates         |
| `fetchpriority`    | `high` for LCP image when appropriate    |

### Picture and art direction [#picture-and-art-direction]

```html
<picture>
  <source type="image/avif" srcset="hero.avif">
  <source type="image/webp" srcset="hero.webp">
  <img src="hero.jpg" alt="Mountain lake at sunrise" width="1200" height="600">
</picture>
```

Use media queries on `<source media="…">` when cropping changes by viewport—not only for format fallbacks.

### Video and audio [#video-and-audio]

```html
<video controls playsinline poster="poster.jpg" width="640" height="360">
  <source src="talk.webm" type="video/webm">
  <source src="talk.mp4" type="video/mp4">
  <track kind="captions" srclang="en" src="talk.vtt" label="English" default>
  Download the <a href="talk.mp4">MP4</a>.
</video>
```

* `controls` — native UI (prefer over custom-only players without a11y).
* `autoplay` — often blocked; if used, mute with `muted` and keep motion brief.
* `loop`, `preload` (`none` | `metadata` | `auto`).
* `<track>` — captions (`captions`), subtitles, descriptions, chapters.

### Iframes [#iframes]

Third-party embeds need `title`, restrictive `sandbox` when possible, and thoughtful `loading="lazy"`. Prefer privacy-enhanced embed URLs.

## 💡 Examples [#-examples]

### Responsive image with srcset [#responsive-image-with-srcset]

```html
<img
  src="photo-800.jpg"
  srcset="photo-400.jpg 400w, photo-800.jpg 800w, photo-1200.jpg 1200w"
  sizes="(max-width: 600px) 100vw, 600px"
  alt="Red ceramic mug on a wooden table"
  width="800"
  height="600"
  loading="lazy"
  decoding="async">
```

### Audio with transcript [#audio-with-transcript]

```html
<figure>
  <figcaption id="ep-title">Episode 12: Semantic HTML</figcaption>
  <audio controls preload="metadata" aria-labelledby="ep-title">
    <source src="ep12.mp3" type="audio/mpeg">
  </audio>
  <details>
    <summary>Transcript</summary>
    <p>Welcome to episode twelve…</p>
  </details>
</figure>
```

### Art-directed picture [#art-directed-picture]

```html
<picture>
  <source media="(max-width: 600px)" srcset="hero-mobile.jpg">
  <source media="(min-width: 601px)" srcset="hero-desktop.jpg">
  <img src="hero-desktop.jpg" alt="Team collaborating in a bright studio">
</picture>
```

### Accessible iframe embed [#accessible-iframe-embed]

```html
<iframe
  title="Map: office location"
  src="https://maps.example.com/embed?q=office"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  allowfullscreen></iframe>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Missing alt** — Critical a11y/SEO failure; decorative needs `alt=""`, not omitted.
* **Filename as alt** — `alt="IMG_4022.jpg"` helps no one.
* **Autoplay + sound** — Hostile UX; often blocked; violates preferences.
* **Captions missing** — Video without captions excludes Deaf/hard-of-hearing users.
* **Huge unoptimized assets** — Compress, modern formats, correct dimensions.
* **CSS background for content images** — Cannot carry alt text; use `<img>` for meaningful photos.
* **Aspect ratio CLS** — Always set width/height or CSS `aspect-ratio`.

## 🔗 Related [#-related]

* [Src](/docs/html/src) — `src`, `srcset`, and URL resolution
* [URL](/docs/html/url) — absolute vs relative media URLs
* [Canvas](/docs/html/canvas) — drawing frames from video/images
* [Figure patterns](/docs/html/section) — grouping media with captions
* [Script](/docs/html/script) — custom players and Media element API
* [Style](/docs/html/style) — object-fit and responsive CSS


# Meta (/docs/html/meta)



# Meta [#meta]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<meta>` element represents metadata that cannot be expressed with `<title>`, `<link>`, `<script>`, or `<style>`. It lives in `<head>` (except `itemprop` microdata cases). Meta tags configure character encoding, viewport behavior, SEO descriptions, social previews, robots directives, and HTTP-equivalent headers.

Meta content is always public in the HTML source—never store secrets there.

## 🔧 Core concepts [#-core-concepts]

### Forms of meta [#forms-of-meta]

1. **Charset** — `<meta charset="utf-8">`
2. **Name/content** — `<meta name="description" content="…">`
3. **Http-equiv** — `<meta http-equiv="…" content="…">` (prefer real HTTP headers when possible)
4. **Property** (Open Graph, etc.) — `<meta property="og:title" content="…">`

### Essential tags [#essential-tags]

```html
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="Concise summary of the page for search and shares.">
```

Viewport notes:

* `width=device-width` — match CSS pixels to device.
* Avoid locking zoom (`user-scalable=no`, extreme `maximum-scale`)—hurts accessibility.
* `viewport-fit=cover` — notched devices with `env(safe-area-inset-*)`.

### SEO and robots [#seo-and-robots]

| Name                 | Purpose                                      |
| -------------------- | -------------------------------------------- |
| `description`        | Snippet candidate (\~150–160 chars)          |
| `robots`             | `index`/`noindex`, `follow`/`nofollow`, etc. |
| `googlebot`          | Crawler-specific overrides                   |
| `author`, `keywords` | Low impact today; keywords largely ignored   |

```html
<meta name="robots" content="index, follow">
<meta name="googlebot" content="max-image-preview:large">
```

### Social and app meta [#social-and-app-meta]

Open Graph and Twitter cards drive link previews:

```html
<meta property="og:title" content="Forms — HTML Reference">
<meta property="og:description" content="Cheat sheet for the form element.">
<meta property="og:image" content="https://example.com/og/forms.png">
<meta property="og:type" content="website">
<meta name="twitter:card" content="summary_large_image">
```

Also common: `theme-color`, `color-scheme`, `application-name`, Apple mobile web app tags.

### Http-equiv (use carefully) [#http-equiv-use-carefully]

| http-equiv                | Notes                                               |
| ------------------------- | --------------------------------------------------- |
| `refresh`                 | Redirect/refresh—prefer HTTP 301/302; a11y concerns |
| `content-security-policy` | Prefer CSP HTTP header                              |
| `X-UA-Compatible`         | Legacy IE; obsolete for modern sites                |

## 💡 Examples [#-examples]

### Solid default head metas [#solid-default-head-metas]

```html
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Tables — HTML Reference</title>
  <meta name="description" content="Accessible HTML table patterns, scope, and captions.">
  <meta name="color-scheme" content="light dark">
  <meta name="theme-color" content="#0f766e">
</head>
```

### Noindex draft page [#noindex-draft-page]

```html
<meta name="robots" content="noindex, nofollow">
```

### Open Graph article [#open-graph-article]

```html
<meta property="og:type" content="article">
<meta property="og:title" content="Prefer semantic lists">
<meta property="og:url" content="https://example.com/blog/lists">
<meta property="og:image" content="https://example.com/og/lists.png">
<meta property="article:published_time" content="2026-07-10T08:00:00Z">
```

### CSP via meta (header preferred) [#csp-via-meta-header-preferred]

```html
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self'; img-src 'self' https: data:; script-src 'self'">
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Charset not first** — Place within the first 1024 bytes.
* **Duplicate descriptions** — Keep one clear `name="description"`.
* **Refresh redirects** — Confuse users and AT; break the back button.
* **Keyword stuffing** — Ineffective and spammy.
* **Disabling zoom** — Accessibility violation for low-vision users.
* **Relative OG images** — Many crawlers need absolute HTTPS URLs.
* **Conflicting robots** — Meta vs `X-Robots-Tag` vs `robots.txt`—align them.

## 🔗 Related [#-related]

* [Head](/docs/html/head) — where meta belongs
* [URL](/docs/html/url) — canonical URLs alongside meta
* [Language](/docs/html/language) — prefer `lang` over `content-language`
* [Media](/docs/html/media) — OG image assets
* [Script](/docs/html/script) — CSP interaction with inline scripts
* [XML](/docs/html/xml) — metadata in XML documents


# Nav (/docs/html/nav)



# Nav [#nav]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<nav>` element marks a section of **major navigation links**—site menus, tables of contents, breadcrumbs, or in-page indexes. Browsers expose it as a `navigation` landmark so assistive technology users can jump directly to it.

Not every group of links needs `<nav>`: footers often wrap legal links in one labeled nav, while incidental “related posts” links may stay in a plain list inside `<aside>` or `<footer>`. Prefer quality over quantity of landmarks.

## 🔧 Core concepts [#-core-concepts]

### Landmark behavior [#landmark-behavior]

* Implicit role: `navigation`.
* Multiple navs are allowed; distinguish them with `aria-label` or `aria-labelledby`.
* Skip redundant roles: do not write `<nav role="navigation">`.

```html
<nav aria-label="Primary">…</nav>
<nav aria-label="Breadcrumb">…</nav>
```

### Typical structure [#typical-structure]

Lists are the conventional pattern:

```html
<nav aria-label="Primary">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/docs" aria-current="page">Docs</a></li>
    <li><a href="/blog">Blog</a></li>
  </ul>
</nav>
```

* `aria-current="page"` (or `true`) marks the current page link.
* One primary `<h2 class="visually-hidden">` can label the region instead of `aria-label`.

### What belongs in nav [#what-belongs-in-nav]

| Include                    | Usually exclude                         |
| -------------------------- | --------------------------------------- |
| Main site menu             | Social icon rows without site structure |
| Docs TOC                   | Pagination alone (optional)             |
| Breadcrumbs                | Random related links                    |
| In-page section jump lists | Language pickers can be nav if major    |

### Keyboard and mobile [#keyboard-and-mobile]

* Ensure links are real `<a href>`—not clickable divs.
* Disclose mobile menus with `<button>` + `aria-expanded`, focus management, and Esc to close.
* Visible focus styles on all interactive items.

## 💡 Examples [#-examples]

### Primary and utility navs [#primary-and-utility-navs]

```html
<header>
  <a href="/">Acme</a>
  <nav aria-label="Primary">
    <ul>
      <li><a href="/product">Product</a></li>
      <li><a href="/pricing">Pricing</a></li>
    </ul>
  </nav>
  <nav aria-label="Account">
    <ul>
      <li><a href="/login">Log in</a></li>
    </ul>
  </nav>
</header>
```

### Breadcrumbs [#breadcrumbs]

```html
<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/docs">Docs</a></li>
    <li aria-current="page">Forms</li>
  </ol>
</nav>
```

### Table of contents [#table-of-contents]

```html
<article>
  <h1>Accessible tables</h1>
  <nav aria-labelledby="toc-heading">
    <h2 id="toc-heading">On this page</h2>
    <ol>
      <li><a href="#caption">Captions</a></li>
      <li><a href="#scope">Scope</a></li>
    </ol>
  </nav>
  <section id="caption">…</section>
</article>
```

### Disclosure menu sketch [#disclosure-menu-sketch]

```html
<nav aria-label="Primary">
  <button type="button" aria-expanded="false" aria-controls="menu">
    Menu
  </button>
  <ul id="menu" hidden>
    <li><a href="/docs">Docs</a></li>
    <li><a href="/api">API</a></li>
  </ul>
</nav>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Too many nav landmarks** — Every link list as `<nav>` overwhelms rotor menus.
* **Unlabeled duplicates** — Two “navigation” entries with no name are indistinguishable.
* **Nav without links** — Empty or button-only regions confuse expectations.
* **`aria-current` on the wrong node** — Put it on the link or the current crumb, consistently.
* **Skip link missing** — Pages with large navs should offer “Skip to content” to `<main>`.
* **Focus trap bugs** — Mobile overlays must return focus and allow Escape.

## 🔗 Related [#-related]

* [List](/docs/html/list) — `ul`/`ol` patterns for menus
* [Footer](/docs/html/footer) — secondary nav in footers
* [Section](/docs/html/section) — TOC within articles
* [Div](/docs/html/div) — layout wrappers around nav
* [Language](/docs/html/language) — language switchers
* [URL](/docs/html/url) — link targets and fragments


# Picture & Source (/docs/html/picture-source)



# Picture & Source [#picture--source]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`<picture>` wraps `<source>` elements and an `<img>` fallback for **art direction** (different crops/files per condition) and format negotiation (AVIF/WebP). The browser picks the first matching `<source>`, then loads via the `<img>` for intrinsic size, `alt`, and decoding behavior.

## 🔧 Core concepts [#-core-concepts]

* **Structure**: `<picture>` → zero+ `<source>` → required `<img>`.
* **`media`**: art direction queries on `<source>`.
* **`type`**: MIME type for format selection.
* **`srcset` / `sizes`**: on `<source>` or `<img>` for resolution switching.
* **Final `<img>`**: provides `alt`, `width`/`height`, `loading`, and fallback `src`.
* Not a replacement for CSS `display` — it selects which resource loads.

```html
<picture>
  <source type="image/avif" srcset="/hero.avif" />
  <source type="image/webp" srcset="/hero.webp" />
  <img src="/hero.jpg" alt="Product on a desk" width="1600" height="900" />
</picture>
```

## 💡 Examples [#-examples]

```html
<!-- Art direction -->
<picture>
  <source
    media="(max-width: 600px)"
    srcset="/hero-mobile.jpg"
    width="800"
    height="1200"
  />
  <source media="(min-width: 601px)" srcset="/hero-desktop.jpg" />
  <img
    src="/hero-desktop.jpg"
    alt="Wide shot of the storefront"
    width="1600"
    height="900"
    fetchpriority="high"
  />
</picture>

<!-- Format + responsive widths -->
<picture>
  <source
    type="image/avif"
    srcset="/p-400.avif 400w, /p-800.avif 800w"
    sizes="(max-width: 700px) 100vw, 700px"
  />
  <source
    type="image/webp"
    srcset="/p-400.webp 400w, /p-800.webp 800w"
    sizes="(max-width: 700px) 100vw, 700px"
  />
  <img
    src="/p-800.jpg"
    srcset="/p-400.jpg 400w, /p-800.jpg 800w"
    sizes="(max-width: 700px) 100vw, 700px"
    alt="Red sneakers"
    width="800"
    height="800"
    loading="lazy"
  />
</picture>

<!-- Dark mode asset -->
<picture>
  <source srcset="/logo-dark.svg" media="(prefers-color-scheme: dark)" />
  <img src="/logo-light.svg" alt="Acme" width="120" height="32" />
</picture>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Omitting `<img>` is invalid — always include it with `alt`.
* `media` on sources is for art direction; don’t confuse with CSS-only hiding of a single image.
* First matching source wins — order matters (narrow media / preferred types first as designed).
* Width/height on sources help but layout stability still depends on the chosen image’s dimensions.
* Overusing many huge variants wastes storage — keep a sensible set.

## 🔗 Related [#-related]

* [images.md](/docs/html/images) — img basics
* [video\_audio.md](/docs/html/video-audio) — media sources
* [media.md](/docs/html/media) — media overview
* [../CSS/object\_fit.md](/docs/html/../css/object-fit) — cropping via CSS
* [../CSS/dark\_mode.md](/docs/html/../css/dark-mode) — theme assets


# Script (/docs/html/script)



# Script [#script]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<script>` element embeds or loads JavaScript (and other script types). Scripts can be classic or module (`type="module"`), blocking or deferred, inline or external. Modern best practice: load modules or classic scripts with `defer` from `<head>`, keep progressive enhancement in mind, and respect Content Security Policy.

Scripts run with the page’s origin privileges—treat URLs, integrity, and user-generated inline script with care.

## 🔧 Core concepts [#-core-concepts]

### Loading modes [#loading-modes]

| Pattern                            | Behavior                                                              |
| ---------------------------------- | --------------------------------------------------------------------- |
| `<script src>` (classic, no attrs) | Fetch + execute immediately; blocks parsing                           |
| `async`                            | Download in parallel; execute as soon as ready (order not guaranteed) |
| `defer`                            | Download in parallel; execute after document parse, in order          |
| `type="module"`                    | Deferred by default; strict mode; unique imports                      |
| Inline script                      | Executes when parsed (modules still deferred)                         |

```html
<script src="/app.js" defer></script>
<script type="module" src="/main.js"></script>
```

### Important attributes [#important-attributes]

* `src` — external URL
* `type` — `module`, `importmap`, MIME for data blocks, or default JS
* `nomodule` — fallback for non-module browsers
* `crossorigin` — CORS for error reporting / modules
* `integrity` — Subresource Integrity (SRI) hash
* `referrerpolicy` — referrer for the request
* `blocking="render"` — rare; opt into render-blocking (use carefully)
* `fetchpriority` — hint for the script request

### Modules vs classic [#modules-vs-classic]

ES modules support `import`/`export`, run once per URL, and default to CORS for cross-origin. Classic scripts share a global scope and duplicate if included twice.

```html
<script type="importmap">
{
  "imports": {
    "lodash/": "https://cdn.example.com/lodash/"
  }
}
</script>
```

### Placement [#placement]

* **Head + defer/module** — preferred for apps.
* **End of body** — legacy pattern for classic scripts without defer.
* **Inline critical** — tiny bootstraps only; prefer external for cacheability.

### Accessibility and UX [#accessibility-and-ux]

Scripts should not be the only way to submit forms or follow links. Provide noscript fallbacks when core content depends on JS:

```html
<noscript>
  <p>This app needs JavaScript. View the <a href="/static">static docs</a>.</p>
</noscript>
```

## 💡 Examples [#-examples]

### Deferred classic + module [#deferred-classic--module]

```html
<head>
  <script src="/legacy-analytics.js" defer></script>
  <script type="module" src="/app.js"></script>
  <script nomodule src="/fallback.js"></script>
</head>
```

### SRI for CDN script [#sri-for-cdn-script]

```html
<script
  src="https://cdn.example.com/lib@1.2.3/lib.min.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
  crossorigin="anonymous"
  defer></script>
```

### Inline module [#inline-module]

```html
<script type="module">
  import { init } from "/js/init.js";
  init(document.getElementById("app"));
</script>
```

### JSON data island (non-JS type) [#json-data-island-non-js-type]

```html
<script id="config" type="application/json">
  { "apiBase": "/api", "featureFlags": { "newNav": true } }
</script>
<script type="module">
  const config = JSON.parse(document.getElementById("config").textContent);
</script>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Parser-blocking scripts** — Large classic scripts in head without `defer` delay First Paint.
* **`async` order** — Dependent files may run out of order; use `defer` or modules.
* **Duplicate globals** — Including the same classic library twice causes bugs.
* **Inline without CSP nonces** — Strict CSP blocks inline scripts; use nonces/hashes or external files.
* **`document.write`** — Destroys performance; avoid.
* **Assuming DOM ready** — Module/defer run after parse; classic without defer may need `DOMContentLoaded`.
* **Untrusted `innerHTML` + script** — XSS risk; sanitize and avoid injecting markup with handlers.

## 🔗 Related [#-related]

* [Head](/docs/html/head) — where to place scripts
* [Src](/docs/html/src) — resolving script URLs
* [URL](/docs/html/url) — CDN and absolute paths
* [Meta](/docs/html/meta) — CSP meta vs headers
* [Form](/docs/html/form) — progressive enhancement of forms
* [Canvas](/docs/html/canvas) — scripts that draw
* [Style](/docs/html/style) — FOUC and load ordering with CSS


# Section (/docs/html/section)



# Section [#section]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<section>` element represents a **thematic grouping** of content, typically with a heading. It is sectioning content: it appears in the document outline and can own its own `<header>` / `<footer>`. Use it when the block is a meaningful chunk of the page—not as a generic styling wrapper (that is `<div>`).

HTML5 also provides `<article>`, `<aside>`, `<nav>`, and `<main>` for more specific roles. Choose the most precise element; fall back to `<section>` for titled thematic groups, and `<div>` when there is no semantics to express.

## 🔧 Core concepts [#-core-concepts]

### Section vs related elements [#section-vs-related-elements]

| Element     | Use when                                                                 |
| ----------- | ------------------------------------------------------------------------ |
| `<section>` | Thematic group that belongs in the outline, usually with heading         |
| `<article>` | Self-contained composition (post, card, widget) distributable on its own |
| `<aside>`   | Tangentially related (pull quote, ads, secondary nav)                    |
| `<main>`    | Dominant unique content of the document (one per page)                   |
| `<div>`     | Purely presentational / script hook                                      |

### Headings and outline [#headings-and-outline]

Every section should ideally have a heading (`h1`–`h6` or `hgroup` patterns). Nesting sections raises the logical rank in outline algorithms; in practice, authors still assign explicit heading levels carefully for accessibility.

```html
<main>
  <h1>HTML landmarks</h1>
  <section aria-labelledby="nav-sec">
    <h2 id="nav-sec">Navigation</h2>
    <p>…</p>
  </section>
  <section aria-labelledby="form-sec">
    <h2 id="form-sec">Forms</h2>
    <p>…</p>
  </section>
</main>
```

### Accessibility [#accessibility]

* `<section>` without an accessible name is **not** a landmark in most browsers.
* With `aria-label` / `aria-labelledby` (often pointing at the heading), it becomes a `region` landmark.
* Do not create dozens of named regions—reserve for major chunks.
* Prefer one `<main>`; put sections inside it.

### Headers and footers inside [#headers-and-footers-inside]

```html
<section>
  <header>
    <h2>Release notes</h2>
    <p>Version 2.4</p>
  </header>
  <p>…</p>
  <footer>
    <p>Last updated <time datetime="2026-07-10">July 10</time></p>
  </footer>
</section>
```

## 💡 Examples [#-examples]

### Article composed of sections [#article-composed-of-sections]

```html
<article>
  <h1>Using section wisely</h1>
  <section>
    <h2>When to use it</h2>
    <p>Group related content under a shared theme.</p>
  </section>
  <section>
    <h2>When to avoid it</h2>
    <p>Do not wrap every heading for CSS convenience.</p>
  </section>
</article>
```

### Named region landmark [#named-region-landmark]

```html
<section aria-labelledby="newsletter-heading">
  <h2 id="newsletter-heading">Newsletter</h2>
  <form action="/subscribe" method="post">…</form>
</section>
```

### FAQ pattern [#faq-pattern]

```html
<section aria-labelledby="faq">
  <h2 id="faq">FAQ</h2>
  <div>
    <h3>Is section a landmark?</h3>
    <p>Only when it has an accessible name.</p>
  </div>
  <div>
    <h3>Can I nest sections?</h3>
    <p>Yes—reflect real hierarchy.</p>
  </div>
</section>
```

### Avoid: section as layout shell [#avoid-section-as-layout-shell]

```html
<!-- Prefer div for grid shells without meaning -->
<div class="layout-grid">
  <main>…</main>
  <aside>…</aside>
</div>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Section soup** — Replacing all divs with sections adds noise and false outline entries.
* **Headingless sections** — Weak semantics; add a heading or use a div.
* **Multiple mains** — Invalid pattern; sections do not replace `main`.
* **Skipping heading levels** — Jumping `h2` → `h4` confuses AT users.
* **Over-labeling regions** — Too many landmarks slow navigation.
* **Confusing article vs section** — If it could stand alone in a feed, prefer `article`.

## 🔗 Related [#-related]

* [Div](/docs/html/div) — non-semantic containers
* [Nav](/docs/html/nav) — navigation sections
* [Footer](/docs/html/footer) — section and page footers
* [Form](/docs/html/form) — forms inside sections
* [List](/docs/html/list) — TOC lists for long sections
* [Language](/docs/html/language) — `lang` on a section
* [Style](/docs/html/style) — styling section layouts


# Semantic HTML (/docs/html/semantic)



# Semantic HTML [#semantic-html]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Semantic elements describe meaning: headings, landmarks, lists, figures, and text-level semantics. They improve accessibility, SEO, and readability without CSS. Prefer native elements over generic `<div>`/`<span>` when a matching semantic tag exists.

## 🔧 Core concepts [#-core-concepts]

| Element                                                    | Meaning                  |
| ---------------------------------------------------------- | ------------------------ |
| `header` `footer` `main` `nav` `aside` `section` `article` | landmarks / sections     |
| `h1`–`h6`                                                  | heading outline          |
| `p` `ul` `ol` `dl`                                         | text structure           |
| `figure` `figcaption`                                      | media with caption       |
| `blockquote` `cite` `q`                                    | quotations               |
| `time` `address` `mark` `strong` `em`                      | inline semantics         |
| `search`                                                   | search landmark (modern) |

* One primary `<main>` per document.
* `section` needs a heading; `article` is independently distributable content.
* Don’t skip heading levels arbitrarily.

```html
<body>
  <header>...</header>
  <nav aria-label="Primary">...</nav>
  <main>
    <article>
      <h1>Title</h1>
      <p>...</p>
    </article>
  </main>
  <footer>...</footer>
</body>
```

## 💡 Examples [#-examples]

```html
<article>
  <header>
    <h1>Release notes</h1>
    <p><time datetime="2026-07-10">July 10, 2026</time></p>
  </header>
  <section aria-labelledby="feat">
    <h2 id="feat">Features</h2>
    <ul>
      <li>Faster builds</li>
    </ul>
  </section>
  <figure>
    <img src="/chart.svg" alt="Build time chart falling from 12s to 4s" />
    <figcaption>Median build time by week</figcaption>
  </figure>
</article>

<aside aria-labelledby="tips">
  <h2 id="tips">Tips</h2>
  <p>...</p>
</aside>

<!-- Text emphasis -->
<p><strong>Warning:</strong> <em>destructive</em> action.</p>
```

```html
<!-- Prefer -->
<nav>...</nav>
<!-- Over -->
<div class="nav">...</div>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using only `<div>` soup forces ARIA to reinvent semantics poorly.
* Multiple `<h1>` can be OK in some outlines but keep a clear hierarchy.
* `section` without headings is usually a glorified div.
* `strong` ≠ bold CSS; `em` ≠ italic CSS — meaning first, style second.
* Landmark overuse (`nav` everywhere) adds noise — label distinct navs.

## 🔗 Related [#-related]

* [section.md](/docs/html/section) — sections
* [nav.md](/docs/html/nav) — navigation
* [footer.md](/docs/html/footer) — footer
* [accessibility.md](/docs/html/accessibility) — a11y
* [aria.md](/docs/html/aria) — when HTML isn’t enough


# Src (/docs/html/src)



# Src [#src]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The **`src` attribute** (and relatives `srcset`, `data`, `href` for some resources) tells the browser where to fetch an embedded resource: scripts, images, frames, tracks, and media sources. Understanding URL resolution, CORS, and responsive image candidates prevents broken assets and layout shift.

`src` always holds a single URL. For responsive images, combine `src` (fallback) with `srcset` and `sizes`. For `<video>` / `<audio>`, child `<source src>` elements provide format alternatives.

## 🔧 Core concepts [#-core-concepts]

### Elements that use `src` [#elements-that-use-src]

| Element                | Resource                  |
| ---------------------- | ------------------------- |
| `<img>`                | Image                     |
| `<script>`             | JavaScript                |
| `<iframe>`             | Nested browsing context   |
| `<audio>` / `<video>`  | Media (or use `<source>`) |
| `<source>`             | Media/picture candidate   |
| `<track>`              | Text track (WebVTT)       |
| `<embed>`              | External plug-in content  |
| `<input type="image">` | Submit button image       |

Related: `<link href>` for stylesheets/icons; `<a href>` for navigation—not `src`.

### URL resolution [#url-resolution]

Relative `src` values resolve against the document URL, or against `<base href>` if present.

```html
<!-- Document: https://example.com/docs/html/ -->
<img src="images/logo.png" alt="Logo">
<!-- → https://example.com/docs/html/images/logo.png -->

<img src="/images/logo.png" alt="Logo">
<!-- → https://example.com/images/logo.png -->
```

Protocols: `https:` preferred; `data:` for small embeds; `blob:` for generated objects; avoid mixed content (`http` on `https` pages).

### Srcset syntax [#srcset-syntax]

```html
<img
  src="hero-800.jpg"
  srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w"
  sizes="(max-width: 700px) 100vw, 700px"
  alt="Hero">
```

* **Width descriptors** (`400w`) — with `sizes`, browser picks density-appropriate file.
* **Pixel density** (`logo.png 1x, logo@2x.png 2x`) — for fixed-size images.
* `src` remains the fallback / default.

### CORS and credentials [#cors-and-credentials]

Cross-origin images can display without CORS but **taint canvas**. Scripts and fonts need proper CORS. Use `crossorigin` on `<img>` / `<script>` / `<link>` when you need access to pixel data or better error info.

```html
<img src="https://cdn.example.com/pic.jpg" alt="" crossorigin="anonymous">
```

### Integrity [#integrity]

Pair `src` with `integrity` (SRI) on scripts and stylesheets to ensure bytes match an expected hash.

## 💡 Examples [#-examples]

### Image with dimensions and lazy load [#image-with-dimensions-and-lazy-load]

```html
<img
  src="/media/team.jpg"
  alt="Engineering team at the whiteboard"
  width="640"
  height="480"
  loading="lazy"
  decoding="async">
```

### Video sources [#video-sources]

```html
<video controls poster="/media/poster.jpg">
  <source src="/media/talk.webm" type="video/webm">
  <source src="/media/talk.mp4" type="video/mp4">
</video>
```

### Script module URL [#script-module-url]

```html
<script type="module" src="/assets/js/main.js"></script>
```

### Picture format negotiation [#picture-format-negotiation]

```html
<picture>
  <source srcset="/img/hero.avif" type="image/avif">
  <source srcset="/img/hero.webp" type="image/webp">
  <img src="/img/hero.jpg" alt="Forest path in fog">
</picture>
```

### Blob URL from script [#blob-url-from-script]

```html
<script type="module">
  const blob = new Blob(["print('hi')"], { type: "text/python" });
  const url = URL.createObjectURL(blob);
  // revoke when done: URL.revokeObjectURL(url);
</script>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Broken relative paths** — Moving pages without fixing assets 404s; prefer root-absolute `/…` for app-wide assets.
* **`<base>` side effects** — Changes every relative `src` and `href`.
* **Missing `src` on img** — Invalid; empty images still need intentional handling.
* **Srcset without sizes** — Browser may assume `100vw` and over-download.
* **Hotlinking** — Unreliable and often blocked; host or contract CDNs.
* **Mixed content** — Active mixed content blocked; passive images may warn.
* **Forgetting revoke** — Blob URLs leak memory until `revokeObjectURL`.

## 🔗 Related [#-related]

* [Media](/docs/html/media) — images, audio, video elements
* [URL](/docs/html/url) — URL anatomy and encoding
* [Script](/docs/html/script) — script loading attributes
* [Canvas](/docs/html/canvas) — CORS-tainted images
* [Head](/docs/html/head) — `<base>` and resource hints
* [Style](/docs/html/style) — CSS `url()` vs HTML `src`


# Style (/docs/html/style)



# Style [#style]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Styling HTML happens through the **CSS cascade**: external stylesheets (`<link rel="stylesheet">`), document-level `<style>` elements, and inline `style` attributes. Prefer external or scoped document CSS for maintainability; use inline styles sparingly for dynamic values. The HTML `style` attribute applies declarations to one element with high specificity.

Separating structure (HTML) from presentation (CSS) improves accessibility, caching, and theming. Never use styling alone to convey meaning that belongs in semantics or text.

## 🔧 Core concepts [#-core-concepts]

### Three authoring layers [#three-authoring-layers]

```html
<head>
  <link rel="stylesheet" href="/styles.css">
  <style>
    :root { color-scheme: light dark; }
    .callout { border-inline-start: 4px solid #0f766e; }
  </style>
</head>
<body>
  <p style="margin-block: 0">Inline exception</p>
</body>
```

| Layer        | Pros                           | Cons                                           |
| ------------ | ------------------------------ | ---------------------------------------------- |
| External CSS | Cacheable, shareable           | Extra request (mitigate with HTTP/2, bundling) |
| `<style>`    | Critical CSS, no round trip    | Not shared across pages unless duplicated      |
| `style=""`   | Quick overrides, JS-set values | Hard to maintain; high specificity             |

### The `style` attribute [#the-style-attribute]

* Contains CSS declarations, not selectors.
* Specificity equals one inline declaration (beats classes unless `!important` wars).
* Cannot express pseudo-elements (`::before`) or media queries—use a stylesheet.
* Reflects in `element.style`; CSSOM `cssText` updates it.

### `<style>` element attributes [#style-element-attributes]

* `media` — conditional application (`media="(min-width: 48rem)"`).
* `blocking="render"` — opt into render-blocking (default for classic stylesheets in head).
* `nonce` / CSP hashes — allow inline under strict CSP.
* `title` — alternate stylesheets (with `<link rel="stylesheet" title>`).

### Cascade and importance (simplified) [#cascade-and-importance-simplified]

1. Origin & importance (user agent \< user \< author; `!important` reverses layers carefully)
2. Specificity (`inline` > IDs > classes/attributes > elements)
3. Order (later wins when equal)

### Accessibility of presentation [#accessibility-of-presentation]

* Do not rely on color alone.
* Preserve focus visibility.
* Respect `prefers-reduced-motion` and `prefers-color-scheme`.
* Maintain contrast (WCAG).
* Keep hit targets large enough.

## 💡 Examples [#-examples]

### Critical CSS in head [#critical-css-in-head]

```html
<head>
  <style>
    body { margin: 0; font-family: system-ui, sans-serif; }
    .hero { min-height: 60vh; }
  </style>
  <link rel="stylesheet" href="/full.css">
</head>
```

### Media-specific style block [#media-specific-style-block]

```html
<style media="print">
  nav, .no-print { display: none; }
  a[href]::after { content: " (" attr(href) ")"; }
</style>
```

### Theming with custom properties [#theming-with-custom-properties]

```html
<style>
  :root {
    --bg: #f8fafc;
    --fg: #0f172a;
    --accent: #0f766e;
  }
  @media (prefers-color-scheme: dark) {
    :root {
      --bg: #0f172a;
      --fg: #f8fafc;
    }
  }
  body {
    background: var(--bg);
    color: var(--fg);
  }
</style>
```

### Dynamic inline style from script [#dynamic-inline-style-from-script]

```html
<div id="bar" role="progressbar" aria-valuenow="40" aria-valuemin="0" aria-valuemax="100">
  <span class="fill"></span>
</div>
<script type="module">
  const fill = document.querySelector("#bar .fill");
  fill.style.width = "40%";
  fill.style.background = "var(--accent)";
</script>
```

## ⚠️ Pitfalls [#️-pitfalls]

* **Inline everything** — Unmaintainable; breaks theming and CSP ease.
* **`!important` sprawl** — Sign of specificity fights; refactor selectors.
* **Removing focus outlines** — Provide `:focus-visible` alternatives.
* **Using CSS for content** — Important text in `content:` may be missed by AT/translators.
* **FOUC** — Late stylesheets flash unstyled content; order and preload carefully.
* **Mixing presentational HTML** — `<font>`, `align`, `bgcolor` are obsolete; use CSS.
* **Huge style tags** — Defeat caching; extract to files for multi-page sites.

## 🔗 Related [#-related]

* [Head](/docs/html/head) — linking stylesheets
* [Div](/docs/html/div) — layout hooks for CSS
* [Script](/docs/html/script) — load order with JS
* [Meta](/docs/html/meta) — `color-scheme`, theme-color
* [Media](/docs/html/media) — styling images/video (`object-fit`)
* [Canvas](/docs/html/canvas) — CSS size vs bitmap size
* [Section](/docs/html/section) — styling landmarks


# Inline SVG (/docs/html/svg-inline)



# Inline SVG [#inline-svg]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Inline SVG embeds vector graphics directly in HTML for crisp icons, illustrations, and charts. You can style with CSS, animate, and expose titles for accessibility. Prefer `<img src="*.svg">` or `<use>` sprites when you don’t need per-path styling.

## 🔧 Core concepts [#-core-concepts]

* **Root**: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">`.
* **`viewBox`**: coordinate system; scales independently of `width`/`height`.
* **Shapes**: `path` `rect` `circle` `line` `polyline` `polygon` `text` `g`.
* **CSS**: `fill`, `stroke`, `currentColor` for themeable icons.
* **A11y**: decorative → `aria-hidden="true"`; meaningful → `<title>` + `role="img"` / `aria-label`.
* **Sprites**: `<use href="/icons.svg#check">` (external `use` has CORS limits).

```html
<svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true" focusable="false">
  <path fill="currentColor" d="M9 16.17 4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z" />
</svg>
```

## 💡 Examples [#-examples]

```html
<!-- Meaningful graphic -->
<svg role="img" aria-labelledby="salesTitle" viewBox="0 0 100 40" width="300">
  <title id="salesTitle">Sales rising from 10 to 40</title>
  <polyline
    fill="none"
    stroke="currentColor"
    stroke-width="3"
    points="0,30 30,22 60,18 100,5"
  />
</svg>

<!-- Icon button -->
<button type="button" aria-label="Settings">
  <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24" width="20" height="20">
    <path fill="currentColor" d="..." />
  </svg>
</button>

<!-- Style -->
<style>
  .icon {
    width: 1.25rem;
    height: 1.25rem;
    display: block;
  }
  .icon-danger {
    color: crimson;
  }
</style>

<!-- Sprite use -->
<svg class="icon" aria-hidden="true" focusable="false">
  <use href="/sprite.svg#arrow" />
</svg>
```

```html
<!-- Prefer currentColor over hardcoded fills for theming -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* Huge inline SVGs bloat HTML — externalize complex art.
* Missing `viewBox` breaks scaling.
* Interactive SVG needs keyboard support if it acts like a control — wrap in `button`/`a` instead.
* `focusable="false"` helps older IE/Edge; still set `aria-hidden` on decorative icons.
* XSS: never inline unsanitized SVG from users (`<script>`, event handlers).

## 🔗 Related [#-related]

* [images.md](/docs/html/images) — raster images
* [canvas.md](/docs/html/canvas) — canvas alternative
* [accessibility.md](/docs/html/accessibility) — graphics a11y
* [../CSS/icon.md](/docs/html/../css/icon) — icon CSS
* [embedding.md](/docs/html/embedding) — object/embed


# Table (/docs/html/table)



# Table [#table]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `<table>` element represents **tabular data**—information arranged in rows and columns. Use tables for data relationships, not for page layout (CSS Grid/Flexbox replaced that anti-pattern). Accessible tables need captions, clear headers, and `scope` (or explicit `headers` IDs) so assistive technologies can announce cell context.

Core pieces: `<table>`, `<caption>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>`, plus `<colgroup>` / `<col>` for column styling.

## 🔧 Core concepts [#-core-concepts]

### Basic structure [#basic-structure]

```html
<table>
  <caption>Quarterly revenue (USD thousands)</caption>
  <thead>
    <tr>
      <th scope="col">Quarter</th>
      <th scope="col">Revenue</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Q1</th>
      <td>40</td>
    </tr>
    <tr>
      <th scope="row">Q2</th>
      <td>55</td>
    </tr>
  </tbody>
</table>
```

### Header cells and scope [#header-cells-and-scope]

| `scope`    | Meaning                   |
| ---------- | ------------------------- |
| `col`      | Header for the column     |
| `row`      | Header for the row        |
| `colgroup` | Header for a column group |
| `rowgroup` | Header for a row group    |

Complex tables may use `headers="id1 id2"` on `<td>` pointing to `id`s on `<th>`.

### Sections [#sections]

* `<thead>` — column labels (can repeat when printing).
* `<tbody>` — main data (multiple allowed).
* `<tfoot>` — summaries; may appear before `tbody` in markup for streaming, still rendered at bottom in some cases—follow current HTML guidance and test.

### Spanning [#spanning]

* `colspan` — extend across columns
* `rowspan` — extend across rows\
  Keep spans minimal; they complicate a11y and responsive redesigns.

### When not to use tables [#when-not-to-use-tables]

Layout grids, email-only legacy layouts (sometimes unavoidable), and simple key/value pairs (consider `<dl>`) should not force data-table semantics.

## 💡 Examples [#-examples]

### Table with footer totals [#table-with-footer-totals]

```html
<table>
  <caption>Hardware inventory</caption>
  <thead>
    <tr>
      <th scope="col">Item</th>
      <th scope="col">Qty</th>
      <th scope="col">Unit price</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">Keyboard</th>
      <td>12</td>
      <td>40</td>
    </tr>
    <tr>
      <th scope="row">Mouse</th>
      <td>20</td>
      <td>25</td>
    </tr>
  </tbody>
  <tfoot>
    <tr>
      <th scope="row">Total units</th>
      <td colspan="2">32</td>
    </tr>
  </tfoot>
</table>
```

### Irregular headers with `headers` [#irregular-headers-with-headers]

```html
<table>
  <caption>Exam scores</caption>
  <tr>
    <td></td>
    <th id="mid" scope="col">Midterm</th>
    <th id="fin" scope="col">Final</th>
  </tr>
  <tr>
    <th id="ada" scope="row">Ada</th>
    <td headers="ada mid">92</td>
    <td headers="ada fin">88</td>
  </tr>
</table>
```

### Scrollable responsive wrapper [#scrollable-responsive-wrapper]

```html
<div class="table-scroll" tabindex="0" role="region" aria-label="Revenue table">
  <table>…</table>
</div>
```

```css
.table-scroll { overflow-x: auto; max-width: 100%; }
```

### Sortable header button (progressive) [#sortable-header-button-progressive]

```html
<th scope="col">
  <button type="button" aria-label="Sort by name ascending">
    Name
  </button>
</th>
```

Keep the `<th>` semantics; enhance with script without replacing the table with divs.

## ⚠️ Pitfalls [#️-pitfalls]

* **Layout tables** — Break reflow, reading order, and CSS flexibility.
* **Missing caption / headers** — Screen readers announce raw grids without context.
* **Only bold text as headers** — Use `<th>`, not styled `<td>`.
* **Empty header cells** — Provide meaningful labels or `abbr`.
* **Too many spans** — Hard to navigate linearly.
* **Clickable rows without keyboard support** — Prefer links/buttons inside cells.
* **CSS `display` changes** — Altering table `display` can destroy a11y mappings in some browsers—test.

## 🔗 Related [#-related]

* [List](/docs/html/list) — alternative for non-tabular sets
* [Section](/docs/html/section) — wrapping data sections
* [Div](/docs/html/div) — scroll wrappers
* [Form](/docs/html/form) — inputs inside table cells
* [Input](/docs/html/input) — editable grids
* [Canvas](/docs/html/canvas) — charts vs data tables (provide both)
* [Style](/docs/html/style) — table layout CSS


# Template & Slot (/docs/html/template-slot)



# Template & Slot [#template--slot]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`<template>` holds inert DOM that isn’t rendered until cloned with script. `<slot>` (inside Shadow DOM) projects light-DOM children into shadow trees. Together they power Web Components and client-side rendering patterns without displaying markup prematurely.

## 🔧 Core concepts [#-core-concepts]

* **`<template>`**: `template.content` is a `DocumentFragment`; clone with `cloneNode(true)`.
* **Inert**: scripts/styles/images inside don’t run until adopted into a live document.
* **`<slot>`**: placeholder in shadow root; default content inside slot shows if nothing assigned.
* **Named slots**: `<slot name="title">` ↔ `slot="title"` on light children.
* **Assignment**: automatic or `slotAssignment: "manual"` + `slot.assign()`.
* **`slotchange` event**: fires when assigned nodes change.

```html
<template id="row">
  <li class="row"><span class="name"></span></li>
</template>

<script>
  const tpl = document.getElementById("row");
  const node = tpl.content.cloneNode(true);
  node.querySelector(".name").textContent = "Ada";
  list.append(node);
</script>
```

## 💡 Examples [#-examples]

```html
<!-- Component with slots -->
<script>
  class UserCard extends HTMLElement {
    constructor() {
      super();
      this.attachShadow({ mode: "open" }).innerHTML = `
        <style>::slotted(img){width:48px;border-radius:50%}</style>
        <slot name="avatar"></slot>
        <h2><slot name="name">Anonymous</slot></h2>
        <div><slot></slot></div>
      `;
    }
  }
  customElements.define("user-card", UserCard);
</script>

<user-card>
  <img slot="avatar" src="/a.jpg" alt="" />
  <span slot="name">Ada Lovelace</span>
  <p>Mathematician</p>
</user-card>

<!-- Manual assignment -->
<script>
  const shadow = host.attachShadow({ mode: "open", slotAssignment: "manual" });
  shadow.innerHTML = `<slot></slot>`;
  shadow.querySelector("slot").assign(...host.children);
</script>

<!-- slotchange -->
<script>
  shadow.querySelector("slot").addEventListener("slotchange", (e) => {
    console.log(e.target.assignedNodes());
  });
</script>
```

```html
<!-- Clone for each list item; never append template.content directly -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `cloneNode(true)` and moving `template.content` empties the template after first use — always clone.
* Slots only work in Shadow DOM — not in light DOM alone.
* Fallback slot content is not light DOM — don’t expect to query it as children of the host.
* Scripts inside live-cloned templates will run — sanitize untrusted HTML.
* Named slot mismatch leaves content unprojected (still in light DOM).

## 🔗 Related [#-related]

* [web\_components.md](/docs/html/web-components) — full stack
* [../Javascript/DOM/shadow\_dom.md](/docs/html/../javascript/dom/shadow-dom) — shadow trees
* [../Javascript/DOM/custom\_elements.md](/docs/html/../javascript/dom/custom-elements) — custom elements
* [script.md](/docs/html/script) — script loading
* [semantic.md](/docs/html/semantic) — light DOM structure


# URL (/docs/html/url)



# URL [#url]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

URLs (Uniform Resource Locators) identify resources in HTML attributes such as `href`, `src`, `action`, and `cite`. Authors work with absolute URLs, root-relative paths, document-relative paths, and special schemes (`mailto:`, `tel:`, `data:`, `blob:`). Correct encoding, HTTPS, and stable canonical URLs matter for security, SEO, and broken-link prevention.

The browser resolves relative references against the active document base URL (affected by `<base>`).

## 🔧 Core concepts [#-core-concepts]

### Anatomy [#anatomy]

```
https://user:pass@example.com:443/path/to/page?query=1#fragment
\___/   \_______/ \_________/ \__/ \_________/ \_____/ \______/
scheme  userinfo   host       port  path        query   fragment
```

In modern web apps, prefer HTTPS, avoid embedding credentials in URLs, and keep fragments client-side only (not sent to servers).

### Forms used in HTML [#forms-used-in-html]

| Form              | Example                        | Resolves to                                       |
| ----------------- | ------------------------------ | ------------------------------------------------- |
| Absolute          | `https://cdn.example.com/a.js` | As written                                        |
| Root-relative     | `/images/logo.png`             | Origin + path                                     |
| Document-relative | `../assets/app.css`            | Relative to current URL path                      |
| Protocol-relative | `//cdn.example.com/x`          | Inherit current scheme (avoid; prefer `https://`) |
| Same-document     | `#section`                     | Fragment only                                     |
| Special           | `mailto:hi@ex.com`             | Handled by OS/UA                                  |

### Encoding [#encoding]

* Encode spaces and reserved characters in paths/queries (`encodeURIComponent` for components).
* Use `%20` or `+` in query strings per server expectations.
* Internationalized domains use Punycode; paths may be Unicode but encoding is safer for interoperability.

### HTML attributes that take URLs [#html-attributes-that-take-urls]

* Navigation: `a.href`, `area.href`, `base.href`, `link.href`
* Resources: `img.src`, `script.src`, `iframe.src`, `source.src`, `track.src`
* Forms: `form.action`
* Misc: `blockquote.cite`, `q.cite`, `html.manifest` (obsolete)

### Canonicalization and SEO [#canonicalization-and-seo]

```html
<link rel="canonical" href="https://example.com/docs/url">
```

Pick one preferred host (`www` vs apex), trailing-slash policy, and HTTPS redirect chain. Pair with `hreflang` alternates when localized.

## 💡 Examples [#-examples]

### Relative vs absolute in links [#relative-vs-absolute-in-links]

```html
<nav>
  <a href="/">Home</a>
  <a href="/docs/html/forms">Forms</a>
  <a href="https://developer.mozilla.org/">MDN</a>
  <a href="#pitfalls">On this page</a>
</nav>
```

### Form GET builds a query URL [#form-get-builds-a-query-url]

```html
<form action="/search" method="get">
  <label for="q">Search</label>
  <input id="q" name="q" type="search" value="semantic html">
  <button type="submit">Go</button>
</form>
<!-- Submits to /search?q=semantic+html -->
```

### Safe external link pattern [#safe-external-link-pattern]

```html
<a href="https://example.com/partner"
   rel="noopener noreferrer"
   target="_blank">
  Partner site
</a>
```

`noopener` protects `window.opener`; `noreferrer` also omits referrer (trade-offs for analytics).

### Data and blob URLs [#data-and-blob-urls]

```html
<img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'%3E%3C/%3E" alt="">
```

Prefer files for large assets; data URLs bloat HTML and cache poorly.

## ⚠️ Pitfalls [#️-pitfalls]

* **Broken relative links** after moving pages—root-relative paths are stabler for apps.
* **`<base href>`** rewriting every relative URL unexpectedly.
* **Open redirects** — never bounce users to unchecked query params.
* **Credentials in URLs** — leak via history, logs, and Referer.
* **Mixed content** — HTTP resources on HTTPS pages fail or warn.
* **Unescaped `&` in query strings within HTML** — write `&amp;` in HTML attributes.
* **Assuming fragments reach the server** — they do not on normal navigations.

## 🔗 Related [#-related]

* [Src](/docs/html/src) — resource URL attributes
* [Head](/docs/html/head) — canonical and base
* [Form](/docs/html/form) — `action` and method
* [Media](/docs/html/media) — media resource URLs
* [Nav](/docs/html/nav) — in-site link patterns
* [Language](/docs/html/language) — locale in paths / hreflang
* [Meta](/docs/html/meta) — OG URLs
* [XML](/docs/html/xml) — XML Base / namespaces


# Video & Audio (/docs/html/video-audio)



# Video & Audio [#video--audio]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`<video>` and `<audio>` embed media with native controls, multiple `<source>` fallbacks, tracks for captions, and a rich DOM API. Prefer native elements for accessibility and performance; use `controls`, captions, and sensible preload defaults.

## 🔧 Core concepts [#-core-concepts]

| Attribute                    | Role                     |
| ---------------------------- | ------------------------ |
| `src` / `<source>`           | media URL(s)             |
| `controls`                   | show UA controls         |
| `autoplay`                   | may play muted only      |
| `muted` `loop` `playsinline` | playback flags           |
| `preload`                    | `none` `metadata` `auto` |
| `poster`                     | video placeholder image  |
| `width` `height`             | video layout             |
| `crossorigin`                | CORS for WebGL/canvas    |

* **Tracks**: `<track kind="captions" srclang="en" src="..." default>`.
* **API**: `play()`, `pause()`, `currentTime`, `volume`, events `play` `pause` `ended` `error`.
* **Formats**: provide multiple sources (e.g. MP4 + WebM) when needed.

```html
<video controls playsinline poster="/poster.jpg" width="1280" height="720">
  <source src="/demo.webm" type="video/webm" />
  <source src="/demo.mp4" type="video/mp4" />
  <track kind="captions" srclang="en" src="/demo.vtt" label="English" default />
  Download the <a href="/demo.mp4">video</a>.
</video>
```

## 💡 Examples [#-examples]

```html
<audio controls preload="metadata">
  <source src="/episode.mp3" type="audio/mpeg" />
  <source src="/episode.ogg" type="audio/ogg" />
</audio>

<video
  controls
  muted
  loop
  autoplay
  playsinline
  aria-label="Product animation"
>
  <source src="/loop.mp4" type="video/mp4" />
</video>

<script>
  const v = document.querySelector("video");
  btn.onclick = async () => {
    try {
      await v.play();
    } catch {
      /* autoplay blocked */
    }
  };
  v.addEventListener("error", () => console.error(v.error));
</script>
```

```html
<!-- Picture-in-picture / fullscreen via controls or JS APIs -->
```

## ⚠️ Pitfalls [#️-pitfalls]

* Autoplay with sound is blocked — mute or require a gesture.
* Missing captions fails accessibility for dialogue-heavy video.
* `preload="auto"` can waste bandwidth — prefer `metadata`/`none` on listing pages.
* Cross-origin media without CORS taints canvas draws.
* Don’t rely on Flash-era embeds — use native or modern players built on these elements.

## 🔗 Related [#-related]

* [media.md](/docs/html/media) — media overview
* [picture\_source.md](/docs/html/picture-source) — source selection
* [iframe.md](/docs/html/iframe) — third-party players
* [accessibility.md](/docs/html/accessibility) — captions
* [../CSS/object\_fit.md](/docs/html/../css/object-fit) — cover/contain


# Web Components (/docs/html/web-components)



# Web Components [#web-components]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Web Components combine Custom Elements, Shadow DOM, and HTML templates/slots into reusable, framework-agnostic widgets. Define a class, register a tag with a hyphenated name, encapsulate markup/styles in a shadow root, and project content with slots.

## 🔧 Core concepts [#-core-concepts]

| Piece                   | Role                                   |
| ----------------------- | -------------------------------------- |
| Custom Elements         | `customElements.define("x-el", Class)` |
| Shadow DOM              | style/DOM encapsulation                |
| `<template>` / `<slot>` | markup reuse & projection              |
| CSS `::part` / vars     | controlled theming                     |
| ES modules              | load component definitions             |

* Lifecycle: `constructor`, `connectedCallback`, `disconnectedCallback`, `attributeChangedCallback`.
* Form-associated custom elements can participate in forms (ElementInternals).
* Progressive enhancement: unknown elements render light DOM children until upgraded.

```html
<script type="module">
  class CoolBadge extends HTMLElement {
    constructor() {
      super();
      this.attachShadow({ mode: "open" }).innerHTML = `
        <style>:host{display:inline-pad;padding:.2em .5em;background:var(--badge-bg, #eee)}</style>
        <slot></slot>
      `;
    }
  }
  customElements.define("cool-badge", CoolBadge);
</script>
<cool-badge>Beta</cool-badge>
```

## 💡 Examples [#-examples]

```html
<template id="tooltip-tpl">
  <style>
    :host {
      position: relative;
    }
    .tip {
      display: none;
      position: absolute;
      ...;
    }
    :host(:hover) .tip,
    :host(:focus-within) .tip {
      display: block;
    }
  </style>
  <slot></slot>
  <div class="tip" part="tip"><slot name="tip"></slot></div>
</template>

<script type="module">
  const tpl = document.getElementById("tooltip-tpl");
  class XTooltip extends HTMLElement {
    constructor() {
      super();
      this.attachShadow({ mode: "open" }).append(tpl.content.cloneNode(true));
    }
  }
  customElements.define("x-tooltip", XTooltip);
</script>

<!-- Theming from outside -->
<style>
  x-tooltip {
    --badge-bg: #224;
  }
  x-tooltip::part(tip) {
    border-radius: 6px;
  }
</style>
```

```js
await customElements.whenDefined("cool-badge");
```

## ⚠️ Pitfalls [#️-pitfalls]

* Customized built-ins (`is="..."`) lack full cross-browser support — prefer autonomous elements.
* Closed shadow roots aren’t secure — don’t hide secrets there.
* Slotted content is styled with limited `::slotted` — complex styling may need parts/vars.
* SSR/hydration needs care — unknown elements flash unstyled without declarative shadow DOM strategies.
* Avoid huge shadow trees for simple static HTML — semantics first.

## 🔗 Related [#-related]

* [template\_slot.md](/docs/html/template-slot) — template & slot
* [../Javascript/DOM/custom\_elements.md](/docs/html/../javascript/dom/custom-elements) — element API
* [../Javascript/DOM/shadow\_dom.md](/docs/html/../javascript/dom/shadow-dom) — shadow API
* [accessibility.md](/docs/html/accessibility) — a11y in components
* [aria.md](/docs/html/aria) — ARIA when needed


# XML (/docs/html/xml)



# XML [#xml]

*HTML · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**XML** (Extensible Markup Language) is a strict, generic markup language for structured data. **HTML5** is an SGML-inspired living standard with its own parsing rules—far more forgiving than XML. Authors sometimes meet XML via XHTML serialization, SVG/MathML embedded in HTML, sitemaps, RSS/Atom, or app config files.

This sheet contrasts XML rules with HTML practice and covers when polyglot markup, namespaces, and well-formedness matter in web documents.

## 🔧 Core concepts [#-core-concepts]

### Well-formedness (XML) [#well-formedness-xml]

XML documents must be well-formed:

* Single root element
* Properly nested tags
* Attribute values quoted
* Case-sensitive names
* Empty elements written as `<tag/>` or `<tag>&lt;/tag>`
* Special characters escaped: `&amp;` `&lt;` `&gt;` `&quot;` `&apos;`
* Optional XML declaration: `&lt;?xml version="1.0" encoding="UTF-8"?>`

HTML parsers auto-correct many errors; XML parsers **fail fatally** on malformed input.

### HTML vs XHTML [#html-vs-xhtml]

| Topic        | HTML5 (text/html)            | XHTML / XML               |
| ------------ | ---------------------------- | ------------------------- |
| MIME         | `text/html`                  | `application/xhtml+xml`   |
| Void tags    | `<br>` ok                    | `<br/>` or `<br>&lt;/br>` |
| Omitted tags | Often allowed                | Never                     |
| Namespaces   | Limited magic for SVG/MathML | Explicit `xmlns`          |
| Script/CSS   | Special CDATA-like rules     | Must respect XML escaping |

Serving XHTML as `text/html` makes browsers use the HTML parser—XML rules are not enforced.

### Namespaces [#namespaces]

```xml
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24">
  <circle cx="12" cy="12" r="10" fill="currentColor"/>
</svg>
```

In HTML5, inline SVG and MathML are parsed with namespace awareness. Custom elements use different rules (no XML namespaces required).

### `xml:lang` and `lang` [#xmllang-and-lang]

In HTML, prefer `lang`. In XML vocabularies, `xml:lang` is standard. Polyglot documents may include both with identical values.

### Embedding XML-ish content in HTML [#embedding-xml-ish-content-in-html]

* **SVG / MathML** — first-class in HTML5.
* **Foreign data** — often JSON in `<script type="application/json">` instead of inline XML.
* **`XHTML` self-closing** — in `text/html`, trailing slashes on void elements are ignored noise; on non-void elements they can create surprising DOM trees—avoid casual `/>` on `<div/>`.

## 💡 Examples [#-examples]

### Minimal well-formed XML [#minimal-well-formed-xml]

```xml
<?xml version="1.0" encoding="UTF-8"?>
<note>
  <to>Ada</to>
  <from>Grace</from>
  <message>Ship the spec.</message>
</note>
```

### Inline SVG in HTML [#inline-svg-in-html]

```html
<figure>
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" role="img" aria-label="Green circle">
    <circle cx="50" cy="50" r="40" fill="#0f766e"/>
  </svg>
  <figcaption>Decorative brand mark</figcaption>
</figure>
```

### Atom feed snippet [#atom-feed-snippet]

```xml
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Docs updates</title>
  <link href="https://example.com/feed.xml" rel="self"/>
  <updated>2026-07-10T12:00:00Z</updated>
  <entry>
    <title>Forms cheat sheet</title>
    <link href="https://example.com/html/form"/>
    <id>urn:uuid:1234</id>
    <updated>2026-07-10T12:00:00Z</updated>
  </entry>
</feed>
```

### Polyglot-minded void elements [#polyglot-minded-void-elements]

```html
<!-- Safe in both HTML and XHTML serializations -->
<meta charset="utf-8"/>
<link rel="stylesheet" href="/app.css"/>
<img src="/logo.svg" alt="Acme"/>
<br/>
```

Still serve HTML as `text/html` unless you intentionally need XML tooling.

## ⚠️ Pitfalls [#️-pitfalls]

* **Assuming HTML is XML** — Unclosed `<p>` or `<li>` may “work” in HTML and break XML pipelines.
* **`innerHTML` with XML strings** — HTML parser rules apply in the DOM, not XML rules.
* **Namespace typos** — Wrong SVG `xmlns` yields elements in the wrong namespace (no rendering).
* **Raw `&` in XML** — Must escape; HTML text content is also safer escaped.
* **XHTML MIME without error handling** — A single error blank-screens the page in XML mode.
* **`document.write` / copy-paste XHTML** — Self-closing non-void tags in HTML create empty elements and orphaned children.

## 🔗 Related [#-related]

* [Head](/docs/html/head) — document prologue vs XML declaration
* [Language](/docs/html/language) — `lang` / `xml:lang`
* [Meta](/docs/html/meta) — charset related to encoding declarations
* [URL](/docs/html/url) — XML Base concepts
* [Media](/docs/html/media) — SVG as image `src`
* [Script](/docs/html/script) — JSON data blocks vs XML
* [Style](/docs/html/style) — styling SVG embedded in HTML


# Async (/docs/jest/async)



# Async [#async]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Jest supports promises, async/await, and callbacks (`done`). Prefer returning/awaiting promises; use `.resolves` / `.rejects` matchers for clarity.

## 🔧 Core concepts [#-core-concepts]

| Style            | Pattern                              |
| ---------------- | ------------------------------------ |
| async/await      | `await` inside `test`                |
| Promise return   | `return fetch().then(...)`           |
| resolves/rejects | `await expect(p).resolves.toBe(...)` |
| done             | Legacy callbacks — avoid if possible |
| Fake timers      | Interact carefully with promises     |

Unhandled rejections fail the test when properly awaited.

## 💡 Examples [#-examples]

**async/await:**

```js
test('loads user', async () => {
  const user = await api.getUser(1);
  expect(user.id).toBe(1);
});
```

**resolves / rejects:**

```js
await expect(api.getUser(1)).resolves.toMatchObject({ id: 1 });
await expect(api.getUser(-1)).rejects.toThrow(/not found/);
await expect(api.getUser(-1)).rejects.toMatchObject({ status: 404 });
```

**Promise return (no async):**

```js
test('ok', () => {
  return api.ping().then((r) => expect(r).toBe('pong'));
});
```

**Timeouts:**

```js
test('slow', async () => {
  await longJob();
}, 15_000);
```

**Concurrent (Jest 29+):**

```js
test.concurrent('a', async () => { /* ... */ });
test.concurrent('b', async () => { /* ... */ });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `await` / `return` → false green tests.
* Mixing `done` with promises incorrectly.
* Asserting before microtasks flush — await or `await Promise.resolve()`.
* Fake timers + real promises deadlocks without `advanceTimers`.
* Swallowing errors in try/catch without rethrow/expect.

## 🔗 Related [#-related]

* [Matchers](/docs/jest/matchers)
* [Timers](/docs/jest/timers)
* [Mocks](/docs/jest/mocks)
* [Spies](/docs/jest/spies)
* [Setup & teardown](/docs/jest/setup-teardown)
* [React Testing Library](/docs/jest/react-testing-library)


# Config (/docs/jest/config)



# Config [#config]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Configure Jest via `jest.config.js/ts` or `package.json#jest`. Key knobs: environment, transforms, roots, coverage, and setup files.

## 🔧 Core concepts [#-core-concepts]

| Option                | Purpose                  |
| --------------------- | ------------------------ |
| `testEnvironment`     | `node` \| `jsdom`        |
| `roots` / `testMatch` | Discovery                |
| `transform`           | TS/JS compile            |
| `moduleNameMapper`    | Aliases / CSS mocks      |
| `setupFilesAfterEnv`  | Matchers, RTL            |
| `collectCoverageFrom` | Coverage scope           |
| `clearMocks`          | Auto clear between tests |

## 💡 Examples [#-examples]

**jest.config.js:**

```js
/** @type {import('jest').Config} */
module.exports = {
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: ['**/__tests__/**/*.test.ts'],
  clearMocks: true,
  collectCoverageFrom: ['src/**/*.{ts,tsx}', '!src/**/*.d.ts'],
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '\\.(css|less)$': 'identity-obj-proxy',
  },
  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
};
```

**React / jsdom:**

```js
testEnvironment: 'jsdom',
```

**package.json scripts:**

```json
{
  "scripts": {
    "test": "jest",
    "test:ci": "jest --ci --coverage --maxWorkers=2"
  }
}
```

**CLI overrides:**

```shellscript
npx jest --config=jest.config.js
npx jest --env=jsdom
npx jest --runInBand
```

## ⚠️ Pitfalls [#️-pitfalls]

* Path aliases in TS not mirrored in `moduleNameMapper`.
* Transforming `node_modules` accidentally (slow) or not transforming ESM deps.
* Multiple configs in monorepos without projects/`--selectProjects`.
* `jsdom` for pure Node libraries — unnecessary overhead.
* Coverage thresholds failing CI without local awareness.

## 🔗 Related [#-related]

* [Install](/docs/jest/install)
* [TypeScript](/docs/jest/typescript)
* [Coverage](/docs/jest/coverage)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Module mocks](/docs/jest/module-mocks)
* [Watch mode](/docs/jest/watch-mode)


# Coverage (/docs/jest/coverage)



# Coverage [#coverage]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Jest ships coverage via Istanbul/V8 providers. Collect with `--coverage`, set thresholds, and emit HTML/LCOV for CI.

## 🔧 Core concepts [#-core-concepts]

| Option                | Role             |
| --------------------- | ---------------- |
| `--coverage`          | Enable           |
| `collectCoverageFrom` | Include globs    |
| `coverageThreshold`   | Fail under %     |
| `coverageProvider`    | `babel` \| `v8`  |
| `coverageReporters`   | html, text, lcov |

Ignore generated files and stories in `coveragePathIgnorePatterns`.

## 💡 Examples [#-examples]

**CLI:**

```shellscript
npx jest --coverage
npx jest --coverage --collectCoverageFrom='src/**/*.{ts,tsx}'
```

**Config thresholds:**

```js
module.exports = {
  collectCoverageFrom: [
    'src/**/*.{js,jsx,ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/*.stories.*',
  ],
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },
  coverageReporters: ['text', 'lcov', 'html'],
};
```

**CI:**

```shellscript
npx jest --ci --coverage --maxWorkers=2
```

Open `coverage/lcov-report/index.html` locally.

## ⚠️ Pitfalls [#️-pitfalls]

* Inflated coverage from trivial barrel files.
* V8 vs babel provider differences on ignored lines.
* Thresholds on empty suites passing vacuously.
* Not gitignoring `coverage/`.
* Collecting from `dist/` instead of `src/`.

## 🔗 Related [#-related]

* [Config](/docs/jest/config)
* [Watch mode](/docs/jest/watch-mode)
* [Install](/docs/jest/install)
* [TypeScript](/docs/jest/typescript)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Migration to Vitest](/docs/jest/migration-vitest)


# Custom Matchers (/docs/jest/custom-matchers)



# Custom Matchers [#custom-matchers]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Extend `expect` with domain matchers via `expect.extend`. Ship them from `setupFilesAfterEnv` so every test can use readable assertions.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                    |
| --------------- | ----------------------- |
| `expect.extend` | Register matchers       |
| `this.isNot`    | Negation support        |
| `this.utils`    | Diff / print helpers    |
| TypeScript      | Augment `jest.Matchers` |
| jest-dom        | Ready-made DOM matchers |

Return `\{ pass, message \}` from matcher functions.

## 💡 Examples [#-examples]

**Define:**

```js
// matchers/toBeWithinRange.js
expect.extend({
  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        pass
          ? `expected ${received} not to be within ${floor}-${ceiling}`
          : `expected ${received} to be within ${floor}-${ceiling}`,
    };
  },
});
```

**Setup:**

```js
// jest.setup.js
require('./matchers/toBeWithinRange');
```

**Use:**

```js
expect(100).toBeWithinRange(90, 110);
expect(50).not.toBeWithinRange(90, 110);
```

**TypeScript declaration:**

```ts
declare global {
  namespace jest {
    interface Matchers<R> {
      toBeWithinRange(floor: number, ceiling: number): R;
    }
  }
}
export {};
```

**Async matchers:** return a Promise of `\{ pass, message \}` for `.resolves` chains when needed.

## ⚠️ Pitfalls [#️-pitfalls]

* Mutating global expect without setup file — matchers missing in some workers.
* Poor `message` functions making failures opaque.
* Ignoring `this.isNot` leading to wrong negation text.
* Conflicting matcher names with jest-dom.
* Forgetting to export types for TS projects.

## 🔗 Related [#-related]

* [Matchers](/docs/jest/matchers)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Config](/docs/jest/config)
* [React Testing Library](/docs/jest/react-testing-library)
* [Snapshots](/docs/jest/snapshots)
* [TypeScript](/docs/jest/typescript)


# Glossary (/docs/jest/glossary)



# Glossary [#glossary]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core Jest terms for matchers, mocks, lifecycle hooks, snapshots, and test configuration.

## 🔧 Core concepts [#-core-concepts]

| Term             | Definition                                                                            |
| ---------------- | ------------------------------------------------------------------------------------- |
| AfterAll         | A hook that runs once after all tests in a file or `describe` finish.                 |
| AfterEach        | A hook that runs after every test in the current scope.                               |
| BeforeAll        | A hook that runs once before any tests in a file or `describe` start.                 |
| BeforeEach       | A hook that runs before every test in the current scope.                              |
| Coverage         | A report of which statements/branches tests executed.                                 |
| Describe         | A block that groups related tests under a shared name.                                |
| Each             | A helper (`test.each` / `describe.each`) that table-drives repeated cases.            |
| Expect           | The assertion entry point that chains matchers onto a value.                          |
| Fake timers      | Mocked clock APIs that let tests advance time manually.                               |
| Fn               | `jest.fn()`, the factory for mock functions.                                          |
| Hoisting         | Jest’s behavior of lifting `jest.mock` calls to the top of a module.                  |
| It / test        | A single test case function registered with Jest.                                     |
| Matcher          | An assertion method such as `toBe`, `toEqual`, or `toHaveBeenCalled`.                 |
| Mock             | A stand-in function or module that records calls and controls returns.                |
| Module mock      | Replacing an imported module with a mock via `jest.mock`.                             |
| Only / skip      | Focusing (`.only`) or excluding (`.skip`) specific suites or tests.                   |
| Setup file       | A file run before the test framework is installed in each environment.                |
| Snapshot         | A serialized output stored on disk and compared on later runs.                        |
| Spy              | A wrapper around a real function that records calls while optionally calling through. |
| Suite            | A group of tests, typically created by a `describe` block.                            |
| Test environment | The runtime context such as `node` or `jsdom` for each test file.                     |
| Test runner      | The component that discovers files and executes suites.                               |
| Timeout          | The maximum duration a test may run before Jest fails it.                             |
| Transformer      | A preprocessor (often Babel/ts-jest) that compiles files before tests.                |
| Watch mode       | A continuous mode that re-runs affected tests on file changes.                        |

## 💡 Examples [#-examples]

**Describe, test, and matchers:**

```js
describe("sum", () => {
  test("adds numbers", () => {
    expect(1 + 2).toBe(3);
    expect({ a: 1 }).toEqual({ a: 1 });
  });
});
```

**Mocks and spies:**

```js
const fetchUser = jest.fn().mockResolvedValue({ id: 1 });
const log = jest.spyOn(console, "log").mockImplementation(() => {});

await fetchUser(1);
expect(fetchUser).toHaveBeenCalledWith(1);
log.mockRestore();
```

**Lifecycle hooks:**

```js
beforeEach(() => {
  jest.clearAllMocks();
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing &#x2A;*`toBe`*&#x2A; (reference/primitive identity) with &#x2A;*`toEqual`** (deep value equality).
* Mixing **mock** (full replacement) with **spy** (wrap existing implementation).
* Treating **snapshot** failures as always product bugs — snapshots need intentional updates.
* Equating **fake timers** with real delays — you must advance timers explicitly.
* Assuming **clearAllMocks** resets implementations the same way **resetAllMocks** does.

## 🔗 Related [#-related]

* [matchers](/docs/jest/matchers)
* [mocks](/docs/jest/mocks)
* [spies](/docs/jest/spies)
* [setup\_teardown](/docs/jest/setup-teardown)
* [snapshots](/docs/jest/snapshots)
* [watch\_mode](/docs/jest/watch-mode)


# Jest (/docs/jest)



# Jest [#jest]

JavaScript testing framework.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Install (/docs/jest/install)



# Install [#install]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Jest is a zero/low-config JavaScript test runner with assertions, mocks, snapshots, and coverage. Install as a dev dependency; use `jest` or `npm test` via scripts.

## 🔧 Core concepts [#-core-concepts]

| Package                  | Role                    |
| ------------------------ | ----------------------- |
| `jest`                   | Runner + expect + mocks |
| `babel-jest`             | Transform modern JS     |
| `ts-jest` / `@swc/jest`  | TypeScript              |
| `jest-environment-jsdom` | DOM for React           |

Jest 29+ is common; check your major for config keys.

## 💡 Examples [#-examples]

**Install:**

```shellscript
npm i -D jest @types/jest
# TypeScript:
npm i -D ts-jest typescript
# React DOM env:
npm i -D jest-environment-jsdom
```

**package.json:**

```json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:cov": "jest --coverage"
  }
}
```

**First test:**

```js
// sum.test.js
const sum = (a, b) => a + b;

test('adds', () => {
  expect(sum(1, 2)).toBe(3);
});
```

**Init config:**

```shellscript
npx jest --init
```

**Run:**

```shellscript
npx jest
npx jest sum.test.js
npx jest -t "adds"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Running an old global `jest` instead of the project binary.
* Missing transform for ESM/TS — tests fail to parse.
* Confusing Vitest APIs when both exist in a monorepo.
* Not setting `testEnvironment` for DOM code (`node` vs `jsdom`).
* Committing huge coverage folders — gitignore them.

## 🔗 Related [#-related]

* [Config](/docs/jest/config)
* [Matchers](/docs/jest/matchers)
* [TypeScript](/docs/jest/typescript)
* [Watch mode](/docs/jest/watch-mode)
* [Coverage](/docs/jest/coverage)
* [Migration to Vitest](/docs/jest/migration-vitest)


# Matchers (/docs/jest/matchers)



# Matchers [#matchers]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`expect(value)` matchers assert equality, truthiness, numbers, strings, collections, and errors. Prefer asymmetric matchers for partial object checks.

## 🔧 Core concepts [#-core-concepts]

| Matcher                 | Use                                    |
| ----------------------- | -------------------------------------- |
| `toBe`                  | Referential / primitives (`Object.is`) |
| `toEqual`               | Deep equality                          |
| `toStrictEqual`         | Deep + undefined keys                  |
| `toMatch` / `toContain` | String / array                         |
| `toThrow`               | Sync exceptions                        |
| `toBeCloseTo`           | Floats                                 |
| `toHaveBeenCalled`      | Mocks                                  |

Chain `.not`, `.resolves`, `.rejects`.

## 💡 Examples [#-examples]

**Equality:**

```js
expect(1 + 1).toBe(2);
expect({ a: 1 }).toEqual({ a: 1 });
expect({ a: 1 }).toStrictEqual({ a: 1 });
```

**Truthiness & numbers:**

```js
expect(x).toBeTruthy();
expect(x).toBeNull();
expect(x).toBeUndefined();
expect(0.1 + 0.2).toBeCloseTo(0.3);
expect(score).toBeGreaterThan(10);
```

**Collections & strings:**

```js
expect(['a', 'b']).toContain('a');
expect('hello').toMatch(/ell/);
expect({ a: 1, b: 2 }).toMatchObject({ a: 1 });
expect([{ id: 1 }]).toContainEqual({ id: 1 });
```

**Asymmetric:**

```js
expect(user).toEqual({
  id: expect.any(Number),
  email: expect.stringMatching(/@/),
  meta: expect.objectContaining({ role: 'admin' }),
});
```

**Errors:**

```js
expect(() => parse('')).toThrow(Error);
expect(() => parse('')).toThrow(/empty/);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `toBe` on objects compares references — use `toEqual`.
* Floating point with `toBe` — use `toBeCloseTo`.
* `toThrow` needs a wrapped function, not a thrown call.
* Over-specific snapshots instead of focused matchers.
* Forgetting `await expect(...).resolves` for promises.

## 🔗 Related [#-related]

* [Async](/docs/jest/async)
* [Mocks](/docs/jest/mocks)
* [Custom matchers](/docs/jest/custom-matchers)
* [Snapshots](/docs/jest/snapshots)
* [Spies](/docs/jest/spies)
* [Install](/docs/jest/install)


# Migration to Vitest (/docs/jest/migration-vitest)



# Migration to Vitest [#migration-to-vitest]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Vitest is Jest-compatible for many APIs (`describe`, `expect`, `vi.fn`) with Vite-native ESM speed. Migrate incrementally: install Vitest, map config, replace Jest globals, fix mocks.

## 🔧 Core concepts [#-core-concepts]

| Jest                 | Vitest                 |
| -------------------- | ---------------------- |
| `jest.fn`            | `vi.fn`                |
| `jest.mock`          | `vi.mock`              |
| `jest.spyOn`         | `vi.spyOn`             |
| `jest.useFakeTimers` | `vi.useFakeTimers`     |
| `jest.config.js`     | `vitest.config.ts`     |
| `jsdom` env          | `environment: 'jsdom'` |

Keep `@testing-library/*` — works with both.

## 💡 Examples [#-examples]

**Install:**

```shellscript
npm i -D vitest jsdom @vitest/coverage-v8
```

**vitest.config.ts:**

```ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./vitest.setup.ts'],
    coverage: { provider: 'v8', reporter: ['text', 'html'] },
  },
});
```

**API swap:**

```ts
// before
jest.spyOn(api, 'get').mockResolvedValue(1);
// after
import { vi } from 'vitest';
vi.spyOn(api, 'get').mockResolvedValue(1);
```

**Scripts:**

```json
{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}
```

**Codemod mindset:** replace `jest.` → `vi.`, update snapshot paths, re-check module mocks under ESM.

## ⚠️ Pitfalls [#️-pitfalls]

* Assuming 100% Jest mock hoisting parity under native ESM.
* Leaving `@types/jest` conflicting with Vitest types.
* Transforming with Jest while running Vitest (duplicate configs).
* Coverage provider/path differences breaking CI thresholds.
* Migrating everything at once — prefer package-by-package in monorepos.

## 🔗 Related [#-related]

* [Install](/docs/jest/install)
* [Config](/docs/jest/config)
* [Mocks](/docs/jest/mocks)
* [Module mocks](/docs/jest/module-mocks)
* [TypeScript](/docs/jest/typescript)
* [Coverage](/docs/jest/coverage)


# Mocks (/docs/jest/mocks)



# Mocks [#mocks]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`jest.fn` and `jest.mock` replace dependencies with controllable fakes. Track calls, set return values, and restore with `clearAllMocks` / `restoreAllMocks`.

## 🔧 Core concepts [#-core-concepts]

| API                                     | Role                  |
| --------------------------------------- | --------------------- |
| `jest.fn()`                             | Mock function         |
| `jest.mock(path)`                       | Module mock (hoisted) |
| `jest.spyOn`                            | Wrap existing method  |
| `mockReturnValue` / `mockResolvedValue` | Outputs               |
| `mockImplementation`                    | Custom body           |

Manual mocks live in `__mocks__` beside modules.

## 💡 Examples [#-examples]

**jest.fn:**

```js
const send = jest.fn().mockReturnValue(true);
send('hi');
expect(send).toHaveBeenCalledWith('hi');
expect(send).toHaveBeenCalledTimes(1);
```

**Async mock:**

```js
const fetchUser = jest
  .fn()
  .mockResolvedValue({ id: 1 })
  .mockRejectedValueOnce(new Error('network'));
```

**Module mock:**

```js
jest.mock('./api', () => ({
  getUser: jest.fn().mockResolvedValue({ id: 1 }),
}));

import { getUser } from './api';

test('uses mock', async () => {
  await expect(getUser()).resolves.toEqual({ id: 1 });
});
```

**Partial mock:**

```js
jest.mock('./utils', () => {
  const actual = jest.requireActual('./utils');
  return { ...actual, randomId: () => 'fixed' };
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* `jest.mock` is hoisted — don't rely on runtime vars above it without `jest.doMock`.
* Forgetting to reset mocks between tests → cross-test pollution.
* Mocking the wrong path (definition vs import site).
* Over-mocking until nothing real is tested.
* ESM + Jest mocking needs experimental/transform setup.

## 🔗 Related [#-related]

* [Spies](/docs/jest/spies)
* [Module mocks](/docs/jest/module-mocks)
* [Matchers](/docs/jest/matchers)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Async](/docs/jest/async)
* [Custom matchers](/docs/jest/custom-matchers)


# Module Mocks (/docs/jest/module-mocks)



# Module Mocks [#module-mocks]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Automock modules with `jest.mock`, manual `__mocks__` folders, and virtual mocks. Control Node built-ins and CSS/assets via mappers.

## 🔧 Core concepts [#-core-concepts]

| Technique                  | When                 |
| -------------------------- | -------------------- |
| `jest.mock('./mod')`       | Auto mock or factory |
| `__mocks__/mod.js`         | Shared manual mock   |
| `jest.requireActual`       | Partial mock         |
| `moduleNameMapper`         | Assets / aliases     |
| `jest.unstable_mockModule` | ESM (experimental)   |

Factories run in a sandboxed scope; hoist rules apply to `jest.mock`.

## 💡 Examples [#-examples]

**Manual mock:**

```plaintext
src/
  api.js
  __mocks__/
    api.js
```

```js
// __mocks__/api.js
export const getUser = jest.fn();
```

```js
jest.mock('./api');
import { getUser } from './api';
getUser.mockResolvedValue({ id: 1 });
```

**Virtual mock:**

```js
jest.mock('analytics', () => ({ track: jest.fn() }), { virtual: true });
```

**Asset mapper:**

```js
moduleNameMapper: {
  '\\.svg$': '<rootDir>/test/svgrMock.js',
  '\\.(css)$': 'identity-obj-proxy',
},
```

**Unmock / isolate:**

```js
jest.unmock('./api');
jest.isolateModules(() => {
  const mod = require('./fresh');
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Factory referencing out-of-scope variables (TDZ / hoist).
* Manual mocks not picked up because path casing/OS differs.
* Mocking ESM named exports incorrectly (namespace shape).
* Leaving automock on globally (`automock: true`) — surprising.
* Circular deps with `requireActual` causing partial undefineds.

## 🔗 Related [#-related]

* [Mocks](/docs/jest/mocks)
* [Spies](/docs/jest/spies)
* [Config](/docs/jest/config)
* [TypeScript](/docs/jest/typescript)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Migration to Vitest](/docs/jest/migration-vitest)


# React Testing Library (/docs/jest/react-testing-library)



# React Testing Library [#react-testing-library]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Testing Library tests React the way users interact: roles, labels, text — not implementation details. Pair with Jest + `jsdom` and `@testing-library/jest-dom`.

## 🔧 Core concepts [#-core-concepts]

| API                   | Role                   |
| --------------------- | ---------------------- |
| `render`              | Mount component        |
| `screen`              | Queries on document    |
| `userEvent`           | Realistic interactions |
| `waitFor` / `findBy*` | Async UI               |
| `within`              | Scope queries          |

Prefer `getByRole` → `getByLabelText` → `getByText` → `getByTestId`.

## 💡 Examples [#-examples]

**Install:**

```shellscript
npm i -D @testing-library/react @testing-library/jest-dom @testing-library/user-event jest-environment-jsdom
```

```js
// jest.setup.js
import '@testing-library/jest-dom';
```

**Component test:**

```tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Login } from './Login';

test('submits email', async () => {
  const user = userEvent.setup();
  const onSubmit = jest.fn();
  render(<Login onSubmit={onSubmit} />);

  await user.type(screen.getByLabelText(/email/i), 'ada@ex.com');
  await user.click(screen.getByRole('button', { name: /sign in/i }));

  expect(onSubmit).toHaveBeenCalledWith({ email: 'ada@ex.com' });
});
```

**Async:**

```tsx
expect(await screen.findByText(/welcome/i)).toBeInTheDocument();
await waitFor(() => expect(mock).toHaveBeenCalled());
```

## ⚠️ Pitfalls [#️-pitfalls]

* Querying by className / enzyme-style selectors.
* Forgetting `userEvent.setup()` with fake timers.
* Not wrapping state updates that warn about act — usually fixed by `findBy`/`await user`.
* Snapshotting entire `container.innerHTML` instead of behavior asserts.
* Using `getBy*` for elements that appear asynchronously — use `findBy*`.

## 🔗 Related [#-related]

* [Matchers](/docs/jest/matchers)
* [Async](/docs/jest/async)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Config](/docs/jest/config)
* [Timers](/docs/jest/timers)
* [Snapshots](/docs/jest/snapshots)


# Setup & Teardown (/docs/jest/setup-teardown)



# Setup & Teardown [#setup--teardown]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`beforeAll` / `beforeEach` / `afterEach` / `afterAll` manage lifecycle. Keep setup local to `describe` blocks; reset mocks and state so tests stay independent.

## 🔧 Core concepts [#-core-concepts]

| Hook         | When                |
| ------------ | ------------------- |
| `beforeAll`  | Once before suite   |
| `beforeEach` | Before every test   |
| `afterEach`  | After every test    |
| `afterAll`   | Once after suite    |
| `describe`   | Scope hooks & tests |

Order: outer `beforeAll` → inner `beforeAll` → `beforeEach` → test → `afterEach` → …

## 💡 Examples [#-examples]

**Typical cleanup:**

```js
beforeEach(() => {
  jest.clearAllMocks();
});

afterEach(() => {
  jest.useRealTimers();
  cleanup(); // RTL
});
```

**Scoped describe:**

```js
describe('db', () => {
  let db;
  beforeAll(async () => {
    db = await connect();
  });
  afterAll(async () => {
    await db.close();
  });
  test('query', async () => {
    expect(await db.ping()).toBe(true);
  });
});
```

**Global setup files (config):**

```js
// jest.config.js
setupFiles: ['<rootDir>/jest.polyfills.js'],
setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
```

```js
// jest.setup.js
import '@testing-library/jest-dom';
```

**Skip / only:**

```js
describe.skip('wip', () => {});
test.only('focus', () => {});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Shared mutable state in `beforeAll` without reset.
* Async hooks without `async`/`await` → races.
* Leaving `test.only` in committed code.
* Heavy `beforeEach` making suites slow — prefer lighter factories.
* Global setup importing app modules before mocks are declared.

## 🔗 Related [#-related]

* [Config](/docs/jest/config)
* [Mocks](/docs/jest/mocks)
* [Timers](/docs/jest/timers)
* [React Testing Library](/docs/jest/react-testing-library)
* [Module mocks](/docs/jest/module-mocks)
* [Watch mode](/docs/jest/watch-mode)


# Snapshots (/docs/jest/snapshots)



# Snapshots [#snapshots]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Snapshots store serialized output and fail when it changes. Use for UI trees, large JSON, or error messages — keep them small and review diffs in PRs.

## 🔧 Core concepts [#-core-concepts]

| API                            | Use                        |
| ------------------------------ | -------------------------- |
| `toMatchSnapshot`              | File under `__snapshots__` |
| `toMatchInlineSnapshot`        | Embedded in test file      |
| `toThrowErrorMatchingSnapshot` | Error text                 |
| `-u` / `--updateSnapshot`      | Refresh baselines          |
| Property matchers              | Soften volatile fields     |

Prefer inline snapshots for tiny values; file snapshots for larger trees.

## 💡 Examples [#-examples]

**Basic:**

```js
test('renders', () => {
  expect(renderHeader()).toMatchSnapshot();
});
```

**Inline:**

```js
expect(user).toMatchInlineSnapshot(`
{
  "id": 1,
  "name": "Ada",
}
`);
```

**Property matchers:**

```js
expect(article).toMatchSnapshot({
  id: expect.any(Number),
  createdAt: expect.any(Date),
});
```

**Update:**

```shellscript
npx jest -u
npx jest path/to/file.test.js -u
```

**Serializer (custom):**

```js
expect.addSnapshotSerializer({
  test: (v) => v && v.__type === 'Money',
  print: (v) => `Money(${v.cents})`,
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Giant DOM snapshots that churn on class-name noise.
* Blindly updating with `-u` without reading diffs.
* Timestamps/random IDs without property matchers.
* Committing snapshots that differ by OS line endings.
* Using snapshots instead of precise matchers for critical logic.

## 🔗 Related [#-related]

* [Matchers](/docs/jest/matchers)
* [React Testing Library](/docs/jest/react-testing-library)
* [Custom matchers](/docs/jest/custom-matchers)
* [Watch mode](/docs/jest/watch-mode)
* [Config](/docs/jest/config)
* [Coverage](/docs/jest/coverage)


# Spies (/docs/jest/spies)



# Spies [#spies]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`jest.spyOn(object, method)` wraps a real method to assert calls while optionally keeping the original implementation. Prefer spies when you need partial observation.

## 🔧 Core concepts [#-core-concepts]

| API                    | Effect                         |
| ---------------------- | ------------------------------ |
| `jest.spyOn(obj, 'm')` | Track calls                    |
| `mockImplementation`   | Replace body                   |
| `mockRestore`          | Put original back              |
| `mockClear`            | Clear call history             |
| `mockReset`            | Clear history + implementation |

Spies are mocks; matchers like `toHaveBeenCalledWith` apply.

## 💡 Examples [#-examples]

**Observe without changing:**

```js
const log = jest.spyOn(console, 'log').mockImplementation(() => {});
doWork();
expect(log).toHaveBeenCalledWith('done');
log.mockRestore();
```

**Replace temporarily:**

```js
const spy = jest
  .spyOn(Date, 'now')
  .mockReturnValue(1_700_000_000_000);
expect(Date.now()).toBe(1_700_000_000_000);
spy.mockRestore();
```

**Class method:**

```js
const spy = jest.spyOn(User.prototype, 'save').mockResolvedValue(undefined);
await user.save();
expect(spy).toHaveBeenCalled();
```

**Cleanup in afterEach:**

```js
afterEach(() => {
  jest.restoreAllMocks();
});
```

**Call order:**

```js
expect(fnA.mock.invocationCallOrder[0]).toBeLessThan(
  fnB.mock.invocationCallOrder[0],
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Spying on non-configurable properties / some ESM bindings.
* Leaving `console` spies mocked and hiding useful output.
* `mockReset` vs `mockRestore` confusion — restore for spies.
* Spying after the module cached a bound original function.
* Asserting call order in parallel async code.

## 🔗 Related [#-related]

* [Mocks](/docs/jest/mocks)
* [Module mocks](/docs/jest/module-mocks)
* [Matchers](/docs/jest/matchers)
* [Timers](/docs/jest/timers)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Async](/docs/jest/async)


# Timers (/docs/jest/timers)



# Timers [#timers]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Fake timers control `setTimeout`, `setInterval`, and (with modern APIs) `Date`. Use them to test debouncing, polling, and animations without real waits.

## 🔧 Core concepts [#-core-concepts]

| API                    | Role            |
| ---------------------- | --------------- |
| `jest.useFakeTimers()` | Enable fakes    |
| `jest.useRealTimers()` | Restore real    |
| `advanceTimersByTime`  | Fast-forward ms |
| `runAllTimers`         | Flush all       |
| `runOnlyPendingTimers` | Current queue   |
| `modern` / legacy      | Fake timer impl |

Jest 29 defaults to modern `@sinonjs/fake-timers`.

## 💡 Examples [#-examples]

**Debounce:**

```js
jest.useFakeTimers();

test('debounces', () => {
  const fn = jest.fn();
  const d = debounce(fn, 500);
  d();
  d();
  expect(fn).not.toHaveBeenCalled();
  jest.advanceTimersByTime(500);
  expect(fn).toHaveBeenCalledTimes(1);
});

afterEach(() => {
  jest.useRealTimers();
});
```

**Async + timers:**

```js
test('polls', async () => {
  jest.useFakeTimers();
  const p = waitForReady(); // uses setTimeout
  await jest.advanceTimersByTimeAsync(1000);
  await expect(p).resolves.toBe(true);
});
```

**Fake Date:**

```js
jest.useFakeTimers({ now: new Date('2020-01-01') });
expect(Date.now()).toBe(new Date('2020-01-01').getTime());
```

**Config:**

```js
// jest.config.js
fakeTimers: { enableGlobally: false },
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `useRealTimers` → later tests hang or flake.
* Mixing real promises with fake timers without `advanceTimersByTimeAsync`.
* `runAllTimers` infinite loops on recurring intervals.
* User-event / RTL needs `advanceTimers` coordination.
* Spying on `Date` while also faking timers — pick one strategy.

## 🔗 Related [#-related]

* [Async](/docs/jest/async)
* [Mocks](/docs/jest/mocks)
* [Spies](/docs/jest/spies)
* [Setup & teardown](/docs/jest/setup-teardown)
* [React Testing Library](/docs/jest/react-testing-library)
* [Config](/docs/jest/config)


# TypeScript (/docs/jest/typescript)



# TypeScript [#typescript]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Run TypeScript tests with `ts-jest`, `@swc/jest`, or Babel. Keep `tsconfig` and Jest transforms aligned for path aliases and JSX.

## 🔧 Core concepts [#-core-concepts]

| Approach     | Notes                            |
| ------------ | -------------------------------- |
| `ts-jest`    | Type-aware option; slower        |
| `@swc/jest`  | Fast transpile                   |
| `babel-jest` | Shared Babel pipeline            |
| Types        | `@types/jest` or `@jest/globals` |

Prefer transpile-only for speed; run `tsc --noEmit` separately in CI.

## 💡 Examples [#-examples]

**ts-jest preset:**

```shellscript
npm i -D ts-jest typescript @types/jest
npx ts-jest config:init
```

```js
// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
};
```

**SWC:**

```js
transform: {
  '^.+\\.(t|j)sx?$': ['@swc/jest', {
    jsc: { parser: { syntax: 'typescript', tsx: true } },
  }],
},
```

**Globals import (ESM-friendly):**

```ts
import { describe, expect, test } from '@jest/globals';

test('typed', () => {
  const n: number = 1;
  expect(n).toBe(1);
});
```

**Path aliases:** mirror `paths` from `tsconfig` in `moduleNameMapper`.

## ⚠️ Pitfalls [#️-pitfalls]

* Type errors only caught if `ts-jest` diagnostics enabled — don't assume.
* JSX runtime mismatches (`react` vs `react-jsx`).
* Mixing ESM `ts-jest` experimental mode without Node flags.
* Duplicate `@types/jest` vs Vitest types in the same project.
* Compiling tests into `dist` accidentally via broad `include`.

## 🔗 Related [#-related]

* [Install](/docs/jest/install)
* [Config](/docs/jest/config)
* [React Testing Library](/docs/jest/react-testing-library)
* [Module mocks](/docs/jest/module-mocks)
* [Migration to Vitest](/docs/jest/migration-vitest)
* [Matchers](/docs/jest/matchers)


# Watch Mode (/docs/jest/watch-mode)



# Watch Mode [#watch-mode]

*Jest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`jest --watch` / `--watchAll` re-runs tests on file changes. Interactive filters focus on failed tests, filenames, and related source files — ideal for TDD.

## 🔧 Core concepts [#-core-concepts]

| Mode             | Behavior                 |
| ---------------- | ------------------------ |
| `--watch`        | Git-aware changed files  |
| `--watchAll`     | All tests on any change  |
| Interactive keys | Filter, update snapshots |
| `--onlyChanged`  | Non-interactive changed  |

Requires a git/hg repo for `--watch` heuristics; else use `--watchAll`.

## 💡 Examples [#-examples]

**Scripts:**

```json
{
  "scripts": {
    "test": "jest",
    "test:watch": "jest --watch",
    "test:watchAll": "jest --watchAll"
  }
}
```

**Interactive keys (typical):**

```plaintext
a  run all tests
f  run only failed
o  only changed (watch)
p  filter by filename regex
t  filter by test name regex
u  update snapshots
q  quit
```

**CLI filters without UI:**

```shellscript
npx jest --watch --testPathPattern=Button
npx jest -t "submits form" --watchAll
```

**CI:** never use watch — use `--ci`.

## ⚠️ Pitfalls [#️-pitfalls]

* `--watch` outside git showing confusing empty sets — use `--watchAll`.
* Updating snapshots with `u` without reviewing.
* Watching huge monorepos without `roots` / projects — slow.
* Editors saving continuously causing thrash — debounce/save properly.
* Relying on watch caches after dependency upgrades — restart.

## 🔗 Related [#-related]

* [Install](/docs/jest/install)
* [Snapshots](/docs/jest/snapshots)
* [Config](/docs/jest/config)
* [Coverage](/docs/jest/coverage)
* [Setup & teardown](/docs/jest/setup-teardown)
* [Matchers](/docs/jest/matchers)


# AbortController (/docs/javascript/abort-controller)



# AbortController [#abortcontroller]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`AbortController` and `AbortSignal` cancel async operations — `fetch`, streams, and custom tasks. Create a controller, pass `signal` to APIs, call `abort()` to reject pending work and run abort listeners. Essential for timeouts, navigation changes, and avoiding race conditions.

## 🔧 Core concepts [#-core-concepts]

* **`new AbortController()`** → `\{ signal, abort(reason?) \}`.
* **`signal.aborted`*&#x2A;, &#x2A;*`signal.reason`*&#x2A;, &#x2A;*`signal.throwIfAborted()`**.
* **`signal.addEventListener("abort", ...)`** — once fired, stays aborted.
* **`AbortSignal.timeout(ms)`**: auto-abort after delay.
* **`AbortSignal.any([s1, s2])`**: abort when any aborts (modern).
* **Fetch**: `fetch(url, \{ signal \})` rejects with `AbortError` / `TimeoutError`.

```js
const c = new AbortController();
fetch("/api", { signal: c.signal }).catch((e) => {
  if (e.name === "AbortError") return;
  throw e;
});
c.abort();
```

## 💡 Examples [#-examples]

```js
// Timeout via helper
const data = await fetch("/slow", {
  signal: AbortSignal.timeout(5000),
}).then((r) => r.json());

// Manual timeout
const c = new AbortController();
const t = setTimeout(() => c.abort("timeout"), 3000);
try {
  await fetch("/api", { signal: c.signal });
} finally {
  clearTimeout(t);
}

// Cancel on new request (race guard)
let current;
function search(q) {
  current?.abort();
  current = new AbortController();
  return fetch(`/search?q=${encodeURIComponent(q)}`, {
    signal: current.signal,
  });
}

// Custom abortable work
function sleep(ms, signal) {
  return new Promise((resolve, reject) => {
    signal?.throwIfAborted();
    const id = setTimeout(resolve, ms);
    signal?.addEventListener(
      "abort",
      () => {
        clearTimeout(id);
        reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
      },
      { once: true },
    );
  });
}

// Combine signals
const userCancel = new AbortController();
const signal = AbortSignal.any([userCancel.signal, AbortSignal.timeout(10_000)]);
```

```js
// Event listener option
el.addEventListener("click", handler, { signal: c.signal });
c.abort(); // removes listener
```

## ⚠️ Pitfalls [#️-pitfalls]

* Aborted fetch throws — always handle `AbortError` so UI doesn’t treat cancel as failure.
* Reusing an already-aborted signal keeps operations aborted — create a new controller per run.
* Not all APIs support signals yet — wrap manually with listeners.
* `abort(reason)` reason support varies; check `signal.reason`.
* Forgetting to abort on unmount leaks in-flight requests.

## 🔗 Related [#-related]

* [fetch.md](/docs/javascript/fetch) — fetch + signal
* [timers.md](/docs/javascript/timers) — timeout patterns
* [promise.md](/docs/javascript/promise) — rejection handling
* [DOM/events.md](/docs/javascript/dom/events) — signal option
* [event\_loop.md](/docs/javascript/event-loop) — async cancellation


# Web APIs (/docs/javascript/api)



# Web APIs [#web-apis]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Browser and runtime **Web APIs** sit beside the language core: timers, encoding, crypto, streams, and platform globals. This sheet covers common non-DOM APIs you use from scripts. Prefer standards-based APIs over legacy vendor methods.

## 🔧 Core concepts [#-core-concepts]

* **Globals**: `globalThis`, `window` (browsers), `self` (workers).
* **Timers**: `setTimeout`, `setInterval`, `clearTimeout`, `clearInterval`, `queueMicrotask`.
* **Encoding**: `TextEncoder` / `TextDecoder`, `btoa` / `atob` (binary strings).
* **Crypto**: `crypto.getRandomValues`, `crypto.randomUUID`, `crypto.subtle`.
* **Streams**: `ReadableStream`, `WritableStream`, `TransformStream`.
* **Abort**: `AbortController` / `AbortSignal` cancel async work.
* **Structured clone**: `structuredClone(value)` deep-copies most data.

```js
const id = crypto.randomUUID();
const bytes = crypto.getRandomValues(new Uint8Array(16));
const copy = structuredClone({ nested: [1, 2, 3] });
```

## 💡 Examples [#-examples]

```js
// Debounced timer
function debounce(fn, ms) {
  let t;
  return (...args) => {
    clearTimeout(t);
    t = setTimeout(() => fn(...args), ms);
  };
}

// Abortable delay
function delay(ms, signal) {
  return new Promise((resolve, reject) => {
    const id = setTimeout(resolve, ms);
    signal?.addEventListener("abort", () => {
      clearTimeout(id);
      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
    }, { once: true });
  });
}

const ac = new AbortController();
await delay(1000, ac.signal).catch((e) => console.warn(e.name));

// Text encode / decode
const enc = new TextEncoder();
const dec = new TextDecoder();
const buf = enc.encode("café");
console.log(dec.decode(buf)); // café

// Base64 of binary (safe path)
function toBase64(bytes) {
  let s = "";
  for (const b of bytes) s += String.fromCharCode(b);
  return btoa(s);
}

// Subtle crypto digest
async function sha256(text) {
  const data = new TextEncoder().encode(text);
  const hash = await crypto.subtle.digest("SHA-256", data);
  return [...new Uint8Array(hash)]
    .map((b) => b.toString(16).padStart(2, "0"))
    .join("");
}

// Microtask vs macrotask
queueMicrotask(() => console.log("micro"));
setTimeout(() => console.log("macro"), 0);
Promise.resolve().then(() => console.log("promise"));
// Order: micro, promise, macro
```

```js
// Simple transform stream (uppercase)
const upper = new TransformStream({
  transform(chunk, controller) {
    controller.enqueue(chunk.toUpperCase());
  },
});

const reader = new ReadableStream({
  start(c) {
    c.enqueue("hello");
    c.close();
  },
}).pipeThrough(upper).getReader();

const { value } = await reader.read();
console.log(value); // HELLO
```

## ⚠️ Pitfalls [#️-pitfalls]

* `btoa` / `atob` expect Latin-1 binary strings — not UTF-8 text directly.
* Timer IDs are numbers in browsers, objects in Node — always store and clear the return value.
* `crypto.subtle` needs a secure context (`https:` or `localhost`).
* `structuredClone` cannot clone functions, DOM nodes, or some host objects.
* Unhandled timer callbacks still run after navigation in some cases — clear on teardown.

## 🔗 Related [#-related]

* [fetch.md](/docs/javascript/fetch) — HTTP via Fetch API
* [promise.md](/docs/javascript/promise) — async primitives
* [async.md](/docs/javascript/async) — async/await patterns
* [encode.md](/docs/javascript/encode) — URI and percent-encoding
* [url.md](/docs/javascript/url) — URL / URLSearchParams
* [error.md](/docs/javascript/error) — AbortError and exceptions
* [DOM/window.md](/docs/javascript/dom/window) — window globals
* [DOM/events.md](/docs/javascript/dom/events) — event targets


# Arrays (/docs/javascript/arrays)



# Arrays [#arrays]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Arrays are ordered, indexable lists. Prefer non-mutating methods (`map`, `filter`, `toSorted`) when state is shared; mutate in place only when you own the array. Watch sparse holes and default string `sort`.

## 🔧 Core concepts [#-core-concepts]

**Create / static**

| Method                       | Notes                                                |
| ---------------------------- | ---------------------------------------------------- |
| `Array()`, `[]`              | Prefer `[]`; `new Array(n)` makes length-n sparse    |
| `Array.of(...items)`         | Items as elements (avoids single-number length trap) |
| `Array.from(iter, mapFn?)`   | From iterable/array-like; optional map               |
| `Array.isArray(x)`           | True only for real arrays                            |
| `Array.fromAsync(asyncIter)` | Await each yield (ES2024)                            |

**Access / length**

| API                   | Notes                                         |
| --------------------- | --------------------------------------------- |
| `arr[i]`, `arr.at(i)` | `at` supports negatives                       |
| `arr.length`          | Writable; shrink truncates; grow adds holes   |
| `arr.with(i, v)`      | Copy with index `i` set to `v` (non-mutating) |

**Mutating**

| Method                      | Notes                                            |
| --------------------------- | ------------------------------------------------ |
| `push(...x)` / `pop()`      | End insert / remove                              |
| `unshift(...x)` / `shift()` | Start insert / remove (O(n))                     |
| `splice(i, n, ...x)`        | Delete `n` from `i`, insert `x`; returns removed |
| `sort(cmp?)`                | In-place; default **string** order               |
| `reverse()`                 | In-place reverse                                 |
| `fill(v, start?, end?)`     | Fill range with `v`                              |
| `copyWithin(t, s, e?)`      | Copy slice within same array                     |

**Non-mutating (ES2023+)**

| Method                  | Notes                                  |
| ----------------------- | -------------------------------------- |
| `toSorted(cmp?)`        | Sorted copy                            |
| `toReversed()`          | Reversed copy                          |
| `toSpliced(i, n, ...x)` | Splice copy                            |
| `slice(start?, end?)`   | Subarray copy (end exclusive)          |
| `concat(...items)`      | Flatten one level of arrays; new array |

**Search**

| Method                        | Notes                                 |
| ----------------------------- | ------------------------------------- |
| `includes(v, from?)`          | SameValueZero (finds `NaN`)           |
| `indexOf` / `lastIndexOf`     | Strict equality; no `NaN`             |
| `find` / `findLast`           | First/last element matching predicate |
| `findIndex` / `findLastIndex` | Index or `-1`                         |
| `some` / `every`              | Any / all pass predicate              |

**Iterate / transform / convert**

| Method                         | Notes                                |
| ------------------------------ | ------------------------------------ |
| `forEach(fn)`                  | Side effects; ignores return         |
| `map` / `filter`               | Transform / keep                     |
| `flat(depth?)` / `flatMap(fn)` | Flatten; map then flatten 1          |
| `reduce` / `reduceRight`       | Fold L→R / R→L                       |
| `keys` / `values` / `entries`  | Index / value / pair iterators       |
| `join(sep?)`                   | String; default `","`                |
| `Object.groupBy(arr, fn)`      | Group into object of arrays (ES2024) |

```js
const a = Array.from({ length: 3 }, (_, i) => i + 1); // [1, 2, 3]
const last = a.at(-1); // 3
```

## 💡 Examples [#-examples]

```js
const nums = [3, 1, 4, 1, 5];

const sorted = nums.toSorted((x, y) => x - y);
const replaced = nums.with(2, 99); // [3, 1, 99, 1, 5]
const unique = [...new Set(nums)];

function chunk(arr, size) {
  const out = [];
  for (let i = 0; i < arr.length; i += size) {
    out.push(arr.slice(i, i + size));
  }
  return out;
}

const people = [
  { name: "Ada", role: "eng" },
  { name: "Alan", role: "eng" },
  { name: "Grace", role: "ops" },
];
const byRole = Object.groupBy(people, (p) => p.role);

const nested = [[1, 2], [3], [4, 5]];
console.log(nested.flat()); // [1, 2, 3, 4, 5]

const freq = nums.reduce((m, n) => {
  m.set(n, (m.get(n) ?? 0) + 1);
  return m;
}, new Map());

const [head, ...tail] = nums;
const copy = [...nums, 9];
```

```js
const sparse = [];
sparse[2] = "x";
console.log(sparse.length); // 3

const chars = Array.from("hi"); // ["h", "i"]

// Stable partition
const evens = nums.filter((n) => n % 2 === 0);
const odds = nums.filter((n) => n % 2 !== 0);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Default `sort()` uses string order — always pass `(a, b) => a - b` for numbers.
* Prefer `toSorted` / `with` when you must not mutate shared arrays.
* `delete arr[i]` leaves a hole; use `splice` or `toSpliced`.
* `includes` uses SameValueZero (finds `NaN`); `indexOf` does not.
* Spreading huge arrays can hit call-stack / memory limits.

## 🔗 Related [#-related]

* [iteration.md](/docs/javascript/iteration) — looping patterns
* [for\_of.md](/docs/javascript/for-of) — for...of
* [iterator.md](/docs/javascript/iterator) — iterable protocol
* [map.md](/docs/javascript/map) — Map collections
* [set.md](/docs/javascript/set) — unique values
* [objects.md](/docs/javascript/objects) — Object.groupBy
* [json.md](/docs/javascript/json) — serialize arrays


# Arrow functions (/docs/javascript/arrow-functions)



# Arrow functions [#arrow-functions]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Arrow functions (`=>`) are compact function expressions — JS’s common “lambda” style for callbacks. They differ from `function` in `this` binding, `arguments`, constructability, and prototype. Prefer arrows for short callbacks; use `function` when you need dynamic `this` or a method on a prototype.

## 🔧 Core concepts [#-core-concepts]

* **Syntax**: `(a, b) => expr` or `(a, b) => \{ statements; return x; \}`.
* **Implicit return**: single expression body returns that value; object literals need `( \{ … \} )`.
* **Lexical `this`**: inherits `this` from the enclosing scope (no own `this`).
* **No `arguments` object**: use rest params `(...args) =>`.
* **Not constructors**: cannot `new` an arrow; no `prototype` property.
* **Callbacks**: ideal for `map` / `filter` / `then` / event handlers that should keep outer `this`.

## 💡 Examples [#-examples]

```js
const double = (n) => n * 2;
const add = (a, b) => a + b;

const nums = [1, 2, 3];
nums.map((n) => n * 2);
nums.filter((n) => n > 1);

// Block body
const sum = (arr) => {
  let t = 0;
  for (const n of arr) t += n;
  return t;
};

// Return object literal
const toPair = (k, v) => ({ [k]: v });

// Lexical this
class Timer {
  delay = 100;
  start() {
    setTimeout(() => {
      console.log(this.delay); // Timer instance
    }, this.delay);
  }
}

// vs function — own this (often wrong in callbacks)
setTimeout(function () {
  // this is not the Timer
}, 0);

// Rest instead of arguments
const max = (...xs) => Math.max(...xs);
```

```js
// Ascending sort comparator
[3, 1, 2].sort((a, b) => a - b);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Object methods as arrows on the prototype lose per-instance `this` patterns you may want; class fields as arrows are fine but not shared on the prototype.
* Implicit return of `\{\}` is a block, not an object — wrap in parentheses.
* Cannot be used as constructors or with `yield` as generators.
* `this` inside an arrow in a `function` callback still follows the outer scope — know which scope you mean.
* Longer logic is often clearer as a named `function` declaration.

## 🔗 Related [#-related]

* [Functions](/docs/javascript/functions) — declarations, expressions, params
* [this keyword](/docs/javascript/this-keyword) — `this` binding rules
* [Closures](/docs/javascript/closures) — lexical scope
* [Async](/docs/javascript/async) — async arrows `async () => \{\}`
* [Arrays](/docs/javascript/arrays) — `map` / `filter` / `reduce` callbacks


# Async / Await (/docs/javascript/async)



# Async / Await [#async--await]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`async` functions always return a Promise. `await` pauses the function until a thenable settles, then resumes with the value or throws the rejection. Prefer `async`/`await` for sequential flow; use `Promise.all` (and friends) for concurrency.

## 🔧 Core concepts [#-core-concepts]

* **`async function` / `async () => \{\}`**: return value is wrapped in `Promise.resolve`.
* **`await expr`**: only inside `async` functions or top-level modules.
* **Errors**: rejected promises become thrown exceptions at `await`.
* **Concurrency**: start promises first, then `await` them together.
* **Top-level await**: allowed in ES modules (and some bundler targets).

```js
async function load() {
  const res = await fetch("/api/user");
  if (!res.ok) throw new Error(res.statusText);
  return res.json();
}
```

## 💡 Examples [#-examples]

```js
// Sequential vs parallel
async function sequential(ids) {
  const out = [];
  for (const id of ids) {
    out.push(await fetch(`/u/${id}`).then((r) => r.json()));
  }
  return out;
}

async function parallel(ids) {
  return Promise.all(
    ids.map((id) => fetch(`/u/${id}`).then((r) => r.json())),
  );
}

// try/catch around await
async function safe() {
  try {
    return await load();
  } catch (err) {
    console.error(err);
    return null;
  }
}

// Await multiple
const [a, b] = await Promise.all([fetchA(), fetchB()]);

// allSettled for partial success
const results = await Promise.allSettled([p1, p2, p3]);
for (const r of results) {
  if (r.status === "fulfilled") console.log(r.value);
  else console.warn(r.reason);
}

// Async iteration
async function* pages(url) {
  let next = url;
  while (next) {
    const data = await fetch(next).then((r) => r.json());
    yield data.items;
    next = data.next;
  }
}

for await (const batch of pages("/api?page=1")) {
  console.log(batch.length);
}
```

```js
// Don't forget to return / await inside map
const bad = ids.map(async (id) => await work(id)); // Promise[]
const good = await Promise.all(ids.map((id) => work(id)));

// Microtask timing
async function order() {
  console.log("1");
  await Promise.resolve();
  console.log("3");
}
order();
console.log("2"); // 1, 2, 3
```

## ⚠️ Pitfalls [#️-pitfalls]

* `await` in a loop serializes work — often unintentional.
* Floating promises: always `await`, `return`, or `.catch()` async calls.
* `async` callbacks in `forEach` do not wait — use `for...of` or `Promise.all`.
* Catching with empty `catch` hides AbortError and network failures.
* Mixing `.then` chains with `await` is fine, but keep one style per function.

## 🔗 Related [#-related]

* [promise.md](/docs/javascript/promise) — Promise API
* [fetch.md](/docs/javascript/fetch) — HTTP requests
* [error.md](/docs/javascript/error) — try/catch patterns
* [iteration.md](/docs/javascript/iteration) — for await...of
* [for\_of.md](/docs/javascript/for-of) — sync iteration
* [api.md](/docs/javascript/api) — AbortController


# BigInt (/docs/javascript/bigint)



# BigInt [#bigint]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`BigInt` represents arbitrary-precision integers. Use when values exceed `Number.MAX_SAFE_INTEGER` (±2⁵³−1), such as IDs, cryptography sizes, or exact integer math. BigInts cannot mix with Numbers in arithmetic without explicit conversion.

## 🔧 Core concepts [#-core-concepts]

* **Literals**: `10n`, `-1n`.
* **Construct**: `BigInt(10)`, `BigInt("9007199254740993")`.
* **Ops**: `+ - * / % **` and bitwise on BigInts only (`/` truncates toward zero).
* **Compare**: `&lt; > &lt;= >=` work with Numbers; `===` does not coerce.
* **Typed arrays**: `BigInt64Array`, `BigUint64Array`.
* **No `Math.*`**: use explicit BigInt helpers.

```js
const huge = 9007199254740993n;
huge + 1n; // 9007199254740994n
```

## 💡 Examples [#-examples]

```js
Number.MAX_SAFE_INTEGER; // 9007199254740991
9007199254740993; // loses precision as Number
9007199254740993n; // exact

// Conversion
BigInt(42); // 42n
Number(42n); // 42 — may lose precision for large values
42n === 42; // false
42n == 42; // true (avoid ==)

// Arithmetic
(2n ** 10n); // 1024n
10n / 3n; // 3n (truncates)

// Mixing requires cast
const n = 5;
// 5n + n; // TypeError
5n + BigInt(n); // 10n

// Comparisons
1n < 2; // true
0n === 0; // false

// JSON — not supported natively
JSON.stringify({ id: 1n }); // throws
// serialize as string:
JSON.stringify({ id: 1n.toString() });

// Typed array
const buf = new BigInt64Array([1n, -2n]);
```

```js
function fib(n) {
  let a = 0n,
    b = 1n;
  for (let i = 0; i < n; i++) [a, b] = [b, a + b];
  return a;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing `BigInt` and `Number` in `+`/`*` throws `TypeError`.
* `Math.max(1n, 2n)` throws — no Math support.
* Division truncates; there is no BigInt float.
* `JSON.stringify` cannot serialize BigInt — convert to string/number carefully.
* Unary `+bigint` is invalid; use `Number(bigint)` or comparisons.

## 🔗 Related [#-related]

* [number.md](/docs/javascript/number) — IEEE floats & safe integers
* [typed\_arrays.md](/docs/javascript/typed-arrays) — BigInt64Array
* [json.md](/docs/javascript/json) — serialization
* [equality.md](/docs/javascript/equality) — == vs ===
* [type\_coercion.md](/docs/javascript/type-coercion) — conversions


# Boolean (/docs/javascript/boolean)



# Boolean [#boolean]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Booleans are `true` / `false`. Many values coerce via ToBoolean in conditionals. Prefer explicit checks over truthiness when `0`, `""`, or `null` are valid data.

## 🔧 Core concepts [#-core-concepts]

* **Literals**: `true`, `false`.
* **`Boolean(x)` / `!!x`**: convert with ToBoolean.
* **Falsy**: `false`, `0`, `-0`, `0n`, `""`, `null`, `undefined`, `NaN`.
* **Truthy**: everything else (including `[]`, `\{\}`, `"0"`).
* **Logical ops**: `&&`, `||`, `??` (nullish), `!`.
* **Comparisons**: `===` / `!==` preferred over `==` / `!=`.

```js
Boolean(0); // false
Boolean([]); // true
!!"hi"; // true
```

## 💡 Examples [#-examples]

```js
// Nullish vs OR
const port = settings.port ?? 3000; // only null/undefined
const title = name || "Guest"; // also replaces ""

// Short-circuit
user && user.profile && user.profile.id;
user?.profile?.id; // optional chaining

// Guards
function assert(cond, msg) {
  if (!cond) throw new Error(msg);
}

// Explicit empty checks
function hasText(s) {
  return typeof s === "string" && s.trim().length > 0;
}

// Toggle
let on = false;
on = !on;

// Boolean object trap
const boxed = new Boolean(false);
if (boxed) {
  // runs — object is truthy!
}
```

```js
// Filter truthy
const values = [0, 1, "", "a", null, undefined, NaN, false, true];
const truthy = values.filter(Boolean); // [1, "a", true]

// Predicate helpers
const isNil = (v) => v == null; // null or undefined
const isPresent = (v) => v != null;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `new Boolean(false)` is an object and is truthy — never use Boolean wrappers.
* `==` coerces: `false == 0`, `"" == 0` — use `===`.
* Empty arrays/objects are truthy — check `.length` or `Object.keys`.
* `??` only skips `null`/`undefined`; `||` also skips other falsy values.
* Document APIs that return `0` or `""` so callers do not treat them as missing.

## 🔗 Related [#-related]

* [number.md](/docs/javascript/number) — numeric falsy values
* [strings.md](/docs/javascript/strings) — empty strings
* [objects.md](/docs/javascript/objects) — nullish patterns
* [switch\_case.md](/docs/javascript/switch-case) — branching
* [error.md](/docs/javascript/error) — assertions


# Buffer (/docs/javascript/buffer)



# Buffer [#buffer]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

In Node.js, `Buffer` is a fixed-length sequence of bytes (Uint8Array subclass). Use it for binary I/O, encodings, and crypto. Prefer `Buffer.from` / `Buffer.alloc` over the deprecated `new Buffer()`.

```js
import { Buffer } from "node:buffer";
```

## 🔧 Core concepts [#-core-concepts]

* **`Buffer.from(data, encoding?)`**: from string, array, ArrayBuffer, or another Buffer.
* **`Buffer.alloc(size, fill?, encoding?)`**: zero-filled (safe) allocation.
* **`Buffer.allocUnsafe(size)`**: faster, may contain old memory — overwrite before use.
* **Encodings**: `'utf8'` (default for many APIs), `'utf16le'`, `'base64'`, `'base64url'`, `'hex'`, `'ascii'`, `'latin1'`.
* **`buf.toString(encoding?)`**: bytes → string.
* **`buf.length`**: byte length, not string character count for multi-byte UTF-8.
* **Slice vs subarray**: `subarray` views the same memory; mutating affects the parent.

## 💡 Examples [#-examples]

```js
const a = Buffer.from("hello", "utf8");
const b = Buffer.from([0x68, 0x69]); // 'hi'
const z = Buffer.alloc(8); // 8 zero bytes

console.log(a.toString("utf8")); // 'hello'
console.log(a.toString("hex")); // '68656c6c6f'
console.log(Buffer.from("6869", "hex").toString()); // 'hi'

const b64 = Buffer.from("hi").toString("base64");
Buffer.from(b64, "base64").toString(); // 'hi'

// Concat
const all = Buffer.concat([a, b]);

// Compare / copy
Buffer.compare(a, b);
a.copy(Buffer.alloc(a.length));

// Binary file
import { readFile } from "node:fs/promises";
const buf = await readFile("image.png"); // Buffer
```

```js
// UTF-8 byte length ≠ string length
const s = "é";
[...s].length; // 1
Buffer.byteLength(s, "utf8"); // 2
```

## ⚠️ Pitfalls [#️-pitfalls]

* `allocUnsafe` can leak old data if not filled — prefer `alloc` unless profiling demands otherwise.
* Truncating multi-byte UTF-8 mid-character corrupts strings — decode carefully when slicing.
* `buf.slice` is deprecated legacy alias; use `subarray` and remember shared memory.
* Mixing encodings (e.g. treat base64 as utf8) produces garbage.
* Large buffers: stream instead of loading entire files when possible.

## 🔗 Related [#-related]

* [fs](/docs/javascript/fs) — readFile returns Buffer by default
* [Typed arrays](/docs/javascript/typed-arrays) — Uint8Array / ArrayBuffer
* [Crypto](/docs/javascript/crypto-node) — hashes over Buffers
* [Stream](/docs/javascript/stream) — chunked Buffers
* [encode](/docs/javascript/encode) — URL/text encoding related concepts


# child_process (/docs/javascript/child-process)



# child\_process [#child_process]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js `node:child_process&#x60; runs external programs. Prefer &#x2A;*`spawn`*&#x2A; / &#x2A;*`execFile`** with argument arrays over shell `exec` when you control the command. Shell mode invites injection if user input is interpolated.

```js
import { spawn, execFile, exec } from "node:child_process";
```

## 🔧 Core concepts [#-core-concepts]

* **`spawn(command, args[], options?)`**: streams stdio; best for long-running or large output.
* **`execFile(file, args[], options?, cb)`**: runs executable directly (no shell); buffered stdout/stderr.
* **`exec(command, options?, cb)`**: runs via shell — convenient, riskier.
* **Promises**: `import \{ spawn \} from "node:child_process"` + manual wrappers, or `promisify(execFile)`.
* **Options**: `cwd`, `env`, `timeout`, `maxBuffer`, `stdio` (`'pipe' | 'inherit' | 'ignore'`).
* **Exit**: listen for `close` / `exit`; check `code` and `signal`.

## 💡 Examples [#-examples]

```js
import { spawn, execFile } from "node:child_process";
import { promisify } from "node:util";

const execFileAsync = promisify(execFile);

// Safe: args array, no shell
const { stdout } = await execFileAsync("node", ["-v"]);
console.log(stdout.trim());

const child = spawn("node", ["script.js", "--port", "9000"], {
  stdio: "inherit",
  cwd: process.cwd(),
  env: { ...process.env, NODE_ENV: "development" },
});

child.on("close", (code) => {
  console.log("exit", code);
});

// Capture streamed output
const p = spawn("git", ["status", "--porcelain"]);
let out = "";
p.stdout.setEncoding("utf8");
p.stdout.on("data", (chunk) => {
  out += chunk;
});
await new Promise((resolve, reject) => {
  p.on("error", reject);
  p.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`code ${code}`))));
});
```

```js
// Avoid: exec with untrusted input
// exec(`ls ${userPath}`); // injection risk
```

## ⚠️ Pitfalls [#️-pitfalls]

* **`exec` / `execSync` shell injection**: never concatenate untrusted strings into the command line.
* **`maxBuffer`**: `exec`/`execFile` throw if output exceeds limit (default \~1MB) — use `spawn` for big output.
* Windows: `.cmd` / `.bat` often need `shell: true` or `exec`; prefer explicit `.exe` when possible.
* Forgotten listeners / open stdio can keep the parent process alive.
* `spawn` does not reject on non-zero exit by default — check `code` yourself.

## 🔗 Related [#-related]

* [process](/docs/javascript/process) — env, cwd, exit codes
* [Stream](/docs/javascript/stream) — child stdio streams
* [Events](/docs/javascript/events-node) — `close` / `error` events
* [util](/docs/javascript/util) — `promisify(execFile)`
* [Path](/docs/javascript/path) — resolve executable paths


# Closures (/docs/javascript/closures)



# Closures [#closures]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A closure is a function plus the lexical environment where it was created. Inner functions keep access to outer variables even after the outer function has returned. Closures power private state, factories, event handlers, and partial application.

## 🔧 Core concepts [#-core-concepts]

* **Lexical scope**: nested functions see bindings from enclosing scopes.
* **Lifetime**: each call to the outer function creates a fresh environment.
* **Mutable capture**: closed-over `let`/`const`/`var` bindings stay live — later mutations are visible.
* **Module pattern**: IIFE or ES modules expose a public API while hiding internals.
* **Factory**: return functions that share private state.

```js
function makeCounter() {
  let n = 0;
  return () => ++n;
}
const c = makeCounter();
c(); // 1
c(); // 2
```

## 💡 Examples [#-examples]

```js
// Private state
function createBank(initial = 0) {
  let balance = initial;
  return {
    deposit(amount) {
      balance += amount;
      return balance;
    },
    getBalance() {
      return balance;
    },
  };
}

// Partial application
function multiply(a) {
  return (b) => a * b;
}
const triple = multiply(3);
triple(4); // 12

// Event handler captures element/id
function bindOnce(el, type, handler) {
  const wrapped = (e) => {
    el.removeEventListener(type, wrapped);
    handler(e);
  };
  el.addEventListener(type, wrapped);
}

// Loop pitfall fixed with let / factory
const buttons = [];
for (let i = 0; i < 3; i++) {
  buttons.push(() => i);
}
buttons[0](); // 0 — each iteration has its own i

// Memoization via closure
function memoize(fn) {
  const cache = new Map();
  return (key) => {
    if (cache.has(key)) return cache.get(key);
    const value = fn(key);
    cache.set(key, value);
    return value;
  };
}
```

```js
// Module-like IIFE
const logger = (() => {
  const levels = ["debug", "info", "warn", "error"];
  return {
    log(level, msg) {
      if (levels.includes(level)) console[level]?.(msg);
    },
  };
})();
```

## ⚠️ Pitfalls [#️-pitfalls]

* Accidental retention: closures keep references alive and can delay GC (DOM nodes, large arrays).
* `var` in loops shared one binding across iterations — use `let` or a factory.
* Returning a method that uses `this` from a closure may lose `this` when detached — bind or use arrows carefully.
* Closures over loop indices in `var` + async callbacks is a classic bug.

## 🔗 Related [#-related]

* [functions.md](/docs/javascript/functions) — function forms
* [this\_keyword.md](/docs/javascript/this-keyword) — `this` vs lexical capture
* [modules\_commonjs.md](/docs/javascript/modules-commonjs) — module scope
* [oop.md](/docs/javascript/oop) — private fields alternative
* [event\_loop.md](/docs/javascript/event-loop) — async + closures


# Comments (/docs/javascript/comments)



# Comments [#comments]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Comments document intent for humans. Engines ignore them. JavaScript supports single-line `//` and multi-line `/* */` comments. JSDoc-style blocks are a convention for documenting APIs.

## 🔧 Core concepts [#-core-concepts]

| Form        | Syntax       | Use                                   |
| ----------- | ------------ | ------------------------------------- |
| Single-line | `// note`    | Most everyday notes                   |
| Multi-line  | `/* ... */`  | Longer notes / temporary disable      |
| JSDoc       | `/** ... */` | Document functions/types for tooling  |
| TODO        | `// TODO:`   | Mark follow-ups (don’t leave forever) |

Comments do not replace clear names and small functions.

## 💡 Examples [#-examples]

**Single-line and inline:**

```js
// Convert Celsius to Fahrenheit
const c = 20;
const f = c * 9 / 5 + 32; // standard formula
console.log(f);
```

**Multi-line:**

```js
/*
  Demo script: comments + console output.
  Safe to delete when you understand it.
*/
console.log("ok");
```

**JSDoc-style:**

```js
/**
 * Add two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

console.log(add(2, 3));
```

**Comment out an experiment:**

```js
// const legacy = oldApi();
const value = newApi();
console.log(value);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Nested `/* */` is not allowed — the first `*/` ends the comment.
* `//` inside a string is not a comment: `"http://example.com"` is fine.
* Huge blocks of commented-out code belong in Git history, not the file.
* Misleading comments are worse than none — update them when code changes.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/javascript/getting-started)
* [hello\_world.md](/docs/javascript/hello-world)
* [variables\_let\_const.md](/docs/javascript/variables-let-const)
* [typeof\_basics.md](/docs/javascript/typeof-basics)


# Conditionals (/docs/javascript/conditionals)



# Conditionals [#conditionals]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Conditionals branch control flow with `if` / `else if` / `else`, `switch`, and short-circuit logic. Prefer clear boolean expressions, early returns, and exhaustive switches for unions. Truthiness rules matter — know what counts as falsy.

## 🔧 Core concepts [#-core-concepts]

* **Falsy**: `false`, `0`, `-0`, `0n`, `""`, `null`, `undefined`, `NaN`.
* **Truthy**: everything else (including `[]`, `\{\}`, `"0"`).
* **`if (expr)`**: coerces with ToBoolean.
* **`else if` / `else`**: chained alternatives.
* **`switch (x)`**: strict equality (`===`) match; remember `break`.
* **Guards**: early `return` / `throw` to flatten nesting.

```js
if (user?.isAdmin) {
  allow();
} else if (user) {
  deny();
} else {
  login();
}
```

## 💡 Examples [#-examples]

```js
// Early return style
function canEdit(doc, user) {
  if (!user) return false;
  if (doc.locked) return false;
  return doc.ownerId === user.id || user.role === "admin";
}

// switch with fall-through (intentional)
switch (code) {
  case 200:
  case 201:
    return "ok";
  case 404:
    return "missing";
  default:
    return "error";
}

// switch (true) pattern
switch (true) {
  case score >= 90:
    return "A";
  case score >= 80:
    return "B";
  default:
    return "C";
}

// Short-circuit
isReady && start();
value || fallback; // prefer ?? for nullish-only
exists ? use(exists) : create();

// Numeric range
if (n >= 1 && n <= 10) {
  /* ... */
}
```

```js
// Nullish check without truthiness
if (count != null) {
  // allows 0
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `if (arr)` is always true for empty arrays — check `arr.length`.
* Assignment in condition `if (x = y)` is legal and often a bug — use `===`.
* `switch` without `break` falls through — use `break` or `return`.
* `switch` uses `===` — no coercion between `"1"` and `1`.
* Deep nesting hurts readability — extract functions / use lookup maps.

## 🔗 Related [#-related]

* [ternary.md](/docs/javascript/ternary) — conditional expressions
* [boolean.md](/docs/javascript/boolean) — booleans
* [equality.md](/docs/javascript/equality) — === vs ==
* [switch\_case.md](/docs/javascript/switch-case) — switch deep dive
* [nullish\_coalescing.md](/docs/javascript/nullish-coalescing) — defaults


# Console (/docs/javascript/console)



# Console [#console]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`console` is the standard debugging surface in browsers and Node. Beyond `log`, use levels, grouping, timing, and tabular output. Prefer structured messages over string concatenation.

## 🔧 Core concepts [#-core-concepts]

* **Levels**: `debug`, `log`, `info`, `warn`, `error` (filterable in DevTools).
* **Format**: `%s`, `%d`, `%o`, `%c` (CSS in browsers).
* **Groups**: `group` / `groupCollapsed` / `groupEnd`.
* **Timing**: `time` / `timeLog` / `timeEnd`.
* **Tables**: `console.table(arrayOrObject)`.
* **Assertions**: `console.assert(cond, ...msg)` logs only when falsy.
* **Counts**: `count` / `countReset`.
* **Traces**: `console.trace()` prints a stack.

```js
console.log("user=%s id=%d", "Ada", 42);
console.warn("deprecated");
console.error(new Error("fail"));
```

## 💡 Examples [#-examples]

```js
const users = [
  { id: 1, name: "Ada" },
  { id: 2, name: "Alan" },
];
console.table(users);

console.group("request");
console.log("method", "GET");
console.log("path", "/api");
console.groupEnd();

console.time("work");
await doWork();
console.timeEnd("work");

console.count("hit");
console.count("hit");
console.countReset("hit");

console.assert(users.length > 0, "expected users");

// Styled (browser)
console.log("%cOK", "color: green; font-weight: bold");

// Inspect depth (Node)
console.dir(users[0], { depth: null });

// Clear
// console.clear();
```

```js
// Debug-only helper
const debug = (...args) => {
  if (import.meta.env?.DEV ?? process.env.NODE_ENV !== "production") {
    console.debug(...args);
  }
};

debug("payload", { ok: true });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Logging live objects shows later mutations in some DevTools — log clones or primitives when needed.
* `console.log` in hot paths hurts performance; gate behind flags.
* Stringifying secrets into logs is a security risk — redact tokens.
* `assert` does not throw; use real assertions for control flow.
* Node and browsers differ slightly (`dir`, `%c` support).

## 🔗 Related [#-related]

* [error.md](/docs/javascript/error) — Error objects and stacks
* [json.md](/docs/javascript/json) — pretty-print data
* [api.md](/docs/javascript/api) — runtime globals
* [objects.md](/docs/javascript/objects) — inspecting structures


# Crypto (/docs/javascript/crypto-node)



# Crypto [#crypto]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js `node:crypto` provides hashing, HMAC, random bytes, UUIDs, and more (ciphers, key derivation). Prefer the built-in module over ad-hoc hashing. For passwords use a dedicated KDF (`scrypt`, `pbkdf2`, or `argon2` via libs) — not raw `createHash`.

```js
import crypto from "node:crypto";
```

## 🔧 Core concepts [#-core-concepts]

* **`createHash(algo)`**: one-way digest (`sha256`, `sha512`, `md5`…). Chain `.update().digest()`.
* **`randomUUID()`**: RFC 4122 v4 UUID string (cryptographically strong).
* **`randomBytes(n)`**: `n` cryptographically strong random bytes (`Buffer`); sync or callback/promise forms.
* **`createHmac(algo, key)`**: keyed hash for integrity with a secret.
* **Timing-safe compare**: `timingSafeEqual(a, b)` for secrets/hashes (same length required).

## 💡 Examples [#-examples]

```js
import crypto from "node:crypto";

const hash = crypto.createHash("sha256").update("hello", "utf8").digest("hex");

const id = crypto.randomUUID(); // '3b9f…'

const buf = crypto.randomBytes(16);
const token = buf.toString("hex");

const hmac = crypto
  .createHmac("sha256", process.env.SECRET ?? "dev")
  .update("payload")
  .digest("hex");

// Promise API (Node 15+)
import { randomBytes, randomUUID } from "node:crypto";
const bytes = await randomBytes(32);

function sha256FileBuffer(buf) {
  return crypto.createHash("sha256").update(buf).digest("hex");
}

// Compare digests safely
const a = Buffer.from(hash, "hex");
const b = Buffer.from(hash, "hex");
crypto.timingSafeEqual(a, b); // true
```

```js
// Password hashing sketch — prefer scrypt
const salt = crypto.randomBytes(16);
const key = crypto.scryptSync("password", salt, 64);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `md5` / `sha1` are broken for security — use only for checksums if required.
* Never store passwords as plain `sha256(password)`; use salted slow KDFs.
* `timingSafeEqual` throws if lengths differ — check length first or pad carefully.
* `Math.random()` is not crypto-safe; use `randomBytes` / `randomUUID`.
* Streaming large inputs: call `.update()` multiple times, then `.digest()` once.

## 🔗 Related [#-related]

* [Buffer](/docs/javascript/buffer) — digests and random bytes as Buffers
* [fs](/docs/javascript/fs) — hash file contents
* [process](/docs/javascript/process) — secrets via `process.env`
* [Stream](/docs/javascript/stream) — hash while piping
* [encode](/docs/javascript/encode) — encoding helpers adjacent to hex/base64


# CSV (/docs/javascript/csv)



# CSV [#csv]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CSV is comma-separated text (RFC 4180–style). JavaScript has no built-in CSV parser. For simple rows you can split carefully; for real data use a library such as **Papa Parse** (browser/Node) or **csv-parse** / **csv-stringify** (Node streams).

## 🔧 Core concepts [#-core-concepts]

* **Rows / fields**: lines of records; fields separated by `,` (or `;`, `\t`).
* **Quoting**: fields with commas/newlines wrap in `"`; `""` escapes a quote.
* **Header row**: optional first line of column names.
* **Manual parse**: fine for trusted, simple files without embedded commas.
* **Libraries**: Papa Parse (`Papa.parse` / `Papa.unparse`); Node `csv-parse` + `csv-stringify`.

## 💡 Examples [#-examples]

```js
// Manual — only if no commas inside fields
function parseSimpleCsv(text) {
  return text
    .trim()
    .split(/\r?\n/)
    .map((line) => line.split(","));
}

function toSimpleCsv(rows) {
  return rows.map((r) => r.join(",")).join("\n");
}

const rows = parseSimpleCsv("name,age\nAda,36\n");
```

```js
// Escape a field for RFC-ish output
function csvField(value) {
  const s = String(value ?? "");
  if (/[",\n\r]/.test(s)) return `"${s.replaceAll('"', '""')}"`;
  return s;
}

function rowsToCsv(rows) {
  return rows.map((row) => row.map(csvField).join(",")).join("\n");
}
```

```js
// Papa Parse (npm: papaparse)
import Papa from "papaparse";

const parsed = Papa.parse(csvText, { header: true, skipEmptyLines: true });
// parsed.data → array of objects
const out = Papa.unparse(parsed.data);
```

```js
// Node csv-parse (npm: csv-parse)
import { parse } from "csv-parse/sync";
import { readFile } from "node:fs/promises";

const input = await readFile("data.csv", "utf8");
const records = parse(input, { columns: true, skip_empty_lines: true });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Naïve `split(",")` breaks on quoted commas and newlines inside fields.
* Locale exports may use `;` as separator — do not assume `,`.
* Excel often expects UTF-8 BOM for Unicode; add `\uFEFF` when needed.
* Large files: prefer streaming parsers (`csv-parse` stream API), not full-string parse.
* Type coercion: CSV is all strings until you convert numbers/dates yourself.

## 🔗 Related [#-related]

* [JSON](/docs/javascript/json) — structured alternative to CSV
* [fs](/docs/javascript/fs) — read/write CSV files in Node
* [Strings](/docs/javascript/strings) — split / replace helpers
* [Async](/docs/javascript/async) — async file + parse flows
* [fetch](/docs/javascript/fetch) — download CSV over HTTP


# Date (/docs/javascript/date)



# Date [#date]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`Date` represents an instant in time as milliseconds since the Unix epoch (UTC). Local getters/setters use the host timezone. Prefer ISO 8601 strings and libraries (Temporal, Luxon, dayjs) for calendars and time zones when complexity grows.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new Date()`, `new Date(ms)`, `new Date(isoString)`, `Date.UTC(...)`.
* **Epoch**: `Date.now()`, `date.getTime()`, `+date`.
* **UTC vs local**: `getUTC*` / `setUTC*` vs `get*` / `set*`.
* **Format**: `toISOString()`, `toLocaleString(locale, options)`, `Intl.DateTimeFormat`.
* **Parse**: `Date.parse(string)` — implementation-defined for non-ISO forms.

```js
const now = new Date();
const utc = Date.UTC(2026, 0, 15); // month 0-based
const fromIso = new Date("2026-07-10T08:00:00.000Z");
```

## 💡 Examples [#-examples]

```js
// Add days safely via ms
function addDays(date, days) {
  return new Date(date.getTime() + days * 86_400_000);
}

// Start of local day
function startOfLocalDay(d = new Date()) {
  const x = new Date(d);
  x.setHours(0, 0, 0, 0);
  return x;
}

// Locale format
const fmt = new Intl.DateTimeFormat("en-US", {
  dateStyle: "medium",
  timeStyle: "short",
  timeZone: "America/Los_Angeles",
});
console.log(fmt.format(new Date()));

// Relative (where supported)
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
console.log(rtf.format(-1, "day")); // yesterday

// Diff in whole days (UTC calendar-ish)
function diffDays(a, b) {
  const ms = Date.UTC(b.getFullYear(), b.getMonth(), b.getDate())
    - Date.UTC(a.getFullYear(), a.getMonth(), a.getDate());
  return ms / 86_400_000;
}

// Valid check
function isValidDate(d) {
  return d instanceof Date && !Number.isNaN(d.getTime());
}
```

```js
// Prefer ISO for interchange
JSON.stringify({ at: new Date() }); // {"at":"2026-...Z"} via toJSON

// Manual components (months are 0–11!)
const d = new Date(2026, 6, 10); // Jul 10, 2026 local
```

## ⚠️ Pitfalls [#️-pitfalls]

* Months are **0-based** in the `Date` constructor and setters.
* `new Date("YYYY-MM-DD")` is parsed as UTC; `YYYY-MM-DDTHH:mm` may be local — prefer full ISO with `Z` or offset.
* Invalid dates have `getTime() === NaN`.
* Mutator methods mutate the instance — clone before changing shared dates.
* DST makes “add one day” via `setDate` safer than fixed hours in local math for calendar days.

## 🔗 Related [#-related]

* [number.md](/docs/javascript/number) — timestamps as numbers
* [json.md](/docs/javascript/json) — Date serialization
* [api.md](/docs/javascript/api) — Intl and runtime helpers
* [strings.md](/docs/javascript/strings) — ISO string handling
* [math.md](/docs/javascript/math) — rounding durations


# Destructuring (/docs/javascript/destructuring)



# Destructuring [#destructuring]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Destructuring unpacks values from arrays or properties from objects into distinct variables. It works in assignments, function parameters, and `for...of` loops. Combine with defaults, rest, and renaming for concise, safe extraction.

## 🔧 Core concepts [#-core-concepts]

* **Array**: position-based — `const [a, b] = list`.
* **Object**: name-based — `const \{ x, y \} = obj`.
* **Defaults**: `const \{ a = 1 \} = \{\}` / `const [a = 1] = []`.
* **Rename**: `const \{ name: userName \} = user`.
* **Rest**: `const [head, ...tail] = arr` / `const \{ a, ...rest \} = obj`.
* **Nested**: patterns can nest arbitrarily.
* **Params**: `function f(\{ id, ...opts \} = \{\}) \{\}`.

```js
const [first, second] = [10, 20];
const { title, year = 2020 } = { title: "Guide" };
```

## 💡 Examples [#-examples]

```js
// Swap
let a = 1,
  b = 2;
[a, b] = [b, a];

// Skip slots
const [, , third] = ["a", "b", "c"]; // "c"

// Nested object
const res = { data: { user: { id: 1, name: "Ada" } } };
const {
  data: {
    user: { name },
  },
} = res;

// Rename + default
const { width: w = 100, height: h = 100 } = { width: 80 };

// Function params
function connect({ host = "localhost", port = 5432, ssl = true } = {}) {
  return `${host}:${port} ssl=${ssl}`;
}

// Iterate Map / entries
for (const [key, value] of Object.entries({ a: 1, b: 2 })) {
  console.log(key, value);
}

// Rest object (omit keys)
const user = { id: 1, name: "Ada", password: "secret" };
const { password, ...safe } = user;

// Computed property names
const key = "score";
const { [key]: score } = { score: 99 };
```

```js
// Array from iterable
const [x, y] = new Set([1, 2, 3]); // 1, 2
```

## ⚠️ Pitfalls [#️-pitfalls]

* Destructuring `null`/`undefined` throws — guard: `const \{ a \} = obj ?? \{\}`.
* Array holes and missing props become `undefined` (then defaults apply).
* Object rest copies enumerable own properties only (shallow).
* Pattern `const \{ length \} = "hi"` works (strings are array-like) but prefer explicit APIs.
* Left-hand patterns in assignment need parentheses when starting with `\{`: `(\{ a \} = obj)`.

## 🔗 Related [#-related]

* [spread\_rest.md](/docs/javascript/spread-rest) — rest/spread siblings
* [objects.md](/docs/javascript/objects) — object shapes
* [arrays.md](/docs/javascript/arrays) — array unpacking
* [functions.md](/docs/javascript/functions) — param destructuring
* [optional\_chaining.md](/docs/javascript/optional-chaining) — safe deep access


# dotenv (/docs/javascript/dotenv)



# dotenv [#dotenv]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

In Node.js, configuration often lives in environment variables via `process.env`. The popular `dotenv` package loads a `.env` file into `process.env` at startup. Never commit secrets; use `.env.example` for templates.

```shellscript
npm install dotenv
```

## 🔧 Core concepts [#-core-concepts]

* **`process.env.KEY`**: always a string (or `undefined` if unset).
* **`dotenv.config()`**: reads `.env` from cwd by default; does not overwrite existing env vars.
* **`.env` syntax**: `KEY=value`, comments with `#`, optional quotes.
* **Precedence**: real environment (shell, CI, host) wins over `.env` unless you opt into override.
* **Validation**: check required keys early and exit with a clear error.

## 💡 Examples [#-examples]

```js
// CommonJS
require("dotenv").config();

// ESM (early in entry file)
import "dotenv/config";
// or
import dotenv from "dotenv";
dotenv.config({ path: ".env.local" });

const port = Number(process.env.PORT ?? "3000");
const dbUrl = process.env.DATABASE_URL;

if (!dbUrl) {
  console.error("Missing DATABASE_URL");
  process.exit(1);
}

// Optional override (use carefully)
dotenv.config({ override: true });

// Typed-ish helper
function requireEnv(name) {
  const v = process.env[name];
  if (v === undefined || v === "") {
    throw new Error(`Missing env: ${name}`);
  }
  return v;
}

const apiKey = requireEnv("API_KEY");
```

```ini
# .env
PORT=9000
DATABASE_URL=postgres://localhost:5432/app
# FEATURE_FLAG=true
```

## ⚠️ Pitfalls [#️-pitfalls]

* `process.env` values are strings: `"false"` is truthy; parse booleans/numbers explicitly.
* `dotenv` does not magically load in every worker/child — call config in each process entry.
* Do not rely on `.env` in production if the platform injects env vars (Render, Netlify, etc.).
* Avoid putting secrets in client bundles; `dotenv` is a Node/server concern.
* Empty `KEY=` sets `process.env.KEY` to `""`, not `undefined`.

## 🔗 Related [#-related]

* [process](/docs/javascript/process) — `process.env`, `argv`, `exit`
* [fs](/docs/javascript/fs) — reading config files manually
* [JSON](/docs/javascript/json) — config as JSON instead of `.env`
* [CommonJS modules](/docs/javascript/modules-commonjs) — `require("dotenv")`
* [ESM import/export](/docs/javascript/import-export) — `import "dotenv/config"`


# Encode / Decode (/docs/javascript/encode)



# Encode / Decode [#encode--decode]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Encoding turns text into safe wire formats: URI components, percent-encoding, and Base64. Use the right API for path vs query vs full URI. Pair with `TextEncoder` for UTF-8 bytes.

## 🔧 Core concepts [#-core-concepts]

* **`encodeURI` / `decodeURI`**: encode a full URI; leaves `#`, `?`, `/`, etc.
* **`encodeURIComponent` / `decodeURIComponent`**: encode a single component (query values, path segments).
* **`URL` / `URLSearchParams`**: prefer structured URL building over manual concat.
* **Base64**: `btoa` / `atob` (Latin-1); use byte-safe helpers for UTF-8.
* **UTF-8 bytes**: `TextEncoder` / `TextDecoder`.

```js
encodeURIComponent("a b&c"); // a%20b%26c
decodeURIComponent("a%20b%26c"); // a b&c
```

## 💡 Examples [#-examples]

```js
const q = new URLSearchParams({ q: "café & tea", page: "1" });
console.log(q.toString()); // q=caf%C3%A9+%26+tea&page=1

const url = new URL("https://example.com/search");
url.searchParams.set("q", "hello world");
console.log(url.href);

// Path segment
const slug = encodeURIComponent("foo/bar"); // foo%2Fbar

// UTF-8 Base64
function utf8ToBase64(str) {
  const bytes = new TextEncoder().encode(str);
  let bin = "";
  for (const b of bytes) bin += String.fromCharCode(b);
  return btoa(bin);
}

function base64ToUtf8(b64) {
  const bin = atob(b64);
  const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

console.log(base64ToUtf8(utf8ToBase64("✓")));

// application/x-www-form-urlencoded
const body = new URLSearchParams({ email: "a@b.co", remember: "1" });
await fetch("/login", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body,
});
```

```js
// Wrong vs right for query values
const bad = "https://x.test/?q=" + encodeURI("a&b"); // & still breaks
const good = "https://x.test/?q=" + encodeURIComponent("a&b");
```

## ⚠️ Pitfalls [#️-pitfalls]

* Never use `encodeURI` for query parameter values — use `encodeURIComponent`.
* Double-encoding (`encode` then `encode` again) breaks servers.
* `decodeURIComponent` throws `URIError` on malformed sequences — wrap in try/catch.
* `+` in query strings often means space; `URLSearchParams` handles this.
* `btoa("✓")` throws — encode UTF-8 bytes first.

## 🔗 Related [#-related]

* [url.md](/docs/javascript/url) — URL and search params
* [fetch.md](/docs/javascript/fetch) — request bodies
* [strings.md](/docs/javascript/strings) — string ops
* [api.md](/docs/javascript/api) — TextEncoder / crypto
* [json.md](/docs/javascript/json) — JSON payloads


# Equality (/docs/javascript/equality)



# Equality [#equality]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

JavaScript has strict equality (`===` / `!==`), loose equality (`==` / `!=`) with coercion, and `Object.is` for SameValue semantics. Prefer `===` almost always; use `Object.is` for `NaN` and ±0 edge cases; avoid `==` except intentional nullish checks.

## 🔧 Core concepts [#-core-concepts]

| Op               | Rule                                              |
| ---------------- | ------------------------------------------------- |
| `===`            | Same type + value; no coercion; `NaN !== NaN`     |
| `==`             | Coerces then compares (complex rules)             |
| `Object.is(a,b)` | SameValue: `NaN` equals `NaN`; `-0` ≠ `+0`        |
| `SameValueZero`  | Used by `Map`/`Set`: `NaN` equals `NaN`, ±0 equal |

* **`null == undefined`** is `true&#x60;; &#x2A;*`null === undefined`** is `false`.
* **Objects**: equality is by reference, not deep content.

```js
1 === "1"; // false
1 == "1"; // true
Object.is(NaN, NaN); // true
```

## 💡 Examples [#-examples]

```js
// Prefer strict
if (status === 200) {
  /* ... */
}

// Intentional nullish (either)
if (value == null) {
  // value is null or undefined
}

// NaN checks
Number.isNaN(x); // preferred over x === NaN
Object.is(x, NaN);

// Zeros
+0 === -0; // true
Object.is(+0, -0); // false

// Objects
const a = { x: 1 };
const b = { x: 1 };
a === b; // false
a === a; // true

// Arrays / boxed
[] == false; // true (avoid!)
[1] == true; // false weirdness — never use == with objects

// Map keying uses SameValueZero
const m = new Map();
m.set(NaN, "yes");
m.get(NaN); // "yes"
```

```js
// Deep equality — use a library or structured approach
function shallowEq(a, b) {
  return Object.keys(a).length === Object.keys(b).length &&
    Object.keys(a).every((k) => a[k] === b[k]);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `==` with mixed types is a footgun (`"" == 0`, `null == undefined`, arrays).
* `NaN === NaN` is false — use `Number.isNaN` / `Object.is`.
* Document / iframe boundaries: different `Object` constructors break `instanceof` and sometimes expectations.
* Floating point: `0.1 + 0.2 !== 0.3` — compare with epsilon, not `===`.

## 🔗 Related [#-related]

* [type\_coercion.md](/docs/javascript/type-coercion) — how `==` coerces
* [boolean.md](/docs/javascript/boolean) — truthiness
* [nullish\_coalescing.md](/docs/javascript/nullish-coalescing) — nullish ops
* [object / map](/docs/javascript/map) — SameValueZero keys
* [number.md](/docs/javascript/number) — NaN and floats


# Errors (/docs/javascript/error)



# Errors [#errors]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Errors interrupt normal control flow. Use `try` / `catch` / `finally`, typed error classes, and rethrow carefully. Prefer throwing `Error` (or subclasses) over strings so stacks and `cause` work.

## 🔧 Core concepts [#-core-concepts]

* **Built-ins**: `Error`, `TypeError`, `RangeError`, `SyntaxError`, `URIError`, `AggregateError`.
* **Properties**: `name`, `message`, `stack`, `cause` (ES2022).
* **Throw**: `throw new Error("msg", \{ cause \})`.
* **Catch**: bind the error; optional binding omission in some engines for unused catches.
* **`finally`**: always runs (cleanup), even on return.
* **Async**: rejections surface at `await` or `.catch`.

```js
try {
  JSON.parse("{");
} catch (err) {
  console.error(err.name, err.message);
} finally {
  console.log("done");
}
```

## 💡 Examples [#-examples]

```js
class HttpError extends Error {
  constructor(status, message, options) {
    super(message, options);
    this.name = "HttpError";
    this.status = status;
  }
}

async function getJson(url) {
  try {
    const res = await fetch(url);
    if (!res.ok) {
      throw new HttpError(res.status, res.statusText);
    }
    return await res.json();
  } catch (err) {
    throw new Error(`getJson failed: ${url}`, { cause: err });
  }
}

// Narrowing
function isHttpError(e) {
  return e instanceof HttpError;
}

try {
  await getJson("/api");
} catch (e) {
  if (isHttpError(e) && e.status === 404) {
    console.warn("missing");
  } else {
    throw e; // rethrow unknown
  }
}

// AggregateError (Promise.any)
try {
  await Promise.any([Promise.reject("a"), Promise.reject("b")]);
} catch (e) {
  if (e instanceof AggregateError) {
    console.log(e.errors);
  }
}

// Optional catch binding (when unused)
try {
  risky();
} catch {
  /* ignore */
}
```

```js
// AbortError from fetch
const ac = new AbortController();
fetch(url, { signal: ac.signal }).catch((err) => {
  if (err.name === "AbortError") return;
  console.error(err);
});
ac.abort();
```

## ⚠️ Pitfalls [#️-pitfalls]

* Catching everything and swallowing errors hides bugs — rethrow unknowns.
* `throw "string"` loses stack traces — throw `Error` instances.
* `finally` can override a returned/thrown value if it returns or throws itself.
* Async errors outside `try` around `await` become unhandled rejections.
* `instanceof` fails across realms/iframes — check `name` as fallback.

## 🔗 Related [#-related]

* [promise.md](/docs/javascript/promise) — rejection handling
* [async.md](/docs/javascript/async) — await + try/catch
* [fetch.md](/docs/javascript/fetch) — HTTP failures
* [console.md](/docs/javascript/console) — logging errors
* [api.md](/docs/javascript/api) — AbortController


# Event Loop (/docs/javascript/event-loop)



# Event Loop [#event-loop]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

JavaScript runs on a single thread with an event loop that drains task queues. Understanding macrotasks vs microtasks explains Promise ordering, `setTimeout(0)`, UI updates, and why long sync work freezes the page.

## 🔧 Core concepts [#-core-concepts]

* **Call stack**: runs synchronous code to completion.
* **Macrotasks (tasks)**: `setTimeout`, `setInterval`, I/O, UI events, `MessageChannel`, `setImmediate` (Node).
* **Microtasks**: Promise reactions, `queueMicrotask`, `MutationObserver` callbacks.
* **Order**: after each task, the engine drains **all** microtasks before the next macrotask / render.
* **Rendering**: browsers may paint between tasks (not between microtasks).
* **Workers**: separate event loops / threads.

```js
console.log("a");
setTimeout(() => console.log("c"), 0);
Promise.resolve().then(() => console.log("b"));
// a, b, c
```

## 💡 Examples [#-examples]

```js
queueMicrotask(() => console.log("micro"));
Promise.resolve().then(() => console.log("then"));
setTimeout(() => console.log("timeout"), 0);
console.log("sync");
// sync → micro → then → timeout

// Microtask starvation risk
function flood() {
  Promise.resolve().then(flood);
}
// flood(); // never reaches next macrotask / paint

// Yield to the event loop
async function yieldToMain() {
  await new Promise((r) => setTimeout(r, 0));
}

async function processChunks(items) {
  for (const item of items) {
    work(item);
    await yieldToMain();
  }
}

// async function scheduling
async function demo() {
  console.log(1);
  await null; // microtask continuation
  console.log(2);
}
demo();
console.log(3);
// 1, 3, 2
```

```js
// Node: process.nextTick (microtask-like, before Promises historically)
// Prefer queueMicrotask / Promises for portable code
```

## ⚠️ Pitfalls [#️-pitfalls]

* `setTimeout(fn, 0)` is not “immediate” — it waits for the current task + microtasks + timer clamping.
* Infinite microtask chains block rendering and timers.
* Assuming Promise callbacks run in parallel — they are still sequential on one thread.
* Heavy sync work (JSON.parse huge data, tight loops) blocks everything — chunk or move to workers.
* Error in a microtask can surface differently than in a timer callback.

## 🔗 Related [#-related]

* [promise.md](/docs/javascript/promise) — microtask reactions
* [async.md](/docs/javascript/async) — async/await desugaring
* [timers.md](/docs/javascript/timers) — macrotask timers
* [web\_workers.md](/docs/javascript/web-workers) — off-main-thread
* [DOM/events.md](/docs/javascript/dom/events) — event tasks


# Events (/docs/javascript/events-node)



# Events [#events]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js `EventEmitter` (`node:events`) is the pub/sub backbone for streams, servers, and many core APIs. Objects emit named events; listeners run when those events fire. Browser DOM events are different — see DOM Events for UI.

```js
import { EventEmitter } from "node:events";
```

## 🔧 Core concepts [#-core-concepts]

* **`on(event, listener)` / `addListener`**: register a lasting handler.
* **`once(event, listener)`**: run at most once, then remove.
* **`emit(event, ...args)`**: call listeners synchronously in registration order.
* **`off` / `removeListener` / `removeAllListeners`**: unsubscribe.
* **`prependListener`**: run before previously registered handlers.
* **Error event**: if `error` is emitted with no listeners, Node throws.
* **`EventEmitter` subclassing**: common pattern for custom components.

## 💡 Examples [#-examples]

```js
import { EventEmitter } from "node:events";

const bus = new EventEmitter();

bus.on("data", (chunk) => console.log("got", chunk));
bus.once("ready", () => console.log("ready once"));

bus.emit("ready");
bus.emit("ready"); // no-op for once
bus.emit("data", { n: 1 });

bus.off("data", handler); // need same function reference

class Job extends EventEmitter {
  start() {
    this.emit("start");
    try {
      // work…
      this.emit("done", { ok: true });
    } catch (err) {
      this.emit("error", err);
    }
  }
}

const job = new Job();
job.on("error", (err) => console.error(err));
job.start();
```

```js
import { once } from "node:events";
// Promise that resolves on next event
const [value] = await once(bus, "data");
```

## ⚠️ Pitfalls [#️-pitfalls]

* Listeners are sync: a slow handler blocks subsequent listeners and the emitter.
* Missing `error` listener can crash the process when `emit("error", err)` runs.
* Memory leaks: forgetting to `off` long-lived emitters (set `setMaxListeners` only after understanding why).
* Arrow vs bound methods: remove requires the same function reference you added.
* Do not confuse with DOM `EventTarget` — APIs differ (`addEventListener` vs `on`).

## 🔗 Related [#-related]

* [DOM Events](/docs/javascript/dom/events) — browser event model
* [Stream](/docs/javascript/stream) — streams extend EventEmitter patterns
* [Async](/docs/javascript/async) — `once()` promise helper
* [Promise](/docs/javascript/promise) — bridging events to promises
* [this keyword](/docs/javascript/this-keyword) — listener `this` binding


# Fetch (/docs/javascript/fetch)



# Fetch [#fetch]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`fetch` performs HTTP requests and returns a Promise of `Response`. It only rejects on network failure or abort — HTTP 4xx/5xx still resolve. Always check `response.ok` or `status`.

## 🔧 Core concepts [#-core-concepts]

* **Call**: `fetch(input, init?)` → `Promise<Response>`.
* **Init**: `method`, `headers`, `body`, `credentials`, `signal`, `cache`, `redirect`, `mode`.
* **Body helpers**: `res.json()`, `res.text()`, `res.blob()`, `res.arrayBuffer()`, `res.formData()`.
* **Request body**: string, `Blob`, `FormData`, `URLSearchParams`, `ReadableStream`, `ArrayBuffer`.
* **Abort**: pass `AbortSignal` via `signal`.

```js
const res = await fetch("/api/items");
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
```

## 💡 Examples [#-examples]

```js
// JSON POST
async function createUser(user) {
  const res = await fetch("/api/users", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify(user),
  });
  if (!res.ok) {
    const err = await res.text();
    throw new Error(err || res.statusText);
  }
  return res.json();
}

// Query string
const url = new URL("/search", location.origin);
url.searchParams.set("q", "js");
const list = await fetch(url).then((r) => r.json());

// Timeout via AbortSignal
async function fetchWithTimeout(resource, ms, options = {}) {
  const signal = AbortSignal.timeout(ms);
  return fetch(resource, { ...options, signal });
}

// Credentials (cookies)
await fetch("/api/me", { credentials: "include" });

// Upload FormData
const fd = new FormData();
fd.append("file", fileInput.files[0]);
fd.append("title", "doc");
await fetch("/upload", { method: "POST", body: fd });

// Read headers
const res = await fetch("/api");
console.log(res.headers.get("content-type"));
```

```js
// Stream response body
const res = await fetch("/large.bin");
const reader = res.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log("chunk", value.byteLength);
}

// Parallel requests
const [a, b] = await Promise.all([
  fetch("/a").then((r) => r.json()),
  fetch("/b").then((r) => r.json()),
]);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `fetch` does not throw on 404/500 — check `ok` / `status`.
* Body can be consumed once — clone with `res.clone()` if needed twice.
* Default `credentials` is `"same-origin"`; cross-site cookies need `"include"` + CORS.
* Setting `Content-Type` manually on `FormData` breaks the multipart boundary.
* Opaque responses (`mode: "no-cors"`) hide status and body.

## 🔗 Related [#-related]

* [promise.md](/docs/javascript/promise) — Promise combinators
* [async.md](/docs/javascript/async) — async/await
* [json.md](/docs/javascript/json) — JSON bodies
* [url.md](/docs/javascript/url) — URL building
* [encode.md](/docs/javascript/encode) — form encoding
* [error.md](/docs/javascript/error) — error wrapping
* [api.md](/docs/javascript/api) — AbortSignal
* [DOM/form.md](/docs/javascript/dom/form) — FormData from forms


# for...of (/docs/javascript/for-of)



# for...of [#forof]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`for...of` iterates values from any iterable (`Array`, `String`, `Map`, `Set`, generators, DOM collections that are iterable). Prefer it over index loops when you need values, not indices.

## 🔧 Core concepts [#-core-concepts]

* **Syntax**: `for (const item of iterable) \{ ... \}`.
* **Bindings**: `const` / `let` / destructuring per iteration.
* **Control**: `break`, `continue`, `return` (from enclosing function).
* **Async**: `for await (const x of asyncIterable)`.
* **vs `for...in`**: `in` enumerates keys; `of` yields values.

```js
for (const n of [10, 20, 30]) {
  console.log(n);
}
```

## 💡 Examples [#-examples]

```js
// Entries with index
for (const [i, v] of ["a", "b"].entries()) {
  console.log(i, v);
}

// Strings (Unicode code points with for...of)
for (const ch of "A🙂B") {
  console.log(ch);
}

// Map / Set
const m = new Map([["x", 1], ["y", 2]]);
for (const [k, v] of m) console.log(k, v);

for (const v of new Set([1, 1, 2])) console.log(v);

// Destructure objects in arrays
const rows = [{ id: 1 }, { id: 2 }];
for (const { id } of rows) console.log(id);

// early exit
for (const n of nums) {
  if (n < 0) break;
}

// NodeList (modern browsers — iterable)
for (const el of document.querySelectorAll("li")) {
  el.classList.add("ready");
}

// Async iterable
async function consume(stream) {
  for await (const chunk of stream) {
    console.log(chunk);
  }
}
```

```js
// Generator source
function* range(n) {
  for (let i = 0; i < n; i++) yield i;
}
for (const i of range(3)) console.log(i); // 0 1 2
```

## ⚠️ Pitfalls [#️-pitfalls]

* Do not use `for...in` on arrays when you want values — it yields keys as strings and enumerable prototype props.
* Closing iterators: `break` calls `return()` on the iterator if present (important for generators with `finally`).
* `for await...of` only works in async functions / modules with top-level await.
* Mutating a collection while iterating can skip items or throw — iterate a snapshot (`[...list]`).

## 🔗 Related [#-related]

* [iteration.md](/docs/javascript/iteration) — all loop styles
* [iterator.md](/docs/javascript/iterator) — iterable protocol
* [arrays.md](/docs/javascript/arrays) — array helpers
* [map.md](/docs/javascript/map) — Map iteration
* [set.md](/docs/javascript/set) — Set iteration
* [async.md](/docs/javascript/async) — for await...of
* [while.md](/docs/javascript/while) — while / do...while


# Freeze & Seal (/docs/javascript/freeze-seal)



# Freeze & Seal [#freeze--seal]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Object.freeze`, `Object.seal`, and `Object.preventExtensions` progressively lock objects against extension and mutation. They are shallow. For true immutability in apps, combine with conventions, structuredClone, or immutable libraries — and know what each level allows.

## 🔧 Core concepts [#-core-concepts]

| Method              | Add props | Delete | Reassign values | Reconfigure            |
| ------------------- | --------- | ------ | --------------- | ---------------------- |
| `preventExtensions` | ✗         | ✓\*    | ✓               | ✓                      |
| `seal`              | ✗         | ✗      | ✓               | ✗ (configurable false) |
| `freeze`            | ✗         | ✗      | ✗               | ✗                      |

\*existing configurable props can still be deleted if not sealed.

* **Checks**: `Object.isFrozen`, `isSealed`, `isExtensible`.
* **Strict mode**: failed mutations throw `TypeError`; sloppy mode fails silently.
* **Shallow**: nested objects remain mutable unless frozen too.

```js
const cfg = Object.freeze({ theme: "dark", nested: { a: 1 } });
cfg.theme = "light"; // ignored / TypeError
cfg.nested.a = 2; // still works — shallow!
```

## 💡 Examples [#-examples]

```js
"use strict";

const sealed = Object.seal({ x: 1 });
sealed.x = 2; // OK
// sealed.y = 3; // TypeError
// delete sealed.x; // TypeError

const frozen = Object.freeze({ x: 1 });
// frozen.x = 2; // TypeError

Object.preventExtensions(arrLike);
// arrLike.newProp = 1; // TypeError

// Deep freeze (simple)
function deepFreeze(obj) {
  Object.freeze(obj);
  for (const value of Object.values(obj)) {
    if (value && typeof value === "object" && !Object.isFrozen(value)) {
      deepFreeze(value);
    }
  }
  return obj;
}

// Constants pattern
const ROUTES = Object.freeze({
  HOME: "/",
  ABOUT: "/about",
});

// Arrays
const list = Object.freeze([1, 2, 3]);
// list.push(4); // TypeError
```

```js
// Copy then freeze
const next = Object.freeze({ ...state, count: state.count + 1 });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Shallow freeze is the #1 surprise — nested mutation still works.
* Freezing does not make values deeply immutable or protect against Proxy targets specially.
* `const` ≠ immutable — only rebinding is blocked; freeze the object too.
* Frozen arrays reject mutator methods; some libraries assume extensible objects.
* Cannot unfreeze — make a new object instead.

## 🔗 Related [#-related]

* [objects.md](/docs/javascript/objects) — property descriptors
* [strict\_mode.md](/docs/javascript/strict-mode) — TypeError on mutate
* [structured\_clone.md](/docs/javascript/structured-clone) — deep copy
* [proxy\_reflect.md](/docs/javascript/proxy-reflect) — deeper control
* [spread\_rest.md](/docs/javascript/spread-rest) — immutable updates


# fs (/docs/javascript/fs)



# fs [#fs]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js filesystem APIs live in `node:fs`. Prefer `node:fs/promises` for async/await. Sync methods (`readFileSync`) block the event loop — fine for CLIs/startup, risky in servers.

```js
import fs from "node:fs/promises";
import { readFileSync } from "node:fs";
```

## 🔧 Core concepts [#-core-concepts]

* **`readFile(path, encoding?)`**: returns `Buffer` by default; pass `"utf8"` for a string.
* **`writeFile(path, data, options?)`**: creates/overwrites; `\{ flag: "a" \}` to append.
* **`mkdir(path, \{ recursive: true \})`**: create nested directories.
* **`readdir(path, \{ withFileTypes: true \})`**: list entries; Dirent has `isFile()` / `isDirectory()`.
* **`rm(path, \{ recursive, force \})`**: delete files or trees (replaces older `rmdir`/`unlink` combos).
* **Sync vs async**: `*Sync` blocks; promises/`fs.callbacks` do not.

## 💡 Examples [#-examples]

```js
import fs from "node:fs/promises";
import path from "node:path";

const text = await fs.readFile("notes.txt", "utf8");
await fs.writeFile("out.txt", text, "utf8");

await fs.mkdir(path.join("data", "cache"), { recursive: true });

const entries = await fs.readdir("data", { withFileTypes: true });
for (const ent of entries) {
  console.log(ent.name, ent.isDirectory() ? "dir" : "file");
}

await fs.rm("tmp/build", { recursive: true, force: true });

// Copy / rename
await fs.copyFile("a.json", "b.json");
await fs.rename("b.json", "c.json");

// Sync (scripts / one-shot tools)
import { readFileSync, writeFileSync } from "node:fs";
const cfg = readFileSync("config.json", "utf8");
writeFileSync("config.bak.json", cfg);
```

```js
// Ensure parent dir before write
async function writeSafe(file, data) {
  await fs.mkdir(path.dirname(file), { recursive: true });
  await fs.writeFile(file, data, "utf8");
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting encoding yields a `Buffer`, not a string.
* `writeFile` truncates by default — use append flag or read-modify-write carefully.
* `readdir` without `withFileTypes` returns names only; you need `stat` for type.
* Race conditions: check-then-write can fail; prefer `wx` flag or atomic rename patterns.
* Sync APIs in request handlers stall other connections.

## 🔗 Related [#-related]

* [Path](/docs/javascript/path) — join / resolve paths safely
* [Async](/docs/javascript/async) — async/await with promises
* [Promise](/docs/javascript/promise) — promise basics
* [Buffer](/docs/javascript/buffer) — binary file contents
* [JSON](/docs/javascript/json) — parse config after `readFile`
* [Stream](/docs/javascript/stream) — large files without loading all


# Functions (/docs/javascript/functions)



# Functions [#functions]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Functions are first-class values: declare them, pass them, return them, and store them. Prefer `function` declarations for hoisted named APIs, arrow functions for short callbacks, and methods for object behavior. Modern JS also supports default parameters, rest parameters, and concise bodies.

## 🔧 Core concepts [#-core-concepts]

* **Declaration**: `function name() \{\}` — hoisted (name available in whole scope).
* **Expression**: `const f = function() \{\}` / `const f = () => \{\}` — not hoisted as a binding.
* **Arrow**: lexical `this`, no `arguments`, no `new`, no `prototype`.
* **Defaults**: `function f(a = 1, b = a + 1) \{\}` — evaluated left-to-right when omitted/`undefined`.
* **Rest**: `function f(...args) \{\}` — gathers remaining args into an array.
* **Return**: explicit `return`; arrow concise body returns the expression.
* **IIFE**: `(function () \{ /* private scope */ \})();`

```js
function add(a, b = 0) {
  return a + b;
}
const double = (n) => n * 2;
```

## 💡 Examples [#-examples]

```js
// Named declaration
function greet(name = "world") {
  return `Hello, ${name}`;
}

// Rest + defaults
function sum(first = 0, ...rest) {
  return rest.reduce((a, b) => a + b, first);
}
sum(1, 2, 3); // 6

// Higher-order
function once(fn) {
  let called = false;
  let result;
  return function (...args) {
    if (!called) {
      called = true;
      result = fn.apply(this, args);
    }
    return result;
  };
}

// Method shorthand
const api = {
  base: "/v1",
  get(path) {
    return fetch(this.base + path);
  },
};

// Arrow keeps outer this
class Timer {
  constructor() {
    this.ticks = 0;
  }
  start() {
    setInterval(() => {
      this.ticks += 1;
    }, 1000);
  }
}

// arguments vs rest
function legacy() {
  return Array.from(arguments);
}
const modern = (...args) => args;
```

```js
// Early return / guard clauses
function parseId(raw) {
  if (raw == null) return null;
  const n = Number(raw);
  return Number.isFinite(n) ? n : null;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Arrow functions are not constructors — `new (() => \{\})` throws.
* Arrow `this` is lexical; do not use for object methods that need dynamic `this`.
* Default params only trigger on `undefined`, not `null`.
* Excess arguments are ignored unless you use rest/`arguments`.
* Function declarations inside blocks have historically inconsistent hoisting — prefer `const` expressions in blocks.

## 🔗 Related [#-related]

* [closures.md](/docs/javascript/closures) — lexical capture
* [this\_keyword.md](/docs/javascript/this-keyword) — call-site `this`
* [destructuring.md](/docs/javascript/destructuring) — param patterns
* [spread\_rest.md](/docs/javascript/spread-rest) — rest args
* [arrow / async](/docs/javascript/async) — async functions
* [oop.md](/docs/javascript/oop) — methods & classes


# Generators (/docs/javascript/generators)



# Generators [#generators]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Generator functions (`function*`) pause with `yield` and resume later, producing an iterator. They implement the iterable protocol, enable lazy sequences, custom iteration, and cooperative async flows (often via `async function*` for async iterables).

## 🔧 Core concepts [#-core-concepts]

* **Define**: `function* gen() \{ yield 1; \}`.
* **Iterator**: `const it = gen()` → `\{ next, return, throw \}`.
* **`next(value)`**: resumes; argument becomes the result of the current `yield`.
* **`yield*`**: delegate to another iterable/generator.
* **Done**: `\{ value, done: true \}` after `return` or end.
* **Async**: `async function*` + `for await...of`.

```js
function* count(n) {
  for (let i = 0; i < n; i++) yield i;
}
[...count(3)]; // [0, 1, 2]
```

## 💡 Examples [#-examples]

```js
function* idMaker() {
  let id = 1;
  while (true) yield id++;
}
const ids = idMaker();
ids.next().value; // 1
ids.next().value; // 2

// Two-way communication
function* quiz() {
  const name = yield "What is your name?";
  return `Hello, ${name}`;
}
const q = quiz();
q.next(); // { value: "What is your name?", done: false }
q.next("Ada"); // { value: "Hello, Ada", done: true }

// yield*
function* a() {
  yield 1;
  yield* [2, 3];
  yield 4;
}

// Lazy infinite filter
function* filter(iterable, pred) {
  for (const x of iterable) if (pred(x)) yield x;
}

// Async generator
async function* streamLines(readable) {
  for await (const chunk of readable) {
    yield* String(chunk).split("\n");
  }
}

for await (const line of streamLines(res.body)) {
  console.log(line);
}
```

```js
// Early cleanup
function* withResource() {
  try {
    yield "open";
  } finally {
    console.log("cleanup");
  }
}
const r = withResource();
r.next();
r.return(); // runs finally
```

## ⚠️ Pitfalls [#️-pitfalls]

* Generators are paused, not multithreaded — still single-threaded JS.
* Forgetting `*` makes a normal function that returns a generator object only if you call another generator.
* `yield` is invalid in non-generator callbacks (e.g. inside `.map` callback) — extract a generator helper.
* Infinite generators need care with `[...gen()]` — it never finishes.
* Mixing `throw` into generators requires handling inside the generator body.

## 🔗 Related [#-related]

* [iterator.md](/docs/javascript/iterator) — iterator protocol
* [iteration.md](/docs/javascript/iteration) — for...of
* [async.md](/docs/javascript/async) — async iteration
* [event\_loop.md](/docs/javascript/event-loop) — scheduling
* [arrays.md](/docs/javascript/arrays) — materializing with spread


# Getting Started with JavaScript (/docs/javascript/getting-started)



# Getting Started with JavaScript [#getting-started-with-javascript]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

JavaScript (JS) is the language of the web browser and a popular choice on servers via Node.js. You write `.js` (or `.mjs`) files, or run snippets in browser DevTools / Node’s REPL.

## 🔧 Core concepts [#-core-concepts]

| Idea            | Meaning                                       |
| --------------- | --------------------------------------------- |
| ECMAScript (ES) | The language standard JS implements           |
| Browser runtime | JS + DOM + Web APIs                           |
| Node.js         | JS outside the browser (files, servers, CLIs) |
| Engine          | V8, SpiderMonkey, etc. execute your code      |
| Module          | Reusable file using `import` / `export`       |

**Ways to try JS:** browser console (F12), Node (`node`), or a simple HTML file with a `<script>` tag.

## 💡 Examples [#-examples]

**Check Node version:**

```shellscript
node --version
```

**REPL one-liner:**

```shellscript
node
```

```js
> console.log("Hello")
Hello
> 2 + 2
4
```

**Script file (`hello.js`):**

```js
console.log("Hello from Node");
```

```shellscript
node hello.js
```

**In the browser (inline):**

```html
<!DOCTYPE html>
<html>
  <body>
    <script>
      console.log("Hello from the browser");
    </script>
  </body>
</html>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Browser JS and Node share the language but not all APIs (`document` vs `fs`).
* Old tutorials use `var` everywhere — prefer `let` / `const`.
* Forgetting to open the console makes `console.log` look like “nothing happened.”
* File protocol + modules can be awkward; use a tiny local server when learning modules.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/javascript/hello-world)
* [variables\_let\_const.md](/docs/javascript/variables-let-const)
* [comments.md](/docs/javascript/comments)
* [typeof\_basics.md](/docs/javascript/typeof-basics)


# Glossary (/docs/javascript/glossary)



# Glossary [#glossary]

*Javascript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core JavaScript terms spanning values, functions, async flow, objects, and browser/runtime APIs.

## 🔧 Core concepts [#-core-concepts]

| Term              | Definition                                                                       |
| ----------------- | -------------------------------------------------------------------------------- |
| Array             | An ordered, indexable collection of values with array methods.                   |
| Async/await       | Syntax that pauses an async function until a Promise settles.                    |
| BigInt            | An integer type for values beyond `Number.MAX_SAFE_INTEGER`.                     |
| Boolean           | A primitive that is either `true` or `false`.                                    |
| Callback          | A function passed to another function to run later.                              |
| Closure           | A function that retains access to variables from its outer scope.                |
| Coercion          | Automatic or explicit conversion of a value from one type to another.            |
| Destructuring     | Syntax that unpacks values from arrays or properties from objects.               |
| Event loop        | The runtime mechanism that schedules macrotasks and microtasks.                  |
| Fetch             | The standard API for making HTTP requests that returns a Promise.                |
| Function          | A callable object that executes a block of code with parameters.                 |
| Generator         | A function using `function*` and `yield` that produces an iterator.              |
| Hoisting          | Moving declarations to the top of their scope during compilation.                |
| IIFE              | Immediately Invoked Function Expression that runs as soon as it is defined.      |
| Iterable          | An object that implements `[Symbol.iterator]` and can be looped with `for...of`. |
| JSON              | A text data format and global object for parse/stringify.                        |
| Map               | A collection of key–value pairs that preserves insertion order.                  |
| Module            | A file with its own scope that exports and imports bindings.                     |
| Null              | A primitive representing intentional absence of an object value.                 |
| Object            | A collection of named properties; almost everything non-primitive is one.        |
| Optional chaining | The `?.` operator that short-circuits when a reference is nullish.               |
| Promise           | An object representing a future success or failure of an async operation.        |
| Prototype         | The object linked for inheritance lookups via the prototype chain.               |
| Proxy             | An object that intercepts fundamental operations on another object.              |
| Scope             | The region of code where a binding is visible.                                   |
| Set               | A collection of unique values.                                                   |
| Spread            | The `...` syntax that expands iterables or object properties.                    |
| Strict mode       | A restricted JavaScript variant that catches silent errors.                      |
| Symbol            | A unique, immutable primitive often used as non-colliding property keys.         |
| Template literal  | A string delimited by backticks that supports interpolation and multiline text.  |
| This              | A binding whose value depends on how a function is called.                       |
| Undefined         | A primitive meaning a variable has been declared but not assigned.               |
| WeakMap           | A Map-like collection whose keys are weakly held objects.                        |

## 💡 Examples [#-examples]

**Closure and destructuring:**

```js
function makeCounter() {
  let n = 0;
  return () => ++n;
}
const { length } = [1, 2, 3];
```

**Promise with async/await:**

```js
async function loadUser(id) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error("failed");
  return res.json();
}
```

**Optional chaining and nullish coalescing:**

```js
const name = user?.profile?.name ?? "Anonymous";
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **null** (intentional empty) with **undefined** (missing value).
* Mixing &#x2A;*==*&#x2A; coercion equality with &#x2A;*===** strict equality.
* Assuming **this** always means the enclosing object — it depends on call style.
* Treating **Map** like a plain **Object** — keys and iteration differ.
* Equating **callback** hell with **Promise** chains — both are async, different control styles.

## 🔗 Related [#-related]

* [closures](/docs/javascript/closures)
* [promise](/docs/javascript/promise)
* [async](/docs/javascript/async)
* [prototypes](/docs/javascript/prototypes)
* [destructuring](/docs/javascript/destructuring)
* [event\_loop](/docs/javascript/event-loop)


# Hello World (/docs/javascript/hello-world)



# Hello World [#hello-world]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Hello World confirms your JS environment works. The usual first call is `console.log`, which writes to the browser console or the terminal (Node).

## 🔧 Core concepts [#-core-concepts]

| Piece              | Role                                                        |
| ------------------ | ----------------------------------------------------------- |
| `console.log(...)` | Print values for humans / debugging                         |
| String literal     | `"text"` or `'text'` or `` `text` ``                        |
| Statement          | An instruction, often ending with `;` (ASI may insert them) |
| Script             | Code loaded by Node or a browser                            |

Semicolons are recommended for beginners even though Automatic Semicolon Insertion exists.

## 💡 Examples [#-examples]

**Node script:**

```js
console.log("Hello, World!");
```

```shellscript
node hello.js
```

**Multiple values:**

```js
const name = "Ada";
console.log("Hello,", name);
console.log(`Hello, ${name}!`);
```

**Browser alert (UI, not for real apps):**

```js
alert("Hello, World!");
```

**Log different types:**

```js
console.log(42);
console.log(true);
console.log({ ok: true });
console.log(["a", "b"]);
```

## ⚠️ Pitfalls [#️-pitfalls]

* In the browser, look at the **Console** tab — not the page body — for `console.log`.
* `alert` blocks the UI; use it sparingly while learning.
* Smart quotes from documents break string literals.
* Running TypeScript (`.ts`) needs a toolchain; plain Hello World should be `.js`.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/javascript/getting-started)
* [variables\_let\_const.md](/docs/javascript/variables-let-const)
* [template\_basics.md](/docs/javascript/template-basics)
* [console.md](/docs/javascript/console)


# History API (/docs/javascript/history-api)



# History API [#history-api]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The History API lets SPAs update the URL and session history without full reloads: `pushState`, `replaceState`, and the `popstate` event. Pair with the Navigation API / URL patterns for modern routing. Same-origin only for state URLs.

## 🔧 Core concepts [#-core-concepts]

* **`history.pushState(state, unused, url?)`**: add entry; no reload.
* **`history.replaceState(...)`**: replace current entry.
* **`history.state`**: current state object (structured-cloneable).
* **`history.back()` / `forward()` / `go(n)`**: traverse.
* **`popstate`**: fires on back/forward (not on `pushState` itself).
* **`hashchange`**: hash-only changes (older routing style).
* **Title arg**: ignored in modern browsers — update `document.title` yourself.

```js
history.pushState({ page: 2 }, "", "/page/2");
window.addEventListener("popstate", (e) => {
  render(e.state);
});
```

## 💡 Examples [#-examples]

```js
// Navigate in SPA
function navigate(path, state = {}) {
  history.pushState(state, "", path);
  renderRoute(path, state);
}

function replace(path, state = {}) {
  history.replaceState(state, "", path);
  renderRoute(path, state);
}

window.addEventListener("popstate", (e) => {
  renderRoute(location.pathname, e.state);
});

// Initial hydrate
renderRoute(location.pathname, history.state);

// Query updates without stacking junk
const url = new URL(location.href);
url.searchParams.set("q", query);
history.replaceState(history.state, "", url);

// Scroll restoration
if ("scrollRestoration" in history) {
  history.scrollRestoration = "manual";
}

// Guard external links vs internal
document.addEventListener("click", (e) => {
  const a = e.target.closest("a[href]");
  if (!a || a.origin !== location.origin || a.target === "_blank") return;
  if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
  e.preventDefault();
  navigate(a.pathname + a.search + a.hash);
});
```

```js
// State must be cloneable
history.pushState({ id: 1, when: new Date() }, "", "/item/1");
// history.pushState({ fn: () => {} }, "", "/x"); // DataCloneError
```

## ⚠️ Pitfalls [#️-pitfalls]

* `pushState` does not fire `popstate` — you must render yourself after push.
* State is structured-cloned — no functions, DOM nodes, or symbols.
* Relative URLs resolve against current URL — easy to create wrong paths.
* Back button through many `pushState` entries can feel sticky — use `replaceState` for filters.
* Cross-origin URLs throw — stay same-origin.

## 🔗 Related [#-related]

* [url.md](/docs/javascript/url) — URL / URLSearchParams
* [structured\_clone.md](/docs/javascript/structured-clone) — state cloning
* [DOM/navigation.md](/docs/javascript/dom/navigation) — location / navigation
* [DOM/events.md](/docs/javascript/dom/events) — popstate
* [encode.md](/docs/javascript/encode) — encoding query parts


# HTTP (Node) (/docs/javascript/http-node)



# HTTP (Node) [#http-node]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node’s `node:http` / `node:https` build servers and clients. For most apps prefer frameworks (Express, Fastify) or `fetch` (Node 18+). This sheet covers the core APIs.

## 🔧 Core concepts [#-core-concepts]

| API                          | Role                             |
| ---------------------------- | -------------------------------- |
| `http.createServer(handler)` | HTTP server                      |
| `req` / `res`                | IncomingMessage / ServerResponse |
| `http.request` / `get`       | Outgoing client                  |
| `https`                      | TLS variants                     |
| `fetch(url)`                 | Modern client (undici)           |

## 💡 Examples [#-examples]

**Tiny server:**

```js
import http from 'node:http';

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ ok: true, url: req.url }));
});

server.listen(9000, () => console.log('http://127.0.0.1:9000'));
```

**fetch client (Node 18+):**

```js
const res = await fetch('https://httpbin.org/get');
const data = await res.json();
console.log(data.url);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Always handle `error` on sockets; unhandled errors crash the process.
* Remember to `res.end()` or the request hangs.
* Prefer `fetch` / undici over hand-rolled `http.request` for clients.
* Binding `0.0.0.0` exposes the service on all interfaces.

## 🔗 Related [#-related]

* [fetch](/docs/javascript/fetch)
* [stream](/docs/javascript/stream)
* [process](/docs/javascript/process)
* [url\_node](/docs/javascript/url-node)
* [async](/docs/javascript/async)


# Import / Export (/docs/javascript/import-export)



# Import / Export [#import--export]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

ES modules (`import` / `export`) are the standard module system. Static imports are hoisted and analyzed at load time; dynamic `import()` returns a Promise. Use `.js` extensions in native ESM paths as required by the runtime.

## 🔧 Core concepts [#-core-concepts]

* **Named exports**: `export const x = 1`, `export function f() \{\}`, `export \{ a, b as c \}`.
* **Default export**: one per module — `export default expr`.
* **Import named**: `import \{ a, b as c \} from "./mod.js"`.
* **Import default**: `import Name from "./mod.js"`.
* **Namespace**: `import * as mod from "./mod.js"`.
* **Side-effect**: `import "./polyfill.js"`.
* **Dynamic**: `const mod = await import("./mod.js")`.
* **Re-export**: `export \{ x \} from "./x.js"`, `export * from "./x.js"`.

```js
// math.js
export const PI = Math.PI;
export function area(r) {
  return PI * r * r;
}
export default function sum(...ns) {
  return ns.reduce((a, b) => a + b, 0);
}
```

## 💡 Examples [#-examples]

```js
// consumer.js
import sum, { PI, area } from "./math.js";
import * as math from "./math.js";

console.log(area(2), sum(1, 2), math.PI);

// Rename
import { area as circleArea } from "./math.js";

// Dynamic / conditional
async function loadLocale(lang) {
  const mod = await import(`./locales/${lang}.js`);
  return mod.default;
}

// Import attributes (JSON modules — where supported)
import data from "./config.json" with { type: "json" };

// Re-export barrel
// index.js
export { area, PI } from "./math.js";
export { default as sum } from "./math.js";

// Top-level await in modules
const config = await fetch("/config.json").then((r) => r.json());
export { config };
```

```js
// Live bindings — exports are live
// counter.js
export let count = 0;
export function inc() {
  count += 1;
}

// main.js
import { count, inc } from "./counter.js";
inc();
console.log(count); // 1
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing CommonJS `require` and ESM needs interop — prefer one system per package.
* Default + named: `import foo, \{ bar \}` — default is not in `\{ bar \}` unless also exported named.
* Circular imports can yield temporal dead zone / partial bindings — redesign cycles.
* Bundlers may tree-shake only static `import`; dynamic paths limit analysis.
* In browsers, modules need `type="module"` and usually CORS for file URLs.

## 🔗 Related [#-related]

* [objects.md](/docs/javascript/objects) — module namespaces as objects
* [async.md](/docs/javascript/async) — top-level await
* [promise.md](/docs/javascript/promise) — dynamic import()
* [json.md](/docs/javascript/json) — JSON module data
* [api.md](/docs/javascript/api) — runtime module loaders


# JavaScript (/docs/javascript)



# JavaScript [#javascript]

Language, async, modules, DOM.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Dom](./dom)
* [Examples](./examples)


# Intl (/docs/javascript/intl)



# Intl [#intl]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `Intl` namespace provides locale-aware formatting and comparison: dates, numbers, lists, relative time, plurals, and collation. Prefer `Intl` over hand-rolled locale strings for i18n correctness and accessibility.

## 🔧 Core concepts [#-core-concepts]

| Constructor               | Use                    |
| ------------------------- | ---------------------- |
| `Intl.DateTimeFormat`     | dates/times            |
| `Intl.NumberFormat`       | numbers/currency/units |
| `Intl.RelativeTimeFormat` | “3 days ago”           |
| `Intl.ListFormat`         | “A, B, and C”          |
| `Intl.PluralRules`        | plural categories      |
| `Intl.Collator`           | sort / compare strings |
| `Intl.DisplayNames`       | language/region names  |
| `Intl.Segmenter`          | grapheme/word segments |

* **Locales**: BCP 47 tags — `"en"`, `"en-US"`, `"de-DE"`, `navigator.language`.
* **Options**: style, currency, timeZone, numberingSystem, etc.
* **`supportedLocalesOf`**: feature detection for locale lists.

```js
new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
}).format(1234.5); // "$1,234.50"
```

## 💡 Examples [#-examples]

```js
const locale = navigator.language || "en";

// Dates
new Intl.DateTimeFormat(locale, {
  dateStyle: "medium",
  timeStyle: "short",
}).format(new Date());

// Time zone
new Intl.DateTimeFormat("en-GB", {
  timeZone: "UTC",
  timeStyle: "long",
}).format(new Date());

// Relative
new Intl.RelativeTimeFormat(locale, { numeric: "auto" }).format(-1, "day");
// "yesterday" (en)

// Lists
new Intl.ListFormat(locale, { style: "long", type: "conjunction" }).format([
  "red",
  "green",
  "blue",
]);

// Sort
const collator = new Intl.Collator(locale, { sensitivity: "base" });
["ä", "a", "z"].sort(collator.compare);

// Plurals
const pr = new Intl.PluralRules("ru");
pr.select(3); // "few" etc.

// Display names
new Intl.DisplayNames("en", { type: "language" }).of("fr"); // "French"
```

```js
// Compact notation
new Intl.NumberFormat("en", {
  notation: "compact",
  compactDisplay: "short",
}).format(1_200_000); // "1.2M"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Locale data availability varies by engine — test critical locales.
* Don’t concatenate translated fragments — format whole messages (use ICU MessageFormat libs for complex cases).
* `Date#toLocaleString` is convenient but less reusable than a shared `DateTimeFormat` instance.
* Currency requires ISO codes (`USD`), not symbols alone.
* Sorting without `Collator` breaks non-English languages.

## 🔗 Related [#-related]

* [date.md](/docs/javascript/date) — Date object
* [number.md](/docs/javascript/number) — numeric values
* [strings.md](/docs/javascript/strings) — string compare
* [template\_literals.md](/docs/javascript/template-literals) — building messages
* [performance.md](/docs/javascript/performance) — reuse formatters


# Iteration (/docs/javascript/iteration)



# Iteration [#iteration]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

JavaScript offers several iteration styles: index `for`, `for...of`, `for...in`, `while`, array methods, and iterators/generators. Choose based on whether you need indices, early exit, async, or transformation pipelines.

## 🔧 Core concepts [#-core-concepts]

* **Indexed `for`**: full control of index and step.
* **`for...of`**: values from iterables.
* **`for...in`**: enumerable keys (objects) — rarely for arrays.
* **Array methods**: `forEach`, `map`, `filter`, `reduce` — functional pipelines; `forEach` cannot `break`.
* **`while` / `do...while`**: condition-driven loops.
* **Async**: `for await...of`, or `Promise.all` over mapped async work.

```js
for (let i = 0; i < arr.length; i++) {
  /* index + value: arr[i] */
}
```

## 💡 Examples [#-examples]

```js
const arr = ["a", "b", "c"];

// Indices + values
for (const [i, v] of arr.entries()) {
  console.log(i, v);
}

// Object keys / values / entries
const obj = { x: 1, y: 2 };
for (const key of Object.keys(obj)) console.log(key);
for (const val of Object.values(obj)) console.log(val);
for (const [k, v] of Object.entries(obj)) console.log(k, v);

// Pipeline
const sum = arr
  .map((s) => s.toUpperCase())
  .filter((s) => s !== "B")
  .reduce((acc, s) => acc + s.length, 0);

// forEach (no break)
arr.forEach((v, i) => console.log(i, v));

// Early exit → for...of
for (const v of arr) {
  if (v === "b") break;
}

// Nested with labeled break
outer: for (const row of matrix) {
  for (const cell of row) {
    if (cell < 0) break outer;
  }
}
```

```js
// Async sequential
for (const url of urls) {
  await fetch(url);
}

// Async parallel
await Promise.all(urls.map((u) => fetch(u)));

// Generator-driven
function* walk(node) {
  yield node;
  for (const child of node.children ?? []) yield* walk(child);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `forEach` ignores `async` callbacks’ promises and cannot break.
* `for...in` on arrays includes enumerable extras and yields string keys.
* Mutating length while iterating with index `for` needs care.
* Prefer `Object.keys` / `entries` over `for...in` for own properties.

## 🔗 Related [#-related]

* [for\_of.md](/docs/javascript/for-of) — for...of details
* [while.md](/docs/javascript/while) — while loops
* [iterator.md](/docs/javascript/iterator) — iterators & generators
* [arrays.md](/docs/javascript/arrays) — map/filter/reduce
* [objects.md](/docs/javascript/objects) — key enumeration
* [async.md](/docs/javascript/async) — async iteration
* [map.md](/docs/javascript/map) — Map iteration order


# Iterators & Generators (/docs/javascript/iterator)



# Iterators & Generators [#iterators--generators]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

The **iterable protocol** (`obj[Symbol.iterator]`) supplies an iterator with `next()` → `\{ value, done \}`. **Generators** (`function*`) produce iterators lazily and support `yield` / `yield*`. Async generators use `async function*` and `for await...of`.

## 🔧 Core concepts [#-core-concepts]

* **Iterable**: has `[Symbol.iterator]()` returning an iterator.
* **Iterator**: `\{ next() \}`; optional `return()` / `throw()`.
* **Generator**: `function*` pauses at `yield`; calling it returns a generator object.
* **`yield*`**: delegate to another iterable/generator.
* **Async**: `async function*`, `yield` awaited values, consume with `for await`.

```js
const iterable = {
  *[Symbol.iterator]() {
    yield 1;
    yield 2;
  },
};
[...iterable]; // [1, 2]
```

## 💡 Examples [#-examples]

```js
function* range(start, end, step = 1) {
  for (let i = start; i < end; i += step) yield i;
}
console.log([...range(0, 5)]); // [0,1,2,3,4]

function* idGen() {
  let id = 1;
  while (true) yield id++;
}
const ids = idGen();
ids.next().value; // 1

// yield*
function* flatten(arr) {
  for (const x of arr) {
    if (Array.isArray(x)) yield* flatten(x);
    else yield x;
  }
}
[...flatten([1, [2, [3], 4]])]; // [1,2,3,4]

// Manual iterator
const it = range(0, 2);
console.log(it.next()); // { value: 0, done: false }
console.log(it.next());
console.log(it.next()); // { value: undefined, done: true }

// Async generator
async function* poll(url, signal) {
  while (!signal.aborted) {
    const data = await fetch(url, { signal }).then((r) => r.json());
    yield data;
    await new Promise((r) => setTimeout(r, 1000));
  }
}
```

```js
// Infinite take helper
function take(n, iterable) {
  return {
    *[Symbol.iterator]() {
      let i = 0;
      for (const v of iterable) {
        if (i++ >= n) return;
        yield v;
      }
    },
  };
}
[...take(3, idGen())]; // [1,2,3]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Generators are lazy — side effects run only as you pull values.
* After `done: true`, further `next()` stay done (unless still open with return values).
* `break` in `for...of` calls iterator `return()` — use `try/finally` in generators for cleanup.
* Do not mix sync `for...of` with async generators — use `for await...of`.
* Spreading infinite generators never finishes.

## 🔗 Related [#-related]

* [for\_of.md](/docs/javascript/for-of) — consuming iterables
* [iteration.md](/docs/javascript/iteration) — loop overview
* [arrays.md](/docs/javascript/arrays) — Array.from / spread
* [async.md](/docs/javascript/async) — async iteration
* [map.md](/docs/javascript/map) — built-in iterables
* [set.md](/docs/javascript/set) — built-in iterables


# JSON (/docs/javascript/json)



# JSON [#json]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

JSON is a text data format. `JSON.parse` and `JSON.stringify` convert between strings and plain data (objects, arrays, numbers, strings, booleans, `null`). Functions, `undefined`, Symbols, and many class instances need custom handling.

## 🔧 Core concepts [#-core-concepts]

* **`JSON.parse(text, reviver?)`**: string → value; throws `SyntaxError` on bad input.
* **`JSON.stringify(value, replacer?, space?)`**: value → string; omits `undefined` in objects.
* **Reviver / replacer**: transform keys during parse/stringify.
* **`toJSON()`**: objects can customize serialization.
* **Safe parse**: wrap in try/catch; validate shape after parse.

```js
const obj = JSON.parse('{"a":1}');
const text = JSON.stringify(obj, null, 2);
```

## 💡 Examples [#-examples]

```js
// Pretty print
JSON.stringify({ user: "Ada", ok: true }, null, 2);

// Replacer allowlist
JSON.stringify(user, ["id", "name"]);

// Reviver for dates
const parsed = JSON.parse(payload, (key, value) => {
  if (key.endsWith("At") && typeof value === "string") {
    const d = new Date(value);
    if (!Number.isNaN(d.getTime())) return d;
  }
  return value;
});

// toJSON
const money = {
  amount: 10,
  currency: "USD",
  toJSON() {
    return `${this.amount} ${this.currency}`;
  },
};
JSON.stringify({ price: money }); // {"price":"10 USD"}

// Map ↔ JSON
function mapToJson(map) {
  return JSON.stringify([...map.entries()]);
}
function jsonToMap(text) {
  return new Map(JSON.parse(text));
}

// Deep clone via JSON (limitations!)
const clone = JSON.parse(JSON.stringify(data));
```

```js
function safeParse(text, fallback = null) {
  try {
    return JSON.parse(text);
  } catch {
    return fallback;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `JSON.stringify` drops `undefined`, functions, and Symbols in objects; turns them to `null` in arrays for `undefined`/functions.
* `NaN` / `Infinity` become `null`.
* `Date` becomes ISO string; `Map`/`Set` become `\{\}` unless converted.
* Circular structures throw `TypeError`.
* JSON clone loses prototypes, methods, and `undefined` keys.

## 🔗 Related [#-related]

* [objects.md](/docs/javascript/objects) — plain objects
* [arrays.md](/docs/javascript/arrays) — JSON arrays
* [fetch.md](/docs/javascript/fetch) — JSON HTTP bodies
* [date.md](/docs/javascript/date) — Date ↔ ISO
* [map.md](/docs/javascript/map) — serializing Maps
* [error.md](/docs/javascript/error) — SyntaxError on parse
* [strings.md](/docs/javascript/strings) — text handling


# Map (/docs/javascript/map)



# Map [#map]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`Map` is a keyed collection that preserves insertion order and accepts any value as a key (including objects). Prefer `Map` over plain objects when keys are unknown, non-strings, or you need reliable size / iteration.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new Map()`, `new Map([[k, v], ...])`.
* **Mutate**: `set`, `get`, `has`, `delete`, `clear`.
* **Size**: `map.size` (not a method).
* **Iterate**: `keys()`, `values()`, `entries()`, `forEach`, `for...of`.
* **Key equality**: SameValueZero (`NaN` equals `NaN`; `+0` / `-0` equal).

```js
const m = new Map();
m.set("a", 1).set("b", 2);
m.get("a"); // 1
m.size; // 2
```

## 💡 Examples [#-examples]

```js
// Object keys by reference
const user = { id: 1 };
const scores = new Map();
scores.set(user, 100);
scores.get(user); // 100

// Build from object
const fromObj = new Map(Object.entries({ x: 1, y: 2 }));

// To object (string keys only)
const obj = Object.fromEntries(fromObj);

// Frequency map
function frequencies(list) {
  const freq = new Map();
  for (const item of list) {
    freq.set(item, (freq.get(item) ?? 0) + 1);
  }
  return freq;
}

// Default get
function getOr(map, key, factory) {
  if (!map.has(key)) map.set(key, factory());
  return map.get(key);
}

// Iterate
for (const [k, v] of scores) console.log(k, v);

// Group into Map
function groupBy(list, keyFn) {
  const map = new Map();
  for (const item of list) {
    const key = keyFn(item);
    getOr(map, key, () => []).push(item);
  }
  return map;
}
```

```js
// WeakMap — keys must be objects; not iterable; GC-friendly
const privateState = new WeakMap();
function attach(el) {
  privateState.set(el, { clicks: 0 });
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Object keys are by **reference**, not deep equality.
* `JSON.stringify(map)` → `"\{\}"` — convert with `Object.fromEntries` or entries array.
* `map["a"] = 1` does not use Map storage — always use `.set` / `.get`.
* `WeakMap` is not iterable and cannot use primitive keys.
* Converting to object fails for non-string/symbol keys.

## 🔗 Related [#-related]

* [set.md](/docs/javascript/set) — Set collections
* [objects.md](/docs/javascript/objects) — plain object maps
* [iteration.md](/docs/javascript/iteration) — iterating Maps
* [for\_of.md](/docs/javascript/for-of) — for...of entries
* [json.md](/docs/javascript/json) — serialization
* [arrays.md](/docs/javascript/arrays) — Object.groupBy


# Math (/docs/javascript/math)



# Math [#math]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`Math` is a built-in object of numeric constants and functions. It works on IEEE-754 numbers (not `BigInt`). Prefer `Math` helpers over hand-rolled formulas for clamping, rounding, and trig.

## 🔧 Core concepts [#-core-concepts]

* **Constants**: `Math.PI`, `Math.E`, `Math.LN2`, `Math.SQRT2`, …
* **Rounding**: `floor`, `ceil`, `round`, `trunc`, `fround`.
* **Min/max**: `Math.min(...)`, `Math.max(...)` — watch empty call → `Infinity` / `-Infinity`.
* **Random**: `Math.random()` ∈ `[0, 1)`.
* **Powers**: `sqrt`, `cbrt`, `pow`, `**` operator, `hypot`, `abs`, `sign`.
* **Trig**: `sin`, `cos`, `tan`, `atan2` (radians).

```js
Math.clamp?.(0, 5, 10); // if available; else DIY
const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
```

## 💡 Examples [#-examples]

```js
const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
clamp(120, 0, 100); // 100

Math.trunc(3.9); // 3
Math.floor(-3.1); // -4
Math.trunc(-3.1); // -3

// Inclusive integer random
function randomInt(min, max) {
  return Math.floor(Math.random() * (max - min + 1)) + min;
}

// Sum with hypot for distance
const dist = Math.hypot(dx, dy);

// Percentage
const pct = Math.round((done / total) * 100);

// Avoid float noise for currency — use integers (cents) or Decimal libs
const cents = Math.round(19.99 * 100); // 1999

// Spread min/max on arrays
const nums = [3, 1, 4];
Math.max(...nums); // 4
// Large arrays: use loop or reduce to avoid stack limits
nums.reduce((a, b) => Math.max(a, b), -Infinity);
```

```js
// Angle helpers
const toRad = (deg) => (deg * Math.PI) / 180;
const toDeg = (rad) => (rad * 180) / Math.PI;
Math.sin(toRad(90)); // ~1

// imul / clz32 for bit ops
Math.imul(0xffffffff, 2);

// Sign & absolute
Math.sign(-0); // -0
Math.abs(-4.2); // 4.2
Math.log2(8); // 3
```

## ⚠️ Pitfalls [#️-pitfalls]

* `Math.max()` with no args is `-Infinity`; `Math.min()` is `Infinity`.
* `Math.round` uses “round half away from zero” toward +∞ for `.5` on positives.
* Floating point: `0.1 + 0.2 !== 0.3` — compare with epsilon.
* `Math.random` is not cryptographically secure — use `crypto.getRandomValues`.
* Spreading huge arrays into `Math.max` can throw RangeError.

## 🔗 Related [#-related]

* [number.md](/docs/javascript/number) — Number methods & parsing
* [date.md](/docs/javascript/date) — time arithmetic
* [api.md](/docs/javascript/api) — crypto random
* [arrays.md](/docs/javascript/arrays) — reduce aggregates
* [boolean.md](/docs/javascript/boolean) — comparisons


# Modules (CommonJS) (/docs/javascript/modules-commonjs)



# Modules (CommonJS) [#modules-commonjs]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

CommonJS (CJS) is Node’s classic module system: `require`, `module.exports`, and synchronous loading. ES modules (`import`/`export`) are the web standard and Node’s modern default — know CJS for legacy packages, interop, and tooling. Prefer ESM for new browser and Node code.

## 🔧 Core concepts [#-core-concepts]

* **Export**: `module.exports = value` or `exports.foo = ...` (alias of `module.exports` initially).
* **Import**: `const x = require("./file")` — cached after first load.
* **Resolution**: core modules, `node_modules`, relative paths; optional extensions.
* **`__filename` / `__dirname`**: file path helpers (not in ESM — use `import.meta.url`).
* **Circular deps**: partially filled `exports` during cycle.
* **Interop**: ESM can sometimes `import` CJS; CJS loads ESM via dynamic `import()`.

```js
// math.cjs
function add(a, b) {
  return a + b;
}
module.exports = { add };
```

## 💡 Examples [#-examples]

```js
// Export patterns
module.exports = function main() {};
module.exports = { read, write };
exports.version = "1.0.0"; // OK if not reassigned module.exports

// BAD: breaks exports alias
exports = { a: 1 }; // does not change module.exports

// Import
const { add } = require("./math");
const path = require("node:path");

// Conditional / dynamic path
const lang = require(`./locales/${name}.js`); // still sync; path must be resolvable

// Cache bust (rare)
delete require.cache[require.resolve("./config")];

// ESM consuming CJS (typical bundler/Node)
import pkg from "./legacy.cjs";
import * as ns from "./legacy.cjs";

// CJS consuming ESM
async function load() {
  const esm = await import("./modern.mjs");
  return esm.default;
}

// __dirname in ESM
import { fileURLToPath } from "node:url";
import { dirname } from "node:path";
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Reassigning `exports = ...` does not export — assign `module.exports`.
* `require` is sync and blocks — avoid for huge optional deps at startup when dynamic `import` fits.
* Dual packages (CJS+ESM) can cause “duplicate instance” bugs — follow package `exports` map.
* Browser has no native `require` — use ESM or a bundler.
* Live bindings differ: CJS copies values on require; ESM exports are live.

## 🔗 Related [#-related]

* [import\_export.md](/docs/javascript/import-export) — ES modules
* [oop.md](/docs/javascript/oop) — organizing code
* [json.md](/docs/javascript/json) — require JSON in Node
* [error.md](/docs/javascript/error) — MODULE\_NOT\_FOUND


# new Operator (/docs/javascript/new)



# new Operator [#new-operator]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`new` constructs an instance from a constructor function or class. It creates an object, sets its prototype, binds `this`, and returns the object (unless the constructor returns another object).

## 🔧 Core concepts [#-core-concepts]

* **Steps**: create `\{\}` → set `[[Prototype]]` → call constructor with `this` → return object (or explicit object return).
* **Classes**: `new Person()` required; calling without `new` throws.
* **`new.target`**: meta-property detecting construct calls.
* **`new.target` / subclassing**: works with `extends` and `super`.
* **Built-ins**: `new Map()`, `new Date()`, `new Error()` — some built-ins differ if called as functions.

```js
class Point {
  constructor(x, y) {
    this.x = x;
    this.y = y;
  }
}
const p = new Point(1, 2);
```

## 💡 Examples [#-examples]

```js
// Classic constructor
function User(name) {
  if (new.target === undefined) {
    return new User(name); // allow factory-style call
  }
  this.name = name;
}
User.prototype.hello = function () {
  return `Hi, ${this.name}`;
};

const u = new User("Ada");
u instanceof User; // true
Object.getPrototypeOf(u) === User.prototype; // true

// Class fields & private
class Counter {
  #n = 0;
  get value() {
    return this.#n;
  }
  inc() {
    this.#n += 1;
  }
}
const c = new Counter();

// Return override
function Weird() {
  this.a = 1;
  return { b: 2 }; // instance discarded
}
new Weird(); // { b: 2 }

// Reflect.construct
const d = Reflect.construct(Date, [2026, 0, 1]);
```

```js
// Array exotic
const a = new Array(3); // length 3 sparse
const b = Array.of(3); // [3]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `new` on old constructors sets properties on the global/`undefined` (strict) — prefer `class`.
* Returning a primitive from a constructor is ignored; returning an object replaces `this`.
* `arrow functions` cannot be constructors — no `new`.
* `Symbol` / `BigInt` are not constructible with `new`.
* `instanceof` can be spoofed; use brands or `new.target` checks for security-sensitive code.

## 🔗 Related [#-related]

* [oop.md](/docs/javascript/oop) — classes & inheritance
* [objects.md](/docs/javascript/objects) — prototypes
* [properties.md](/docs/javascript/properties) — defining instance props
* [error.md](/docs/javascript/error) — `new Error`
* [map.md](/docs/javascript/map) — `new Map`
* [date.md](/docs/javascript/date) — `new Date`


# OS module (/docs/javascript/node-os)



# OS module [#os-module]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js `node:os` reports host operating system details: home/temp directories, platform, CPU info, memory, and network interfaces. Useful for tools, diagnostics, and default paths — not a substitute for feature detection in app logic.

```js
import os from "node:os";
```

## 🔧 Core concepts [#-core-concepts]

* **`homedir()`**: current user’s home directory.
* **`tmpdir()`**: default directory for temporary files.
* **`platform()`**: `'darwin' | 'linux' | 'win32' | …` (Node’s naming).
* **`type()` / `release()` / `arch()`**: OS name, version string, CPU arch (`x64`, `arm64`).
* **`cpus()`**: array of CPU core descriptors (`model`, `speed`, `times`).
* **`totalmem()` / `freemem()`**: RAM in bytes.
* **`hostname()` / `networkInterfaces()`**: machine name and NICs.
* **`EOL`**: end-of-line sequence (`\n` or `\r\n`).

## 💡 Examples [#-examples]

```js
import os from "node:os";
import path from "node:path";

const configDir = path.join(os.homedir(), ".myapp");
const scratch = path.join(os.tmpdir(), "myapp-cache");

console.log(os.platform(), os.arch(), os.release());
console.log("cores:", os.cpus().length);
console.log("free MB:", Math.round(os.freemem() / 1024 / 1024));

const cpus = os.cpus();
console.log(cpus[0]?.model);

// Cross-platform line join
const lines = ["a", "b", "c"].join(os.EOL);

const ifaces = os.networkInterfaces();
for (const [name, addrs] of Object.entries(ifaces)) {
  for (const a of addrs ?? []) {
    if (a.family === "IPv4" && !a.internal) {
      console.log(name, a.address);
    }
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `platform()` returns `'win32'` even on 64-bit Windows.
* `cpus().length` is logical cores (HT), not necessarily physical packages.
* `tmpdir()` / `homedir()` can throw or be unexpected in restricted containers.
* `networkInterfaces()` shape varies; filter `internal` and family carefully (`IPv4` vs `4` in older Node).
* Do not hardcode separators — combine with `path` and `os.EOL`.

## 🔗 Related [#-related]

* [Path](/docs/javascript/path) — join home/tmp with filenames
* [process](/docs/javascript/process) — env, cwd, platform via process
* [fs](/docs/javascript/fs) — create dirs under homedir/tmpdir
* [child\_process](/docs/javascript/child-process) — OS-specific binaries


# null and undefined (/docs/javascript/null-undefined)



# null and undefined [#null-and-undefined]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

JavaScript has two empty-ish values: `undefined` (missing / not set) and `null` (intentional empty). Beginners should treat them as related but not identical, and prefer strict equality.

## 🔧 Core concepts [#-core-concepts]

| Value       | Usual meaning                               | How you get it                |
| ----------- | ------------------------------------------- | ----------------------------- |
| `undefined` | Not assigned / missing property / no return | Default state                 |
| `null`      | Deliberate “no object”                      | You (or an API) set it        |
| `==`        | Loose equality                              | `null == undefined` is `true` |
| `===`       | Strict equality                             | Prefer this                   |

Optional chaining (`?.`) and nullish coalescing (`??`) help handle both safely.

## 💡 Examples [#-examples]

**undefined by default:**

```js
let x;
console.log(x);            // undefined
console.log(typeof x);     // undefined

function f() {}
console.log(f());          // undefined
```

**null as intentional empty:**

```js
let user = null;
if (user === null) {
  console.log("logged out");
}
user = { name: "Ada" };
console.log(user.name);
```

**Loose vs strict:**

```js
console.log(null == undefined);  // true
console.log(null === undefined); // false
console.log(null === null);      // true
```

**Nullish coalescing and optional chaining:**

```js
const input = null;
const label = input ?? "default";
console.log(label); // default

const settings = undefined;
console.log(settings?.theme ?? "light"); // light
```

## ⚠️ Pitfalls [#️-pitfalls]

* Prefer `===` so you do not conflate `null` and `undefined` accidentally.
* `??` only falls through for `null`/`undefined`; `||` also treats `0`, `""`, `false` as missing.
* `typeof null` is `"object"` — do not use typeof to detect null.
* Reading missing nested props without `?.` throws: `obj.a.b`.

## 🔗 Related [#-related]

* [typeof\_basics.md](/docs/javascript/typeof-basics)
* [variables\_let\_const.md](/docs/javascript/variables-let-const)
* [nullish\_coalescing.md](/docs/javascript/nullish-coalescing)
* [equality.md](/docs/javascript/equality)


# Nullish Coalescing (/docs/javascript/nullish-coalescing)



# Nullish Coalescing [#nullish-coalescing]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The nullish coalescing operator (`??`) returns the right-hand side only when the left is `null` or `undefined`. Unlike `||`, it preserves intentional falsy values like `0`, `""`, and `false`. Pair with `?.` for safe defaults.

## 🔧 Core concepts [#-core-concepts]

* **`a ?? b`**: if `a` is nullish → `b`, else `a`.
* **`??=`**: assign only if current value is nullish.
* **Precedence**: cannot mix `??` with `&&` / `||` without parentheses.
* **vs `||`**: `||` treats all falsy as missing; `??` only nullish.
* **vs ternary**: `a != null ? a : b` is roughly equivalent (note `!=` coerces).

```js
const port = config.port ?? 3000;
const name = input.name ?? "Anonymous";
```

## 💡 Examples [#-examples]

```js
0 || 42; // 42  (often wrong for counts)
0 ?? 42; // 0

"" || "default"; // "default"
"" ?? "default"; // ""

null ?? "x"; // "x"
undefined ?? "x"; // "x"

// Nested options
const timeout = opts?.timeout ?? 5000;

// Assignment
let theme;
theme ??= "light";
theme ??= "dark"; // stays "light"

// Function defaults (params already handle undefined)
function connect(host, port = 443) {
  // port default only for undefined
}
connect("a", undefined); // 443
connect("a", null); // null — use ?? if null should default
function connect2(host, port) {
  port = port ?? 443;
}

// Prefer ?? for map lookups
const label = dict.get(key) ?? "missing";
```

```js
// Parentheses required
// const x = a || b ?? c; // SyntaxError
const x = (a || b) ?? c;
const y = a || (b ?? c);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing `??` with `||`/`&&` without parens is a syntax error.
* `document.all ?? x` is a weird legacy exception in some engines — ignore in modern code.
* Defaults in destructuring use `=` which also only triggers on `undefined`, not `null` — combine carefully.
* `??` does not deep-merge objects — only picks one side.

## 🔗 Related [#-related]

* [optional\_chaining.md](/docs/javascript/optional-chaining) — `?.` + `??`
* [equality.md](/docs/javascript/equality) — null vs undefined
* [destructuring.md](/docs/javascript/destructuring) — default values
* [ternary.md](/docs/javascript/ternary) — explicit conditionals
* [boolean.md](/docs/javascript/boolean) — truthiness


# Number (/docs/javascript/number)



# Number [#number]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`number` is IEEE-754 double precision. Integers are safe up to `Number.MAX_SAFE_INTEGER` (`2^53 - 1`). Use `BigInt` for larger integers. Prefer `Number` static methods over global `parseInt` / `isNaN` when possible.

## 🔧 Core concepts [#-core-concepts]

* **Literals**: `42`, `3.14`, `0xff`, `0b1010`, `1e3`, separators `1_000_000`.
* **Constants**: `MAX_VALUE`, `MIN_VALUE`, `EPSILON`, `NaN`, `POSITIVE_INFINITY`.
* **Check**: `Number.isFinite`, `Number.isInteger`, `Number.isSafeInteger`, `Number.isNaN`.
* **Parse**: `Number(text)`, `Number.parseInt(text, radix)`, `Number.parseFloat`.
* **Format**: `toFixed`, `toPrecision`, `toString(radix)`, `toLocaleString`, `Intl.NumberFormat`.

```js
Number.isNaN(Number("x")); // true
Number.parseInt("10px", 10); // 10
```

## 💡 Examples [#-examples]

```js
const n = 1_000_000.5;
n.toFixed(2); // "1000000.50"

// Safe integer check
function addSafe(a, b) {
  const s = a + b;
  if (!Number.isSafeInteger(s)) throw new RangeError("unsafe");
  return s;
}

// Epsilon compare
function nearlyEqual(a, b, eps = Number.EPSILON) {
  return Math.abs(a - b) < eps;
}
nearlyEqual(0.1 + 0.2, 0.3);

// Parse with radix
Number.parseInt("08", 10); // 8
Number.parseInt("ff", 16); // 255

// Locale currency
new Intl.NumberFormat("en-US", {
  style: "currency",
  currency: "USD",
}).format(19.9);

// BigInt interop
const big = 10n;
Number(big); // 10 — may lose precision for huge BigInts
BigInt(42); // 42n

// Unary plus
+"42"; // 42
+""; // 0
+null; // 0
+undefined; // NaN
```

```js
// Clamp percent
const pct = Math.min(100, Math.max(0, value));
```

## ⚠️ Pitfalls [#️-pitfalls]

* Global `isNaN` coerces: `isNaN("foo") === true`; use `Number.isNaN`.
* `parseInt` without radix can surprise on leading zeros in old engines — always pass radix.
* `==` coerces strings/numbers; use `===` after explicit parse.
* Floating point drift — don’t use binary floats for money.
* `typeof NaN === "number"`.

## 🔗 Related [#-related]

* [math.md](/docs/javascript/math) — Math helpers
* [boolean.md](/docs/javascript/boolean) — falsy `0` / `NaN`
* [strings.md](/docs/javascript/strings) — parsing from text
* [json.md](/docs/javascript/json) — number serialization
* [date.md](/docs/javascript/date) — timestamps


# Objects (/docs/javascript/objects)



# Objects [#objects]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Objects are key/value maps with a prototype chain. Prefer plain objects for records with known string keys; use `Map` for dynamic or non-string keys. Modern syntax covers shorthand, spread, optional chaining, and nullish assignment.

## 🔧 Core concepts [#-core-concepts]

**Create / copy / merge**

| API                              | Notes                                |
| -------------------------------- | ------------------------------------ |
| `\{\}`, `\{ ...a, ...b \}`       | Literal; shallow merge (later wins)  |
| `Object.create(proto, props?)`   | Set prototype; optional descriptors  |
| `Object.assign(target, ...srcs)` | Shallow copy own enumerable → target |
| `Object.fromEntries(iterable)`   | `[[k,v],…]` → object                 |
| `structuredClone(obj)`           | Deep clone (structured-cloneable)    |

**Keys / values / entries / own checks**

| API                               | Notes                                               |
| --------------------------------- | --------------------------------------------------- |
| `Object.keys(o)`                  | Own enumerable string keys                          |
| `Object.values(o)`                | Own enumerable string-key values                    |
| `Object.entries(o)`               | `[key, value]` pairs                                |
| `Object.hasOwn(o, key)`           | Own property (ES2022); prefer over `hasOwnProperty` |
| `Object.getOwnPropertyNames(o)`   | Own string keys incl. non-enumerable                |
| `Object.getOwnPropertySymbols(o)` | Own symbol keys                                     |
| `Reflect.ownKeys(o)`              | Names + symbols                                     |

**Prototype / integrity**

| API                                             | Notes                               |
| ----------------------------------------------- | ----------------------------------- |
| `Object.getPrototypeOf` / `setPrototypeOf`      | Read/set `[[Prototype]]`            |
| `Object.is(a, b)`                               | SameValue (`NaN`≡`NaN`, `+0`≠`-0`)  |
| `Object.freeze(o)`                              | No add/remove/reconfigure; shallow  |
| `Object.seal(o)`                                | No add/remove; existing writable ok |
| `Object.preventExtensions(o)`                   | No new props                        |
| `Object.isFrozen` / `isSealed` / `isExtensible` | Integrity queries                   |
| `Object.groupBy(items, fn)`                     | Group iterable → object of arrays   |

**Property descriptors**

| Field / API                             | Notes                                     |
| --------------------------------------- | ----------------------------------------- |
| `value`, `writable`                     | Data property                             |
| `get`, `set`                            | Accessor property (no `value`/`writable`) |
| `enumerable`                            | Shown in `for…in` / `keys` / spread       |
| `configurable`                          | Can delete / reconfigure                  |
| `Object.getOwnPropertyDescriptor(o, k)` | One descriptor                            |
| `Object.getOwnPropertyDescriptors(o)`   | All own descriptors                       |
| `Object.defineProperty(o, k, desc)`     | Define/reconfigure one                    |
| `Object.defineProperties(o, descs)`     | Define many                               |

Access: `obj.key`, `obj["key"]`, `obj?.key`. Nullish: `??`, `??=`.

```js
const user = { id: 1, name: "Ada" };
const { name, ...rest } = user;
```

## 💡 Examples [#-examples]

```js
// Shorthand & methods
const x = 1;
const o = {
  x,
  greet() {
    return "hi";
  },
  get label() {
    return String(this.x);
  },
};

// Merge (shallow)
const merged = { ...defaults, ...overrides };

// Optional chaining / nullish
const city = user?.address?.city ?? "unknown";
user.role ??= "guest";

// fromEntries / entries round-trip
const mapish = Object.fromEntries(
  Object.entries(user).map(([k, v]) => [k.toUpperCase(), v]),
);

// Own property checks
Object.hasOwn(user, "name"); // ES2022
Object.prototype.hasOwnProperty.call(user, "name"); // legacy-safe

// Freeze / seal
const cfg = Object.freeze({ mode: "prod" });

// structuredClone deep copy
const copy = structuredClone({ nested: { a: 1 }, when: new Date() });

// Prototype-free dict
const dict = Object.create(null);
dict.admin = true;
```

```js
// GroupBy (ES2024)
Object.groupBy(items, (i) => i.type);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Spread/assign are **shallow** — nested objects stay shared.
* `__proto__` key in JSON can pollute prototypes — use `Object.create(null)` or `Map`.
* `for...in` walks the prototype chain — prefer `Object.keys` / `hasOwn`.
* Comparing objects with `===` is by reference, not deep equality.
* `JSON.stringify` omits `undefined` values and functions.

## 🔗 Related [#-related]

* [properties.md](/docs/javascript/properties) — descriptors & getters
* [oop.md](/docs/javascript/oop) — classes / prototypes
* [map.md](/docs/javascript/map) — Map vs object
* [json.md](/docs/javascript/json) — serialization
* [iteration.md](/docs/javascript/iteration) — enumerating keys
* [new.md](/docs/javascript/new) — constructing instances


# OOP (Classes & Prototypes) (/docs/javascript/oop)



# OOP (Classes & Prototypes) [#oop-classes--prototypes]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

JavaScript OOP is prototype-based. `class` syntax is sugar over constructor functions and prototypes, adding inheritance via `extends`, `super`, public/private fields, and static members.

## 🔧 Core concepts [#-core-concepts]

* **Class**: `constructor`, instance methods, getters/setters, fields.
* **Private**: `#field`, `#method` — truly private per class.
* **Static**: `static` props/methods on the constructor.
* **Inheritance**: `extends`, `super()` before using `this` in subclass constructors.
* **Prototype**: `obj.__proto__` / `Object.getPrototypeOf`; methods live on `.prototype`.
* **`instanceof`**: walks the prototype chain.

```js
class Animal {
  constructor(name) {
    this.name = name;
  }
  speak() {
    return `${this.name} makes a noise`;
  }
}
```

## 💡 Examples [#-examples]

```js
class Dog extends Animal {
  #tricks = [];

  constructor(name, breed) {
    super(name);
    this.breed = breed;
  }

  speak() {
    return `${super.speak()} — woof`;
  }

  addTrick(t) {
    this.#tricks.push(t);
  }

  get tricks() {
    return [...this.#tricks];
  }

  static fromJSON(json) {
    const data = JSON.parse(json);
    return new Dog(data.name, data.breed);
  }
}

const d = new Dog("Rex", "lab");
d instanceof Dog; // true
d instanceof Animal; // true

// Mix-in pattern
const Timestamped = (Base) =>
  class extends Base {
    createdAt = new Date();
  };
class Job extends Timestamped(Object) {}

// Prototype check
Object.getPrototypeOf(d) === Dog.prototype;
```

```js
// Composition over deep hierarchies
class Engine {
  start() {
    return "vroom";
  }
}
class Car {
  constructor() {
    this.engine = new Engine();
  }
  start() {
    return this.engine.start();
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Subclass constructors must call `super()` before accessing `this`.
* Arrow methods as class fields are not on the prototype (per-instance; can’t be easily mocked via proto).
* Private fields are not accessible in subclasses or outside the declaring class.
* `this` in callbacks needs binding or arrows — class methods are not auto-bound.
* Overusing inheritance creates brittle hierarchies — prefer composition.

## 🔗 Related [#-related]

* [new.md](/docs/javascript/new) — construction
* [objects.md](/docs/javascript/objects) — prototypes & literals
* [properties.md](/docs/javascript/properties) — descriptors
* [map.md](/docs/javascript/map) — WeakMap privacy pattern
* [error.md](/docs/javascript/error) — custom Error subclasses
* [import\_export.md](/docs/javascript/import-export) — exporting classes


# Optional Chaining (/docs/javascript/optional-chaining)



# Optional Chaining [#optional-chaining]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Optional chaining (`?.`) short-circuits property/call/element access when the base is `null` or `undefined`, producing `undefined` instead of throwing. Ideal for sparse APIs, optional config, and DOM lookups that may miss.

## 🔧 Core concepts [#-core-concepts]

* **Property**: `obj?.prop`, `obj?.["key"]`.
* **Call**: `fn?.(arg)` — skips call if `fn` is nullish.
* **Element**: `arr?.[0]`.
* **Chain**: `a?.b?.c?.()` — stops at first nullish link.
* **Not a deep existence check for middle truthy holes** — only nullish bases.
* **Assign**: cannot use `?.` on the left-hand side of assignment.

```js
const name = user?.profile?.name;
const first = items?.[0];
api?.log?.("hi");
```

## 💡 Examples [#-examples]

```js
const user = { profile: { name: "Ada" } };
user?.profile?.name; // "Ada"
user?.address?.city; // undefined
null?.x; // undefined

// Methods
const maybe = Math.random() > 0.5 ? console : null;
maybe?.log("ok");

// DOM
document.querySelector("#app")?.classList.add("ready");

// Combined with nullish coalescing
const label = config?.title ?? "Untitled";

// Dynamic key
const key = "email";
user?.contacts?.[key];

// delete with optional (modern)
delete user?.temp; // no-op if user nullish

// Array callback safety
users.map((u) => u.roles?.includes("admin"));
```

```js
// Guard long chains
function getCity(order) {
  return order?.shipping?.address?.city ?? "N/A";
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `?.` only guards `null`/`undefined` — other falsy values (`0`, `""`, `false`) still proceed.
* `obj?.prop` when `obj` exists but `prop` is null returns `null`, not `undefined`.
* Overuse hides bugs — prefer validating required data at boundaries.
* `a?.b.c` still throws if `a.b` is nullish and you access `.c` without `?.`.
* Optional call `fn?.()` does not invent a default function — result is `undefined`.

## 🔗 Related [#-related]

* [nullish\_coalescing.md](/docs/javascript/nullish-coalescing) — `??` defaults
* [destructuring.md](/docs/javascript/destructuring) — defaults on unpack
* [error.md](/docs/javascript/error) — TypeError without `?.`
* [objects.md](/docs/javascript/objects) — property access
* [DOM/selectors.md](/docs/javascript/dom/selectors) — nullable query results


# Path (/docs/javascript/path)



# Path [#path]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js `node:path` builds and inspects filesystem paths. Prefer `path.join` / `path.resolve` over string concatenation so separators and `..` segments stay correct across platforms.

```js
import path from "node:path";
```

## 🔧 Core concepts [#-core-concepts]

* **`join(...parts)`**: concatenates segments; normalizes `.` / `..`; does not resolve against cwd.
* **`resolve(...parts)`**: produces an absolute path from right to left; uses `process.cwd()` when needed.
* **`dirname` / `basename` / `extname`**: parent dir, final segment, and extension (including the dot).
* **`parse` / `format`**: object with `root`, `dir`, `base`, `name`, `ext`.
* **`sep`**: `\` on Windows, `/` on POSIX.
* **`path.posix` / `path.win32`**: force POSIX or Windows rules regardless of host OS (useful for URLs or cross-platform config).

## 💡 Examples [#-examples]

```js
import path from "node:path";
import { fileURLToPath } from "node:url";

path.join("logs", "app", "out.txt");
// 'logs/app/out.txt' (POSIX) or 'logs\\app\\out.txt' (win32)

path.resolve("data", "../config.json");
// absolute path ending in config.json

path.dirname("/var/app/index.js"); // '/var/app'
path.basename("/var/app/index.js"); // 'index.js'
path.basename("/var/app/index.js", ".js"); // 'index'
path.extname("photo.tar.gz"); // '.gz'

const p = path.parse("/home/ada/report.pdf");
// { root: '/', dir: '/home/ada', base: 'report.pdf',
//   ext: '.pdf', name: 'report' }

path.format({ dir: "/tmp", base: "a.txt" }); // '/tmp/a.txt'

// ESM __dirname equivalent
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Always forward slashes (e.g. virtual paths)
path.posix.join("a", "b", "c"); // 'a/b/c'
```

## ⚠️ Pitfalls [#️-pitfalls]

* `join` does not make a path absolute; use `resolve` when you need that.
* `extname` returns only the last extension (`.gz` for `a.tar.gz`).
* Mixing `path.win32` and `path.posix` incorrectly breaks joins; pick one style for a given string format.
* Trailing separators are normalized away by `join` / `resolve` (except root).
* Do not use `path` for URL paths — use `URL` / `url` helpers instead.

## 🔗 Related [#-related]

* [Node URL helpers](/docs/javascript/url-node) — `pathToFileURL` / `fileURLToPath`
* [URL](/docs/javascript/url) — WHATWG `URL` in JS
* [CommonJS modules](/docs/javascript/modules-commonjs) — `__dirname` / `__filename`
* [ESM import/export](/docs/javascript/import-export) — `import.meta.url`
* [fs](/docs/javascript/fs) — reading/writing with resolved paths


# Performance (/docs/javascript/performance)



# Performance [#performance]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Measure and improve runtime with the Performance APIs: high-res timestamps, marks/measures, resource timing, and observers. Optimize what you measure — long tasks, layout thrash, oversized payloads, and unnecessary main-thread work.

## 🔧 Core concepts [#-core-concepts]

* **`performance.now()`**: monotonic ms since `timeOrigin` (not wall clock).
* **Marks/measures**: `mark`, `measure`, `getEntriesByName`, `clearMarks`.
* **`PerformanceObserver`**: stream entries (`resource`, `paint`, `largest-contentful-paint`, `layout-shift`, `longtask`, `event`, …).
* **Navigation / Resource Timing**: network waterfall data.
* **User Timing**: custom marks for app logic.
* **DevTools**: Performance panel + Lighthouse complement APIs.

```js
performance.mark("start");
work();
performance.mark("end");
performance.measure("work", "start", "end");
```

## 💡 Examples [#-examples]

```js
// Simple timing
const t0 = performance.now();
await doWork();
console.log(performance.now() - t0, "ms");

// Observer for long tasks
const po = new PerformanceObserver((list) => {
  for (const e of list.getEntries()) {
    console.log("longtask", e.duration, e);
  }
});
po.observe({ type: "longtask", buffered: true });

// LCP
new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const last = entries[entries.length - 1];
  console.log("LCP", last.startTime, last.element);
}).observe({ type: "largest-contentful-paint", buffered: true });

// Resource sizes
performance.getEntriesByType("resource").forEach((r) => {
  console.log(r.name, r.transferSize, r.duration);
});

// Avoid layout thrashing
// BAD: read/write interleave forcing reflow
// GOOD: batch reads then writes
const heights = els.map((el) => el.offsetHeight);
els.forEach((el, i) => {
  el.style.height = heights[i] * 2 + "px";
});

// Idle work
requestIdleCallback((deadline) => {
  while (deadline.timeRemaining() > 0 && tasks.length) tasks.pop()();
});
```

```js
// Measure fetch
performance.mark("fetch-start");
const res = await fetch("/api");
performance.mark("fetch-end");
performance.measure("fetch", "fetch-start", "fetch-end");
```

## ⚠️ Pitfalls [#️-pitfalls]

* `Date.now()` can jump with clock changes — use `performance.now()` for durations.
* Observing everything allocates — filter entry types and disconnect when done.
* Micro-benchmarks lie (JIT warmup, DCE) — measure realistic paths.
* Optimizing without profiles wastes time — record a trace first.
* Some entries require HTTPS / specific headers (e.g. server timing, cross-origin detail).

## 🔗 Related [#-related]

* [timers.md](/docs/javascript/timers) — rAF / scheduling
* [event\_loop.md](/docs/javascript/event-loop) — long tasks
* [web\_workers.md](/docs/javascript/web-workers) — offload CPU
* [fetch.md](/docs/javascript/fetch) — network cost
* [DOM/events.md](/docs/javascript/dom/events) — event timing


# process (/docs/javascript/process)



# process [#process]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js exposes the current process as the global `process` object: environment, CLI args, working directory, exit codes, and stdio streams. Available without an import in most contexts; you can also `import process from "node:process"`.

## 🔧 Core concepts [#-core-concepts]

* **`process.env`**: environment variables (strings or `undefined`).
* **`process.argv`**: `[nodePath, scriptPath, ...args]`.
* **`process.cwd()`**: current working directory (not the script’s folder).
* **`process.exit(code?)`**: end process; `0` success, non-zero failure.
* **`stdin` / `stdout` / `stderr`**: readable/writable streams for I/O.
* **Signals / events**: `process.on("SIGINT", ...)`, `beforeExit`, `uncaughtException` (use sparingly).

## 💡 Examples [#-examples]

```js
import process from "node:process";

// CLI: node app.js --port 9000
const args = process.argv.slice(2);
console.log(process.execPath); // node binary
console.log(process.cwd());

const port = process.env.PORT ?? "9000";

process.stdout.write("hello\n");
console.error("to stderr"); // often process.stderr

// Read stdin (piped input)
async function readStdin() {
  const chunks = [];
  for await (const chunk of process.stdin) chunks.push(chunk);
  return Buffer.concat(chunks).toString("utf8");
}

process.on("SIGINT", () => {
  console.log("shutting down…");
  process.exit(0);
});

if (!process.env.REQUIRED) {
  console.error("REQUIRED is missing");
  process.exit(1);
}
```

```js
// Change cwd (affects relative fs paths)
process.chdir("/tmp");
```

## ⚠️ Pitfalls [#️-pitfalls]

* `process.exit()` skips pending I/O and `finally` cleanup; prefer letting the loop drain or use `exitCode = 1`.
* `cwd()` is where you launched the process, not `__dirname` / `import.meta.url`.
* `argv` includes node and script paths — slice from index `2` for user args.
* Mutating `process.env` affects the current process only (not the parent shell).
* Unhandled promise rejections may terminate Node depending on version/flags.

## 🔗 Related [#-related]

* [dotenv](/docs/javascript/dotenv) — load `.env` into `process.env`
* [Path](/docs/javascript/path) — resolve paths relative to cwd
* [Stream](/docs/javascript/stream) — stdin/stdout as streams
* [child\_process](/docs/javascript/child-process) — spawn subprocesses
* [Buffer](/docs/javascript/buffer) — binary stdin chunks


# Promise (/docs/javascript/promise)



# Promise [#promise]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

A Promise represents a future settlement: pending → fulfilled or rejected. Chain with `then` / `catch` / `finally`, or use `async`/`await`. Combinators coordinate multiple promises.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new Promise((resolve, reject) => \{ ... \})`, `Promise.resolve`, `Promise.reject`.
* **Consume**: `then(onFulfilled, onRejected)`, `catch`, `finally`.
* **Combinators**: `all`, `allSettled`, `race`, `any`.
* **Thenables**: objects with a `then` method are assimilated.
* **States**: settled state is immutable; further `resolve`/`reject` ignored.

```js
const p = new Promise((resolve, reject) => {
  setTimeout(() => resolve(42), 100);
});
p.then((v) => console.log(v));
```

## 💡 Examples [#-examples]

```js
// Wrap callback API
function readFile(path) {
  return new Promise((resolve, reject) => {
    fs.readFile(path, (err, data) => (err ? reject(err) : resolve(data)));
  });
}

// Combinators
await Promise.all([fetchA(), fetchB()]); // fail-fast
await Promise.allSettled([fetchA(), fetchB()]); // wait all
await Promise.race([fetch(url), timeout(5000)]); // first settled
await Promise.any([mirror1(), mirror2()]); // first fulfilled

// Timeout helper
function timeout(ms) {
  return new Promise((_, reject) => {
    setTimeout(() => reject(new Error("timeout")), ms);
  });
}

// finally for cleanup
fetch(url)
  .then((r) => r.json())
  .finally(() => hideSpinner());

// Flattening
Promise.resolve(1)
  .then((n) => n + 1)
  .then((n) => Promise.resolve(n * 2))
  .then(console.log); // 4
```

```js
// Avoid classic constructor anti-pattern when you already have a promise
// bad: new Promise((resolve) => fetch(url).then(resolve))
// good: return fetch(url)

// Unhandled rejection — always catch
queueMicrotask(() => {
  Promise.reject(new Error("oops")).catch(console.error);
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* `Promise.all` rejects on the first failure — use `allSettled` for partial results.
* Forgetting `return` inside `then` breaks the chain.
* Creating promises that never settle leaks resources — pair with AbortSignal.
* `then(fn, fn)` vs `.catch`: errors in `onFulfilled` skip the second arg — prefer `.catch`.
* Mixing callbacks and promises without wrapping causes double-resolve bugs.

## 🔗 Related [#-related]

* [async.md](/docs/javascript/async) — async/await
* [fetch.md](/docs/javascript/fetch) — promise-based HTTP
* [error.md](/docs/javascript/error) — rejection causes
* [api.md](/docs/javascript/api) — microtasks / AbortSignal
* [iteration.md](/docs/javascript/iteration) — async iteration
* [import\_export.md](/docs/javascript/import-export) — dynamic import()


# Properties (/docs/javascript/properties)



# Properties [#properties]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Object properties have **descriptors** controlling writability, enumerability, configurability, and accessors. Understanding descriptors explains getters, `Object.defineProperty`, and class fields.

## 🔧 Core concepts [#-core-concepts]

* **Data descriptor**: `value`, `writable`, `enumerable`, `configurable`.
* **Accessor descriptor**: `get`, `set`, `enumerable`, `configurable`.
* **Define**: `Object.defineProperty`, `Object.defineProperties`.
* **Inspect**: `Object.getOwnPropertyDescriptor`, `Object.getOwnPropertyDescriptors`.
* **Flags**: non-writable / non-configurable lock down APIs.
* **Symbols**: can be keys; often non-enumerable by convention.

```js
Object.defineProperty(obj, "id", {
  value: 1,
  writable: false,
  enumerable: true,
  configurable: false,
});
```

## 💡 Examples [#-examples]

```js
const user = {};

Object.defineProperty(user, "name", {
  value: "Ada",
  writable: true,
  enumerable: true,
  configurable: true,
});

// Accessor
Object.defineProperty(user, "tag", {
  get() {
    return `@${this.name.toLowerCase()}`;
  },
  set(v) {
    this.name = String(v).replace(/^@/, "");
  },
  enumerable: true,
});

user.tag = "@Grace";
console.log(user.name); // Grace

// Multiple
Object.defineProperties(user, {
  role: { value: "admin", enumerable: true },
  createdAt: { value: Date.now(), writable: false },
});

// Class equivalent
class Rect {
  #w;
  constructor(w, h) {
    this.#w = w;
    this.height = h;
  }
  get width() {
    return this.#w;
  }
  get area() {
    return this.#w * this.height;
  }
}

// Copy descriptors (not just values)
const clone = Object.defineProperties(
  {},
  Object.getOwnPropertyDescriptors(user),
);
```

```js
// Prevent extensions
Object.preventExtensions(user);
Object.seal(user); // + non-configurable
Object.freeze(user); // + non-writable data props
```

## ⚠️ Pitfalls [#️-pitfalls]

* Assignment silently fails on non-writable props in non-strict mode; throws in strict.
* You cannot mix `value` and `get`/`set` in one descriptor.
* `configurable: false` prevents deleting or redefining later.
* Spread/`Object.assign` copy **enumerable values**, not getters as accessors.
* Class fields are writable/enumerable on the instance by default (not on prototype).

## 🔗 Related [#-related]

* [objects.md](/docs/javascript/objects) — object basics
* [oop.md](/docs/javascript/oop) — class getters/fields
* [new.md](/docs/javascript/new) — instance creation
* [map.md](/docs/javascript/map) — alternative key storage
* [json.md](/docs/javascript/json) — enumerable own props only


# Prototypes (/docs/javascript/prototypes)



# Prototypes [#prototypes]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

JavaScript inheritance is prototype-based. Every object has an internal `[[Prototype]]` link (exposed as `__proto__` / `Object.getPrototypeOf`). Property lookup walks the chain until found or `null`. Classes are syntax sugar over constructor functions and prototypes.

## 🔧 Core concepts [#-core-concepts]

* **Prototype chain**: `obj` → `Object.getPrototypeOf(obj)` → … → `null`.
* **Own vs inherited**: `hasOwnProperty` / `Object.hasOwn` vs chain lookup.
* **Constructor**: `Fn.prototype` is assigned as `[[Prototype]]` of `new Fn()` instances.
* **`Object.create(proto)`**: make an object with a chosen prototype.
* **Class**: `class C extends B` wires `C.prototype` → `B.prototype`.
* **`new.target`**: detects construct calls.

```js
const proto = { greet() { return "hi"; } };
const obj = Object.create(proto);
obj.greet(); // "hi"
```

## 💡 Examples [#-examples]

```js
function Animal(name) {
  this.name = name;
}
Animal.prototype.speak = function () {
  return `${this.name} makes a noise`;
};

function Dog(name) {
  Animal.call(this, name);
}
Dog.prototype = Object.create(Animal.prototype);
Dog.prototype.constructor = Dog;
Dog.prototype.speak = function () {
  return `${this.name} barks`;
};

const d = new Dog("Rex");
d.speak(); // "Rex barks"
d instanceof Dog; // true
d instanceof Animal; // true

// Modern equivalent
class Cat extends Animal {
  speak() {
    return `${this.name} meows`;
  }
}

// Inspect
Object.getPrototypeOf(d) === Dog.prototype;
Object.hasOwn(d, "name"); // true
Object.hasOwn(d, "speak"); // false

// Null-prototype map (no inherited keys)
const dict = Object.create(null);
dict.admin = true;
"toString" in dict; // false

// Static vs instance
class Mathy {
  static dual(n) {
    return n * 2;
  }
  half() {
    return this.value / 2;
  }
}
```

```js
// Shadowing
const a = Object.create({ x: 1 });
a.x = 2; // own property shadows prototype
delete a.x; // reveals prototype x again
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutating built-in prototypes (`Array.prototype`) breaks libraries — avoid in app code.
* `for...in` enumerates enumerable inherited keys — prefer `Object.keys` / `hasOwn`.
* Setting `__proto__` is legacy; use `Object.setPrototypeOf` sparingly (engine deopts).
* `instanceof` can fail across realms/iframes with different globals.

## 🔗 Related [#-related]

* [oop.md](/docs/javascript/oop) — class syntax
* [objects.md](/docs/javascript/objects) — property model
* [new.md](/docs/javascript/new) — construction
* [this\_keyword.md](/docs/javascript/this-keyword) — method receivers
* [proxy\_reflect.md](/docs/javascript/proxy-reflect) — intercepting lookup


# Proxy & Reflect (/docs/javascript/proxy-reflect)



# Proxy & Reflect [#proxy--reflect]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Proxy` wraps a target object and intercepts fundamental operations (get, set, apply, construct, …) via traps. `Reflect` mirrors those operations as functions and returns boolean success flags — use it inside traps to forward default behavior correctly.

## 🔧 Core concepts [#-core-concepts]

| Trap                                          | Intercepts                  |
| --------------------------------------------- | --------------------------- |
| `get` / `set`                                 | property read/write         |
| `has`                                         | `in` operator               |
| `deleteProperty`                              | `delete`                    |
| `ownKeys`                                     | `Object.keys` / spread keys |
| `getOwnPropertyDescriptor` / `defineProperty` | descriptors                 |
| `apply` / `construct`                         | function call / `new`       |
| `getPrototypeOf` / `setPrototypeOf`           | prototype                   |

* **Invariants**: traps must respect target non-configurable / non-writable constraints or throw.
* **Revocable**: `Proxy.revocable(target, handler)` → `\{ proxy, revoke \}`.

```js
const p = new Proxy(
  {},
  {
    get(t, prop, receiver) {
      return Reflect.get(t, prop, receiver);
    },
  },
);
```

## 💡 Examples [#-examples]

```js
// Default values
const defaults = { theme: "light" };
const config = new Proxy(defaults, {
  get(t, prop, r) {
    return prop in t ? Reflect.get(t, prop, r) : "«missing»";
  },
});

// Validation on set
const user = new Proxy(
  { age: 0 },
  {
    set(t, prop, value, r) {
      if (prop === "age" && (!Number.isInteger(value) || value < 0)) {
        throw new TypeError("invalid age");
      }
      return Reflect.set(t, prop, value, r);
    },
  },
);

// Negative array index
function wrapArray(arr) {
  return new Proxy(arr, {
    get(t, prop, r) {
      if (typeof prop === "string" && /^-?\d+$/.test(prop)) {
        let i = Number(prop);
        if (i < 0) i = t.length + i;
        return Reflect.get(t, String(i), r);
      }
      return Reflect.get(t, prop, r);
    },
  });
}
wrapArray([1, 2, 3])[-1]; // 3

// Revoke access
const { proxy, revoke } = Proxy.revocable({ secret: 1 }, {});
revoke();
// proxy.secret → TypeError

// Observable-ish
function observable(obj, onChange) {
  return new Proxy(obj, {
    set(t, p, v, r) {
      const ok = Reflect.set(t, p, v, r);
      if (ok) onChange(p, v);
      return ok;
    },
  });
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `Reflect` / wrong `receiver` breaks inheritance and accessors (`this` in getters).
* Violating invariants (e.g. reporting a non-configurable missing property) throws.
* Proxies are not deeply transparent — `===` identity differs from target; libraries may reject them.
* Performance cost vs plain objects — don’t proxy hot paths without need.
* `typeof proxy` follows the target (object/function).

## 🔗 Related [#-related]

* [objects.md](/docs/javascript/objects) — property model
* [prototypes.md](/docs/javascript/prototypes) — prototype ops
* [symbol.md](/docs/javascript/symbol) — well-known symbols
* [freeze\_seal.md](/docs/javascript/freeze-seal) — hardening without Proxy
* [oop.md](/docs/javascript/oop) — classes vs interception


# Regular Expressions (/docs/javascript/regex)



# Regular Expressions [#regular-expressions]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Regular expressions match and extract text patterns. Create with `/pattern/flags` or `new RegExp(string, flags)`. Use with `String` methods (`match`, `matchAll`, `replace`, `search`, `split`) and `RegExp` methods (`test`, `exec`). Prefer readable patterns; escape user input when building dynamic regexes.

## 🔧 Core concepts [#-core-concepts]

| Flag | Meaning                   |
| ---- | ------------------------- |
| `g`  | global — find all         |
| `i`  | ignore case               |
| `m`  | `^`/`$` per line          |
| `s`  | `.` matches newline       |
| `u`  | Unicode (code points)     |
| `y`  | sticky — from `lastIndex` |
| `d`  | indices for groups        |
| `v`  | Unicode sets (modern)     |

* **Groups**: `(...)` capturing, `(?:...)` non-capturing, `(?<name>...)` named.
* **Lookaround**: `(?=...)`, `(?!...)`, `(?&lt;=...)`, `(?&lt;!...)`.
* **Quantifiers**: `*`, `+`, `?`, `\{n,m\}` — add `?` for lazy.
* **Classes**: `\d` `\w` `\s`, `[a-z]`, `[^...]`.

```js
const re = /\b\w+@\w+\.\w+\b/gi;
re.test("a@b.co"); // true
```

## 💡 Examples [#-examples]

```js
// exec loop (mind lastIndex with /g)
const re = /(\d+)/g;
let m;
while ((m = re.exec("a12 b34"))) {
  console.log(m[1], m.index);
}

// matchAll (preferred)
for (const m of "a12 b34".matchAll(/(\d+)/g)) {
  console.log(m[1]);
}

// Named groups + replace
const date = "2026-07-10";
const { groups } = date.match(/(?<y>\d{4})-(?<m>\d{2})-(?<d>\d{2})/);
// groups.y === "2026"

"hello world".replace(/(\w+)\s+(\w+)/, "$2 $1"); // "world hello"
"price: 5".replace(/(?<n>\d+)/, "$$$<n>"); // careful with $

// Escape user input
function escapeRegExp(s) {
  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
new RegExp(`^${escapeRegExp(user)}.txt$`);

// Unicode
/\p{Emoji}/u.test("😀"); // true
```

```js
// Validation
const emailish = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
emailish.test("dev@example.com");
```

## ⚠️ Pitfalls [#️-pitfalls]

* `/g` regexes keep `lastIndex` — reuse can skip matches; reset or use `matchAll`.
* Dot `.` does not match newlines unless `s` flag.
* Catastrophic backtracking on crafted input — avoid nested ambiguous quantifiers on untrusted strings.
* `new RegExp("\\d")` needs double escaping vs literals.
* `replace` with a string treats `$&`, `$1`, etc. specially.

## 🔗 Related [#-related]

* [strings.md](/docs/javascript/strings) — string APIs
* [template\_literals.md](/docs/javascript/template-literals) — building patterns
* [encode.md](/docs/javascript/encode) — encoding vs matching
* [error.md](/docs/javascript/error) — SyntaxError on bad patterns


# Set (/docs/javascript/set)



# Set [#set]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`Set` stores unique values using SameValueZero equality. Insertion order is preserved. Use sets for membership tests, deduplication, and set-algebra helpers.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new Set()`, `new Set(iterable)`.
* **Mutate**: `add`, `delete`, `clear`, `has`.
* **Size**: `set.size`.
* **Iterate**: `keys()` / `values()` (same), `entries()` → `[v, v]`, `forEach`, `for...of`.
* **Equality**: `NaN` equals `NaN`; objects by reference.

```js
const s = new Set([1, 2, 2, 3]);
s.size; // 3
s.has(2); // true
```

## 💡 Examples [#-examples]

```js
// Deduplicate array
const unique = [...new Set(items)];

// Membership
const allowed = new Set(["read", "write", "admin"]);
if (allowed.has(role)) { /* ... */ }

// Union / intersection / difference (ES2025 methods where available)
function union(a, b) {
  return new Set([...a, ...b]);
}
function intersection(a, b) {
  return new Set([...a].filter((x) => b.has(x)));
}
function difference(a, b) {
  return new Set([...a].filter((x) => !b.has(x)));
}

// Native (modern engines)
// a.union(b); a.intersection(b); a.difference(b); a.symmetricDifference(b);

// Toggle membership
function toggle(set, value) {
  if (set.has(value)) set.delete(value);
  else set.add(value);
  return set;
}

// WeakSet — objects only, not iterable
const seen = new WeakSet();
function visit(node) {
  if (seen.has(node)) return;
  seen.add(node);
}
```

```js
for (const v of s) console.log(v);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Object uniqueness is by reference: `new Set([\{a:1\},\{a:1\}]).size === 2`.
* `JSON.stringify(set)` → `"\{\}"` — convert with `[...set]` first.
* `set[0]` does not work — use iteration or convert to array.
* `WeakSet` cannot hold primitives and is not enumerable.
* Mutating while iterating is allowed but can be confusing — prefer snapshots.

## 🔗 Related [#-related]

* [map.md](/docs/javascript/map) — Map collections
* [arrays.md](/docs/javascript/arrays) — dedupe patterns
* [iteration.md](/docs/javascript/iteration) — looping sets
* [for\_of.md](/docs/javascript/for-of) — for...of
* [objects.md](/docs/javascript/objects) — reference equality
* [json.md](/docs/javascript/json) — serialization limits


# Spread & Rest (/docs/javascript/spread-rest)



# Spread & Rest [#spread--rest]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`...` is rest when collecting values into an array/object, and spread when expanding an iterable or object into places that expect multiple elements/properties. Same syntax, opposite direction — context decides.

## 🔧 Core concepts [#-core-concepts]

* **Rest (collect)**: function params, array/object destructuring — must be last.
* **Spread (expand)**: call args, array literals, object literals (own enumerable props).
* **Arrays/iterables**: spread uses the iterator protocol.
* **Objects**: shallow copy / merge — later keys win.
* **Clone caveats**: spread is shallow; nested objects stay shared by reference.

```js
const nums = [1, 2, 3];
Math.max(...nums); // 3
const copy = [...nums];
const merged = { ...a, ...b };
```

## 💡 Examples [#-examples]

```js
// Rest parameters
function logAll(label, ...items) {
  console.log(label, items);
}
logAll("ids", 1, 2, 3); // items === [1, 2, 3]

// Spread into call
const args = [10, 20];
sum(...args);

// Concat / insert
const a = [1, 2];
const b = [0, ...a, 3]; // [0, 1, 2, 3]

// Copy Set / NodeList
const unique = [...new Set([1, 1, 2])];
const els = [...document.querySelectorAll("li")];

// Object merge (shallow)
const defaults = { theme: "light", lang: "en" };
const prefs = { theme: "dark" };
const config = { ...defaults, ...prefs }; // theme: "dark"

// Rest in destructuring
const [head, ...tail] = [1, 2, 3, 4];
const { id, ...meta } = { id: 1, name: "x", role: "admin" };

// Spread Map entries into object (string keys)
const m = new Map([["a", 1], ["b", 2]]);
const obj = Object.fromEntries(m);
```

```js
// Immutable update pattern
const state = { user: { name: "Ada" }, count: 0 };
const next = { ...state, count: state.count + 1 };
```

## ⚠️ Pitfalls [#️-pitfalls]

* Object spread does not copy inherited or non-enumerable properties; symbols need care.
* Spreading huge arrays into args can hit call-stack / argument limits — use loops.
* `...null` / `...undefined` in objects is a no-op; in arrays they throw.
* Rest in objects excludes the listed keys but does not deep-clone nested values.
* Spread order matters for overrides: put overrides last.

## 🔗 Related [#-related]

* [destructuring.md](/docs/javascript/destructuring) — rest patterns
* [arrays.md](/docs/javascript/arrays) — array copy/concat
* [objects.md](/docs/javascript/objects) — object assign/merge
* [functions.md](/docs/javascript/functions) — rest params
* [iterator.md](/docs/javascript/iterator) — iterable protocol


# Stream (/docs/javascript/stream)



# Stream [#stream]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js streams process data in chunks instead of loading everything into memory. Core types: **Readable**, **Writable**, **Duplex**, **Transform**. Prefer `pipeline` (or `stream/promises`) for error-safe piping.

```js
import { pipeline } from "node:stream/promises";
import { createReadStream, createWriteStream } from "node:fs";
```

## 🔧 Core concepts [#-core-concepts]

* **Readable**: producers (`fs.createReadStream`, HTTP request body). Modes: flowing vs paused.
* **Writable**: consumers (`fs.createWriteStream`, HTTP response). Backpressure via `write()` return value.
* **`pipe` / `pipeline`**: connect readable → writable (and transforms). `pipeline` destroys streams on error and forwards errors.
* **Transform**: duplex that modifies chunks (gzip, cipher, line splitters).
* **Object mode**: streams of objects instead of Buffers/strings (`objectMode: true`).
* **Events**: `data`, `end`, `error`, `finish`, `readable` (EventEmitter-based).

## 💡 Examples [#-examples]

```js
import { createReadStream, createWriteStream } from "node:fs";
import { pipeline } from "node:stream/promises";
import { createGzip } from "node:zlib";

await pipeline(
  createReadStream("big.txt"),
  createGzip(),
  createWriteStream("big.txt.gz"),
);

// Manual consume (async iterator)
import { createReadStream as rs } from "node:fs";
for await (const chunk of rs("log.txt", { encoding: "utf8" })) {
  process.stdout.write(chunk);
}
```

```js
import { Readable, Transform } from "node:stream";

const src = Readable.from(["a\n", "b\n", "c\n"]);
const upper = new Transform({
  transform(chunk, enc, cb) {
    cb(null, chunk.toString().toUpperCase());
  },
});

await pipeline(src, upper, process.stdout);
```

```js
// Backpressure sketch
function writeAll(writable, chunks) {
  let i = 0;
  function write() {
    for (; i < chunks.length; i++) {
      const ok = writable.write(chunks[i]);
      if (!ok) {
        writable.once("drain", write);
        return;
      }
    }
    writable.end();
  }
  write();
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Classic `.pipe()` does not clean up well on errors — use `pipeline`.
* Ignoring `error` events can crash the process.
* Mixing `data` handlers and async iteration can conflict — pick one consumption style.
* Forgetting `end()` on writables leaves pipelines hanging.
* Buffering entire stream into a string defeats the purpose for large files.

## 🔗 Related [#-related]

* [fs](/docs/javascript/fs) — file streams vs `readFile`
* [Events](/docs/javascript/events-node) — EventEmitter under streams
* [Buffer](/docs/javascript/buffer) — binary chunks
* [Async](/docs/javascript/async) — `for await` of readables
* [fetch](/docs/javascript/fetch) — web streams / response bodies
* [child\_process](/docs/javascript/child-process) — stdio streams


# Strict Mode (/docs/javascript/strict-mode)



# Strict Mode [#strict-mode]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Strict mode (`"use strict"`) opts into a cleaner, safer JavaScript subset: fewer silent failures, no accidental globals, and `this` is `undefined` in bare calls. ES modules and class bodies are strict by default.

## 🔧 Core concepts [#-core-concepts]

* **Enable**: `"use strict";` at top of script or function body.
* **Modules / classes**: always strict.
* **No accidental globals**: assigning undeclared vars throws.
* **`this`**: `undefined` in non-method calls (not global object).
* **Forbidden**: `with`, octal literals like `0123`, deleting plain names, duplicate params (legacy).
* **`arguments`**: no dynamic link to parameters; `arguments.callee` forbidden.

```js
"use strict";
function f() {
  return this; // undefined when called as f()
}
```

## 💡 Examples [#-examples]

```js
"use strict";

// ReferenceError — would create global in sloppy mode
// x = 1;

let x = 1;
// delete x; // SyntaxError in strict

function sum(a, a) {
  // SyntaxError: duplicate params in strict
}

function show() {
  console.log(this);
}
show(); // undefined (strict) vs window (sloppy browser)

// Silent failure becomes throw
const obj = Object.freeze({ a: 1 });
// obj.a = 2; // TypeError in strict

// Octal
// const n = 012; // SyntaxError — use 0o12

// eval/arguments as binding names illegal
// function eval() {} // SyntaxError
```

```js
// Function-level strict
function legacyCompat() {
  // sloppy if script is sloppy
}
function modern() {
  "use strict";
  // strict only inside modern
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Concatenating scripts can lose a leading `"use strict"` if not first statement.
* Libraries expecting sloppy `this === window` break under strict — bind explicitly.
* Strict is per-function/script — mixed modes in one bundle confuse debugging.
* Don’t rely on sloppy features; write as if everything is strict (modules already are).

## 🔗 Related [#-related]

* [this\_keyword.md](/docs/javascript/this-keyword) — undefined this
* [import\_export.md](/docs/javascript/import-export) — modules are strict
* [error.md](/docs/javascript/error) — thrown errors
* [freeze\_seal.md](/docs/javascript/freeze-seal) — TypeError on mutate
* [equality.md](/docs/javascript/equality) — cleaner semantics


# Strings (/docs/javascript/strings)



# Strings [#strings]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

Strings are immutable UTF-16 sequences. Prefer template literals, `includes`/`startsWith`, and `replaceAll` over older index loops. For full Unicode graphemes, be aware of code units vs code points.

## 🔧 Core concepts [#-core-concepts]

**Create / access**

| API                                    | Notes                               |
| -------------------------------------- | ----------------------------------- |
| `'...'`, `"..."`, `` `tmpl $\{x\}` ``  | Prefer templates for interpolation  |
| `String(x)`, `String.raw`…\`\`         | Coerce; raw skips escape processing |
| `str.length`                           | UTF-16 **code units**               |
| `str[i]`, `str.at(i)`, `str.charAt(i)` | `at` supports negatives             |
| `charCodeAt` / `codePointAt`           | Unit vs full code point             |

**Search / match**

| Method                    | Notes                                   |
| ------------------------- | --------------------------------------- |
| `includes(sub, from?)`    | Boolean substring                       |
| `indexOf` / `lastIndexOf` | Index or `-1`                           |
| `startsWith` / `endsWith` | Prefix / suffix (pos optional)          |
| `search(re)`              | First regex match index                 |
| `match(re)`               | Match array or `null`                   |
| `matchAll(re)`            | Iterator of all matches (`/g` required) |

**Slice / split / join**

| Method                   | Notes                          |
| ------------------------ | ------------------------------ |
| `slice(start?, end?)`    | Supports negatives; preferred  |
| `substring(a, b)`        | Swaps if `a > b`; no negatives |
| `substr(start, len)`     | Legacy — avoid                 |
| `split(sep\|re, limit?)` | → array; empty sep → chars     |
| `Array` `.join(sep)`     | Inverse of `split`             |

**Case / trim / pad / repeat**

| Method                             | Notes                 |
| ---------------------------------- | --------------------- |
| `toLowerCase` / `toUpperCase`      | Locale-insensitive    |
| `toLocaleLowerCase` / `…UpperCase` | Locale-aware          |
| `trim` / `trimStart` / `trimEnd`   | Whitespace (Unicode)  |
| `padStart(n, fill?)` / `padEnd`    | Pad to length `n`     |
| `repeat(n)`                        | Concatenate `n` times |

**Replace / normalize / unicode**

| Method                                  | Notes                                   |
| --------------------------------------- | --------------------------------------- |
| `replace(pat, rep\|fn)`                 | First match only if string/`/g` missing |
| `replaceAll(pat, rep\|fn)`              | All; string or global regex             |
| `normalize("NFC"\|"NFD"\|…)`            | Unicode normalization forms             |
| `localeCompare(other, locales?, opts?)` | Collation compare → −1/0/1              |
| `for...of str`                          | Iterates **code points**                |
| `[...str]` / `Array.from(str)`          | Code-point array                        |

```js
const name = "Ada";
`Hello, ${name}!`;
"file.js".endsWith(".js"); // true
```

## 💡 Examples [#-examples]

```js
const s = "  Hello, World  ";
s.trim().toLowerCase(); // "hello, world"
"a-b-c".split("-"); // ["a","b","c"]
"na".repeat(3); // "nanana"
"id".padStart(4, "0"); // "00id"
"foo bar foo".replaceAll("foo", "baz");

// Template multiline
const html = `
  <div class="card">
    ${title}
  </div>
`.trim();

// Code points iteration
for (const ch of "A🙂B") console.log(ch);

// matchAll
const re = /\d+/g;
for (const m of "a1 b23".matchAll(re)) {
  console.log(m[0], m.index);
}

// Slice vs substring
"abcdef".slice(1, -1); // "bcde"
"abcdef".substring(1, 4); // "bcd"

// Normalize Unicode
"é".normalize("NFC");
```

```js
// Safe HTML escape (minimal)
function escapeHtml(str) {
  return str
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;");
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Strings are immutable — methods return new strings.
* `replace` with string pattern replaces only the first match — use `replaceAll` or `/g`.
* Surrogate pairs: `"🙂".length === 2`; prefer `for...of` / `codePointAt`.
* `==` coerces; compare with `===`.
* Building HTML via concatenation risks XSS — escape or use DOM APIs / frameworks.

## 🔗 Related [#-related]

* [encode.md](/docs/javascript/encode) — URI encoding
* [boolean.md](/docs/javascript/boolean) — empty string falsy
* [arrays.md](/docs/javascript/arrays) — split/join
* [json.md](/docs/javascript/json) — string escaping
* [for\_of.md](/docs/javascript/for-of) — iterating characters
* [DOM/content\_methods.md](/docs/javascript/dom/content-methods) — text vs HTML


# Structured Clone (/docs/javascript/structured-clone)



# Structured Clone [#structured-clone]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The structured clone algorithm deep-copies certain JS values across realms — used by `structuredClone()`, `postMessage`, IndexedDB, and history state. It handles built-ins that `JSON` cannot (Dates, Maps, typed arrays) but rejects functions, DOM nodes, and symbols as keys in some cases.

## 🔧 Core concepts [#-core-concepts]

* **API**: `structuredClone(value, \{ transfer \})`.
* **Supported**: primitives, plain objects/arrays, `Date`, `RegExp`, `Map`, `Set`, `Blob`, `File`, `ArrayBuffer`, typed arrays, `Error` (mostly), cyclic refs.
* **Unsupported**: functions, DOM nodes, class instances’ methods / prototype identity, some platform objects.
* **Transfer**: move `ArrayBuffer` ownership (detached source) via `transfer` list.
* **vs JSON**: JSON drops `undefined`, converts Date to string, can’t cycle; clone keeps more types.

```js
const copy = structuredClone({ d: new Date(), m: new Map([[1, 2]]) });
copy.d instanceof Date; // true
```

## 💡 Examples [#-examples]

```js
// Deep clone with cycles
const a = { name: "a" };
a.self = a;
const b = structuredClone(a);
b.self === b; // true
b !== a; // true

// Map / Set
structuredClone(new Set([1, 2, 2]));

// Transfer buffer to worker-like flow
const buf = new ArrayBuffer(8);
const moved = structuredClone(buf, { transfer: [buf] });
// buf.byteLength === 0 (detached)

// postMessage uses same algorithm
worker.postMessage({ pixels }, [pixels.buffer]);

// History state
history.pushState(structuredClone(state), "", url);

// What fails
// structuredClone(() => {}); // DataCloneError
// structuredClone(document.body); // DataCloneError

// JSON fallback comparison
JSON.parse(JSON.stringify({ d: new Date() })).d; // string, not Date
```

```js
// Clone error
const err = structuredClone(new Error("boom"));
err.message; // "boom"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Class instances become plain objects (prototype lost) or throw — don’t expect methods.
* `transfer` detaches the original buffer — subsequent access throws.
* Older browsers need polyfills / fallbacks for `structuredClone`.
* `WeakMap` / functions / symbols as object keys are not cloneable.
* Not a security boundary by itself — still validate untrusted data.

## 🔗 Related [#-related]

* [json.md](/docs/javascript/json) — JSON clone limits
* [web\_workers.md](/docs/javascript/web-workers) — postMessage
* [typed\_arrays.md](/docs/javascript/typed-arrays) — transferable buffers
* [history\_api.md](/docs/javascript/history-api) — pushState data
* [freeze\_seal.md](/docs/javascript/freeze-seal) — immutability after clone


# switch / case (/docs/javascript/switch-case)



# switch / case [#switch--case]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`switch` selects a branch by strict equality (`===`) against a discriminant. Cases fall through until `break`, `return`, or `throw`. Prefer maps/objects or early returns when branches share little structure.

## 🔧 Core concepts [#-core-concepts]

* **Syntax**: `switch (expr) \{ case v: ... break; default: ... \}`.
* **Matching**: strict equality; no pattern matching built-in.
* **Fall-through**: intentional sharing of bodies; always comment intentional fall-through.
* **Scope**: wrap case bodies in `\{ \}` when using `let`/`const` to avoid TDZ clashes.
* **Alternatives**: lookup tables, `Map`, if/else chains, pattern libs.

```js
switch (status) {
  case 200:
    return "ok";
  case 404:
    return "missing";
  default:
    return "other";
}
```

## 💡 Examples [#-examples]

```js
function httpLabel(code) {
  switch (code) {
    case 200:
    case 201:
    case 204:
      return "success";
    case 301:
    case 302:
      return "redirect";
    case 400:
    case 401:
    case 403:
    case 404:
      return "client-error";
    case 500:
      return "server-error";
    default:
      return "unknown";
  }
}

// Block scope per case
switch (kind) {
  case "user": {
    const id = crypto.randomUUID();
    return { kind, id };
  }
  case "guest": {
    const id = "guest";
    return { kind, id };
  }
  default:
    throw new Error(`bad kind: ${kind}`);
}

// Dispatch table
const handlers = {
  ping: () => "pong",
  time: () => Date.now(),
};
const result = (handlers[cmd] ?? (() => "noop"))();

// switch (true) pattern (use sparingly)
switch (true) {
  case score >= 90:
    return "A";
  case score >= 80:
    return "B";
  default:
    return "C";
}
```

```js
// Exhaustiveness helper for unions (manual)
function assertNever(x) {
  throw new Error(`unexpected: ${x}`);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `break` causes accidental fall-through bugs.
* `case` values are compared with `===` — `"1"` does not match `1`.
* `let`/`const` in a case without braces collide with other cases.
* Large switches are harder to test — prefer strategy maps for open sets of commands.
* `default` is optional but recommended for unexpected values.

## 🔗 Related [#-related]

* [boolean.md](/docs/javascript/boolean) — conditions
* [objects.md](/docs/javascript/objects) — dispatch tables
* [map.md](/docs/javascript/map) — Map-based dispatch
* [error.md](/docs/javascript/error) — default throws
* [oop.md](/docs/javascript/oop) — polymorphic alternatives


# Symbol (/docs/javascript/symbol)



# Symbol [#symbol]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Symbol` is a primitive unique key type. Each `Symbol("desc")` is unique (except `Symbol.for`). Symbols enable non-colliding object properties, protocol hooks (`Symbol.iterator`), and meta behavior without string key clashes.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `Symbol(description?)` — always unique.
* **Global registry**: `Symbol.for(key)` / `Symbol.keyFor(sym)`.
* **As keys**: `obj[sym] = value` — skipped by most string enumerations.
* **Well-known**: `Symbol.iterator`, `Symbol.asyncIterator`, `Symbol.toStringTag`, `Symbol.hasInstance`, `Symbol.toPrimitive`, etc.
* **Description**: `sym.description` (informational only).
* **Not constructible**: `new Symbol()` throws.

```js
const id = Symbol("id");
const user = { [id]: 42, name: "Ada" };
user[id]; // 42
```

## 💡 Examples [#-examples]

```js
const SECRET = Symbol("secret");
const bag = {
  visible: true,
  [SECRET]: "hidden",
};
Object.keys(bag); // ["visible"]
Object.getOwnPropertySymbols(bag); // [Symbol(secret)]

// Global shared symbol
const a = Symbol.for("app.token");
const b = Symbol.for("app.token");
a === b; // true
Symbol.keyFor(a); // "app.token"

// Custom iterable
const range = {
  from: 1,
  to: 3,
  *[Symbol.iterator]() {
    for (let i = this.from; i <= this.to; i++) yield i;
  },
};
[...range]; // [1, 2, 3]

// toStringTag
class Queue {
  get [Symbol.toStringTag]() {
    return "Queue";
  }
}
Object.prototype.toString.call(new Queue()); // "[object Queue]"

// hasInstance
class Even {
  static [Symbol.hasInstance](x) {
    return Number(x) % 2 === 0;
  }
}
2 instanceof Even; // true
```

```js
// Unique enum-like constants
const Color = {
  Red: Symbol("red"),
  Blue: Symbol("blue"),
};
```

## ⚠️ Pitfalls [#️-pitfalls]

* `JSON.stringify` omits symbol keys — serialize explicitly if needed.
* Symbols are not truly private — `getOwnPropertySymbols` reveals them; use `#private` fields for real privacy.
* `Symbol.for` shares across the realm — choose unique registry keys.
* Spreading `\{...obj\}` copies enumerable string keys; symbol copy needs `getOwnPropertySymbols` + descriptors.

## 🔗 Related [#-related]

* [objects.md](/docs/javascript/objects) — property keys
* [iterator.md](/docs/javascript/iterator) — Symbol.iterator
* [oop.md](/docs/javascript/oop) — private fields
* [proxy\_reflect.md](/docs/javascript/proxy-reflect) — ownKeys traps
* [json.md](/docs/javascript/json) — serialization limits


# Template Literals Basics (/docs/javascript/template-basics)



# Template Literals Basics [#template-literals-basics]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Template literals are strings wrapped in backticks (`` ` ``). They support interpolation with `$\{...\}` and multi-line text without awkward `+` concatenation.

## 🔧 Core concepts [#-core-concepts]

| Feature          | Syntax                    | Purpose                    |
| ---------------- | ------------------------- | -------------------------- |
| Template         | `` `text` ``              | String with superpowers    |
| Interpolation    | `` `$\{expr\}` ``         | Embed any expression       |
| Multi-line       | Newlines inside backticks | Readable paragraphs        |
| Nested           | Templates inside `$\{\}`  | Advanced formatting        |
| Tagged templates | `tag\`...\`\`             | Advanced (libraries, i18n) |

Prefer templates over `+` when building messages from variables.

## 💡 Examples [#-examples]

**Interpolation:**

```js
const name = "Ada";
const score = 95;
console.log(`Hello, ${name}! Score: ${score}`);
```

**Expressions inside $\{}:**

```js
const a = 3;
const b = 4;
console.log(`${a} + ${b} = ${a + b}`);
console.log(`Upper: ${"hi".toUpperCase()}`);
```

**Multi-line:**

```js
const html = `
<section>
  <h1>Title</h1>
  <p>Hello</p>
</section>
`.trim();
console.log(html);
```

**Compared to concatenation:**

```js
const user = "Sam";
const oldWay = "Hi " + user + "!";
const newWay = `Hi ${user}!`;
console.log(oldWay === newWay); // true
```

## ⚠️ Pitfalls [#️-pitfalls]

* Use backticks `` ` ``, not quotes — `"Hello $\{name\}"` does **not** interpolate.
* Nested quotes are fine inside templates; escaping backticks needs \`\`\`.
* Huge templates with logic become hard to read — extract variables first.
* Accidental leading indentation in multi-line templates is part of the string.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/javascript/hello-world)
* [variables\_let\_const.md](/docs/javascript/variables-let-const)
* [typeof\_basics.md](/docs/javascript/typeof-basics)
* [strings](/docs/javascript/strings)


# Template Literals (/docs/javascript/template-literals)



# Template Literals [#template-literals]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Template literals use backticks `` ` `` for strings with interpolation `$\{expr\}`, multi-line text, and tagged templates. They replace most string concatenation and enable DSLs (e.g. sanitizers, CSS-in-JS) via tag functions.

## 🔧 Core concepts [#-core-concepts]

* **Interpolate**: `` `Hello $\{name\}` `` — any expression inside `$\{\}`.
* **Multi-line**: newlines are preserved as written.
* **Escape**: `\``, `$`, `\\\` as needed.
* **Tagged**: `tag\`...\``calls`tag(strings, ...values)\`.
* **Raw**: `String.raw\`C:\path\file\`\` — backslashes mostly literal.
* **Nested**: templates can nest inside `$\{\}`.

```js
const name = "Ada";
const msg = `Hello, ${name}!`;
const block = `line1
line2`;
```

## 💡 Examples [#-examples]

```js
const a = 3,
  b = 4;
`sum=${a + b}`; // "sum=7"

// Expressions
`User: ${user?.name ?? "guest"}`;
`Items: ${items.map((i) => i.id).join(", ")}`;

// HTML snippet (sanitize user input!)
const html = `<li class="item">${escapeHtml(text)}</li>`;

// Tagged template
function highlight(strings, ...values) {
  return strings.reduce(
    (out, str, i) => out + str + (values[i] != null ? `<b>${values[i]}</b>` : ""),
    "",
  );
}
highlight`Hello ${"world"}`; // "Hello <b>world</b>"

// String.raw
String.raw`\n`; // "\\n" (two chars: \ and n)

// Nested
const rows = people.map((p) => `<tr><td>${p.name}</td></tr>`).join("");
const table = `<table>${rows}</table>`;
```

```js
// Dynamic property in message
const key = "count";
`Total ${key}=${data[key]}`;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Interpolating untrusted HTML/SQL causes XSS/injection — escape or use safe APIs.
* `$\{obj\}` becomes `obj.toString()` — often `"[object Object]"`; format explicitly.
* Older engines / some tooling mishandle tagged templates — know your targets.
* Accidental nesting of quotes is fine with backticks, but `$\{` inside needs care.
* Large templates rebuilt every render can allocate heavily — cache static parts.

## 🔗 Related [#-related]

* [strings.md](/docs/javascript/strings) — string methods
* [f-string style](/docs/javascript/strings) — formatting
* [optional\_chaining.md](/docs/javascript/optional-chaining) — in interpolations
* [regex.md](/docs/javascript/regex) — patterns vs templates
* [encode.md](/docs/javascript/encode) — escaping


# Ternary Operator (/docs/javascript/ternary)



# Ternary Operator [#ternary-operator]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The conditional (ternary) operator `cond ? then : else` picks one of two expressions. It is an **expression** (produces a value), unlike `if` which is a statement. Use for simple choices; avoid nested ternaries that obscure intent.

## 🔧 Core concepts [#-core-concepts]

* **Form**: `condition ? valueIfTruthy : valueIfFalsy`.
* **Associativity**: right-associative — `a ? b : c ? d : e` ≡ `a ? b : (c ? d : e)`.
* **Precedence**: lower than most operators; higher than assignment and `??`/`||` in careful mixes — use parentheses.
* **Any expressions**: including function calls, objects, further ternaries.
* **Not a substitute** for multi-statement branches — use `if`.

```js
const label = isOn ? "On" : "Off";
const n = x > 0 ? x : 0;
```

## 💡 Examples [#-examples]

```js
// Assignment / return
function fee(amount, member) {
  return member ? amount * 0.9 : amount;
}

// JSX / render-style (conceptually)
const icon = loading ? "spinner" : error ? "warn" : "ok"; // nested — consider clarity

// Prefer flat for readability
const icon2 = loading ? "spinner" : error ? "warn" : "ok";

// With nullish
const title = item?.name ? item.name : "Untitled";
// often better:
const title2 = item?.name ?? "Untitled";

// Call choice
(mode === "edit" ? save : create)(payload);

// Class names
el.className = active ? "tab active" : "tab";

// Nested with parens for clarity
const access =
  user == null ? "guest" : user.isAdmin ? "admin" : "user";
```

```js
// Illegal: statements inside branches without expressions
// cond ? let x = 1 : let y = 2; // SyntaxError
// use if/else or IIFE / blocks in modern proposal contexts carefully
```

## ⚠️ Pitfalls [#️-pitfalls]

* Nested ternaries become unreadable quickly — prefer `if`, lookup maps, or early returns.
* Truthiness: `value ? value : fallback` treats `0`/`""` as missing — use `??`.
* Mixing with `??` / `||` without parentheses is confusing or a syntax error in some combos.
* Side effects in both branches still evaluate only one branch — good — but don’t hide important logic there.
* Overusing ternaries for control flow that needs blocks leads to awkward IIFEs.

## 🔗 Related [#-related]

* [conditionals.md](/docs/javascript/conditionals) — if/else
* [nullish\_coalescing.md](/docs/javascript/nullish-coalescing) — `??`
* [boolean.md](/docs/javascript/boolean) — truthiness
* [optional\_chaining.md](/docs/javascript/optional-chaining) — safe access
* [equality.md](/docs/javascript/equality) — comparisons in conditions


# this Keyword (/docs/javascript/this-keyword)



# this Keyword [#this-keyword]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`this` is determined by **how a function is called**, not where it is defined (except arrows, which inherit lexical `this`). Master call-site rules, binding methods, and class fields to avoid the most common JS bugs.

## 🔧 Core concepts [#-core-concepts]

| Call style                | `this`                       |
| ------------------------- | ---------------------------- |
| `obj.method()`            | `obj`                        |
| `fn()` (sloppy)           | global object                |
| `fn()` (strict / modules) | `undefined`                  |
| `new Fn()`                | new instance                 |
| `fn.call/apply/bind`      | explicit                     |
| Arrow function            | lexical outer `this`         |
| DOM handler (classic)     | element (unless arrow/bound) |

* **`bind`**: returns a new function with fixed `this` (and optional partial args).
* **`call` / `apply`**: invoke immediately with chosen `this`.
* **Class methods**: need binding or arrows if passed as callbacks.

```js
const obj = {
  n: 1,
  get() {
    return this.n;
  },
};
obj.get(); // 1
```

## 💡 Examples [#-examples]

```js
"use strict";

function show() {
  return this?.id;
}
const user = { id: 42, show };
user.show(); // 42
show(); // undefined (strict)

// Explicit binding
show.call({ id: 7 }); // 7
const bound = show.bind({ id: 9 });
bound(); // 9

// Losing this
const detached = user.show;
detached(); // undefined

// Arrow preserves outer this
class Counter {
  count = 0;
  inc = () => {
    this.count += 1;
  };
  bump() {
    this.count += 1;
  }
}
const c = new Counter();
setTimeout(c.inc, 0); // OK
setTimeout(c.bump, 0); // broken unless bound

// call vs apply
function greet(a, b) {
  return `${this.name}: ${a} ${b}`;
}
greet.call({ name: "Ada" }, "hi", "there");
greet.apply({ name: "Ada" }, ["hi", "there"]);

// DOM
button.addEventListener("click", function () {
  console.log(this); // button
});
button.addEventListener("click", () => {
  console.log(this); // outer lexical this
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Extracting methods (`const f = obj.m`) drops the receiver.
* Arrows on prototypes are usually wrong — they close over the wrong `this` at definition time for classes use public fields carefully.
* `bind` creates a new function each time — don’t bind inside render loops without caching.
* In modules, top-level `this` is `undefined`, not `window`.

## 🔗 Related [#-related]

* [functions.md](/docs/javascript/functions) — arrow vs function
* [closures.md](/docs/javascript/closures) — lexical capture
* [oop.md](/docs/javascript/oop) — classes & methods
* [strict\_mode.md](/docs/javascript/strict-mode) — undefined `this`
* [DOM/events.md](/docs/javascript/dom/events) — handler `this`


# Timers (/docs/javascript/timers)



# Timers [#timers]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Timers schedule callbacks on the event loop: `setTimeout`, `setInterval`, and animation-oriented `requestAnimationFrame`. Always keep the handle to clear them. Prefer `rAF` for visual work and avoid overlapping intervals for async jobs.

## 🔧 Core concepts [#-core-concepts]

* **`setTimeout(fn, ms, ...args)`**: once after delay; returns timer id.
* **`setInterval(fn, ms, ...args)`**: repeats; drifts under load.
* **`clearTimeout` / `clearInterval`**: cancel by id.
* **`requestAnimationFrame(cb)`**: before next paint; `cb(timestamp)`.
* **`cancelAnimationFrame(id)`**: cancel rAF.
* **Delay clamping**: nested timeouts / background tabs may be throttled (≥4ms, often 1s+ inactive).
* **`scheduler` / `scheduler.postTask`** (where available): prioritized tasks.

```js
const id = setTimeout(() => console.log("later"), 1000);
clearTimeout(id);
```

## 💡 Examples [#-examples]

```js
// Pass arguments
setTimeout(console.log, 0, "hello", 42);

// Recursive timeout (better control than interval)
function poll(ms) {
  let stopped = false;
  async function tick() {
    if (stopped) return;
    await fetchStatus();
    setTimeout(tick, ms);
  }
  tick();
  return () => {
    stopped = true;
  };
}

// Interval with cleanup
const id = setInterval(() => {
  console.log(Date.now());
}, 1000);
// later: clearInterval(id);

// Animation loop
let raf;
function loop(t) {
  draw(t);
  raf = requestAnimationFrame(loop);
}
raf = requestAnimationFrame(loop);
// cancelAnimationFrame(raf);

// Debounce with timeout
function debounce(fn, ms) {
  let t;
  return (...args) => {
    clearTimeout(t);
    t = setTimeout(() => fn(...args), ms);
  };
}

// Promise wrapper
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
await sleep(200);
```

```js
// Abortable sleep
function sleep(ms, signal) {
  return new Promise((resolve, reject) => {
    const t = setTimeout(resolve, ms);
    signal?.addEventListener("abort", () => {
      clearTimeout(t);
      reject(signal.reason);
    });
  });
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `setInterval` does not wait for async work — callbacks can overlap; use recursive `setTimeout`.
* Timer ids are numbers in browsers, objects in Node — don’t assume type.
* Forgetting to clear timers on unmount leaks and causes “setState on unmounted” bugs.
* `rAF` pauses in background tabs; don’t use it for critical non-visual deadlines.
* String eval form `setTimeout("code", 0)` is obsolete and unsafe.

## 🔗 Related [#-related]

* [event\_loop.md](/docs/javascript/event-loop) — task queues
* [abort\_controller.md](/docs/javascript/abort-controller) — cancel async waits
* [performance.md](/docs/javascript/performance) — measuring delays
* [promise.md](/docs/javascript/promise) — sleep helpers
* [web\_workers.md](/docs/javascript/web-workers) — timers in workers


# Type Coercion (/docs/javascript/type-coercion)



# Type Coercion [#type-coercion]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Coercion converts values between types implicitly (`==`, `+`, `if`) or explicitly (`Number`, `String`, `Boolean`, `BigInt`). Prefer explicit conversions. Know `ToPrimitive`, string concatenation vs addition, and truthiness to debug surprising results.

## 🔧 Core concepts [#-core-concepts]

* **Explicit**: `Number(x)`, `String(x)`, `Boolean(x)`, `BigInt(x)`, `parseInt` / `parseFloat`.
* **Implicit**: `+x` (number), `x + ""` (string), `!!x` (boolean), `==` rules.
* **`+`**: if either side is string, concatenate; else numeric add.
* **`ToPrimitive`**: prefers `valueOf` then `toString` (hint-dependent).
* **Truthy/falsy**: see conditionals — not the same as `Boolean` edge cases for objects.

```js
Number("42"); // 42
String(42); // "42"
Boolean(0); // false
"3" + 1; // "31"
+"3" + 1; // 4
```

## 💡 Examples [#-examples]

```js
// Numeric
Number(""); // 0
Number("  12 "); // 12
Number("12a"); // NaN
parseInt("12a", 10); // 12
parseInt("08", 10); // 8 — always pass radix

// Boolean
Boolean([]); // true
Boolean({}); // true
Boolean(""); // false

// == coercion highlights (avoid)
false == 0; // true
"" == 0; // true
null == undefined; // true
null == 0; // false

// Objects
[] + []; // ""
[] + {}; // "[object Object]"
{} + []; // depends on ASI / context — avoid

// valueOf / toString
const money = {
  valueOf() {
    return 100;
  },
};
money + 1; // 101

// Explicit helpers
const toInt = (v) => {
  const n = Number.parseInt(String(v), 10);
  return Number.isFinite(n) ? n : null;
};
```

```js
// Template always stringifies
`${[1, 2]}`; // "1,2"
`${{ a: 1 }}`; // "[object Object]"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `parseInt` without radix and hex/`0`-prefix history — always pass `10`.
* `Number(null)` is `0` but `Number(undefined)` is `NaN`.
* Arrays coerce to strings via `join` — `==` comparisons get weird.
* `BigInt` does not coerce with `Number` in arithmetic — convert deliberately.
* Relying on `==` “convenience” creates subtle bugs — use `===` + explicit casts.

## 🔗 Related [#-related]

* [equality.md](/docs/javascript/equality) — === vs ==
* [boolean.md](/docs/javascript/boolean) — ToBoolean
* [number.md](/docs/javascript/number) — Number quirks
* [bigint.md](/docs/javascript/bigint) — BigInt conversion
* [strings.md](/docs/javascript/strings) — String conversion


# Typed Arrays (/docs/javascript/typed-arrays)



# Typed Arrays [#typed-arrays]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Typed arrays are array-like views over binary `ArrayBuffer` (and `SharedArrayBuffer`) memory. Use them for files, WebGL, WebAudio, WASM, network protocols, and precise integer/float layouts. They fix element types and sizes — no holes, no mixed types.

## 🔧 Core concepts [#-core-concepts]

| Type                                             | Bytes | Description     |
| ------------------------------------------------ | ----- | --------------- |
| `Int8Array` / `Uint8Array` / `Uint8ClampedArray` | 1     | 8-bit           |
| `Int16Array` / `Uint16Array`                     | 2     | 16-bit          |
| `Int32Array` / `Uint32Array`                     | 4     | 32-bit          |
| `Float32Array` / `Float64Array`                  | 4 / 8 | IEEE floats     |
| `BigInt64Array` / `BigUint64Array`               | 8     | BigInt elements |

* **`ArrayBuffer`**: raw bytes; **view** interprets them.
* **`DataView`**: explicit endianness for mixed layouts.
* **`buffer` / `byteOffset` / `byteLength`**: view window into buffer.
* **Endianness**: typed arrays use platform endianness; DataView lets you choose.

```js
const buf = new ArrayBuffer(8);
const view = new Uint32Array(buf);
view[0] = 0xffffffff;
```

## 💡 Examples [#-examples]

```js
// From length / from array
const a = new Uint8Array(4);
const b = new Uint8Array([1, 2, 3, 4]);
const c = new Uint8Array(b); // copy

// Shared buffer, two views
const buffer = new ArrayBuffer(16);
const u8 = new Uint8Array(buffer);
const f32 = new Float32Array(buffer);
f32[0] = 1.5;
u8.slice(0, 4); // bytes of that float

// Subarray (view) vs slice (copy)
const mid = u8.subarray(2, 6); // shares buffer
const copy = u8.slice(2, 6); // new buffer

// DataView for protocols
const dv = new DataView(buffer);
dv.setUint16(0, 0x1234, false); // big-endian
dv.getUint16(0, false);

// Bytes from string
const enc = new TextEncoder().encode("hi");
const dec = new TextDecoder().decode(enc);

// Fetch as bytes
const res = await fetch("/file.bin");
const bytes = new Uint8Array(await res.arrayBuffer());
```

```js
// Clamped for canvas ImageData
const clamped = new Uint8ClampedArray([300, -1, 128]);
// [255, 0, 128]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Out-of-range assigns wrap (or clamp for `Uint8ClampedArray`) — no throw.
* `TypedArray` is not a real `Array` — no `push`/`pop`; some methods differ.
* Endian bugs when exchanging binary across architectures — prefer DataView for wire formats.
* Detached buffers (after `postMessage` transfer / WASM) throw on access.
* Align `byteOffset` to element size for multi-byte typed arrays.

## 🔗 Related [#-related]

* [bigint.md](/docs/javascript/bigint) — BigInt64Array
* [encode.md](/docs/javascript/encode) — TextEncoder
* [web\_workers.md](/docs/javascript/web-workers) — transferable buffers
* [fetch.md](/docs/javascript/fetch) — arrayBuffer bodies
* [DOM/… canvas](/docs/javascript/../html/canvas) — ImageData buffers


# typeof Basics (/docs/javascript/typeof-basics)



# typeof Basics [#typeof-basics]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`typeof` is an operator that returns a string describing a value’s type tag. It is useful for quick checks while learning, with a few famous quirks to memorize.

## 🔧 Core concepts [#-core-concepts]

| Expression                    | Typical result            |
| ----------------------------- | ------------------------- |
| `typeof "hi"`                 | `"string"`                |
| `typeof 42`                   | `"number"`                |
| `typeof 42n`                  | `"bigint"`                |
| `typeof true`                 | `"boolean"`               |
| `typeof undefined`            | `"undefined"`             |
| `typeof Symbol()`             | `"symbol"`                |
| `typeof \{\}` / `[]` / `null` | `"object"` (see pitfalls) |
| `typeof function () \{\}`     | `"function"`              |

`typeof` never throws on an undeclared variable in older patterns like `typeof x` — it yields `"undefined"`. Prefer declared variables anyway.

## 💡 Examples [#-examples]

**Primitives:**

```js
console.log(typeof "hello"); // string
console.log(typeof 3.14);    // number
console.log(typeof true);    // boolean
console.log(typeof undefined); // undefined
```

**Objects and functions:**

```js
console.log(typeof { a: 1 });     // object
console.log(typeof [1, 2]);       // object
console.log(typeof null);         // object  ← historical bug
console.log(typeof (() => 1));    // function
```

**Guarding before use:**

```js
function double(n) {
  if (typeof n !== "number" || Number.isNaN(n)) {
    throw new TypeError("n must be a number");
  }
  return n * 2;
}

console.log(double(21));
```

**Optional value check:**

```js
let title;
console.log(typeof title); // undefined
title = "Docs";
console.log(typeof title); // string
```

## ⚠️ Pitfalls [#️-pitfalls]

* `typeof null === "object"` — check null with `value === null`.
* Arrays are `"object"` — use `Array.isArray(x)`.
* `typeof NaN` is `"number"`.
* For class instances, prefer `instanceof` or brand checks over `typeof`.

## 🔗 Related [#-related]

* [variables\_let\_const.md](/docs/javascript/variables-let-const)
* [null\_undefined.md](/docs/javascript/null-undefined)
* [hello\_world.md](/docs/javascript/hello-world)
* [equality.md](/docs/javascript/equality)


# Node URL helpers (/docs/javascript/url-node)



# Node URL helpers [#node-url-helpers]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js `node:url` complements the WHATWG `URL&#x60; API with filesystem bridges: &#x2A;*`pathToFileURL`*&#x2A;, &#x2A;*`fileURLToPath`**, and legacy `url.parse` (avoid). Use these when converting between OS paths and `file:` URLs — especially in ESM (`import.meta.url`).

```js
import { pathToFileURL, fileURLToPath } from "node:url";
```

## 🔧 Core concepts [#-core-concepts]

* **`URL`**: standard absolute URL class (also global in Node) — `href`, `pathname`, `searchParams`, etc.
* **`pathToFileURL(path)`**: absolute filesystem path → `URL` with `file:` protocol.
* **`fileURLToPath(url)`**: `file:` URL / string → absolute OS path (handles Windows quirks).
* **`import.meta.url`**: ESM module’s own `file:` URL.
* **Legacy**: `url.parse` / `url.format` are legacy; prefer WHATWG `URL`.

## 💡 Examples [#-examples]

```js
import path from "node:path";
import { pathToFileURL, fileURLToPath } from "node:url";

// ESM __filename / __dirname
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const fileUrl = pathToFileURL(path.join(__dirname, "data.json"));
console.log(fileUrl.href); // file:///…

const back = fileURLToPath(fileUrl);
console.log(back); // absolute path

// Dynamic import from path
const modUrl = pathToFileURL(path.join(__dirname, "plugin.js")).href;
const plugin = await import(modUrl);

// WHATWG URL (same as browsers)
const u = new URL("https://example.com/a?x=1#h");
u.searchParams.get("x"); // '1'
u.pathname = "/b";
console.log(u.toString());
```

```js
// Resolve relative to current module
const asset = new URL("./assets/logo.png", import.meta.url);
const assetPath = fileURLToPath(asset);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `fileURLToPath` only accepts `file:` URLs — http(s) throws.
* On Windows, paths and `file:` URLs differ (`C:\` vs `file:///C:/`); always convert with these helpers.
* `URL.pathname` is percent-encoded; do not treat it as a raw filesystem path — use `fileURLToPath`.
* Legacy `url.parse` is mutable/quirky and marked legacy in docs.
* Relative path strings are not valid `URL` bases without a base argument.

## 🔗 Related [#-related]

* [URL](/docs/javascript/url) — WHATWG `URL` / `URLSearchParams`
* [Path](/docs/javascript/path) — `join`, `dirname`, `resolve`
* [ESM import/export](/docs/javascript/import-export) — `import.meta.url`
* [CommonJS modules](/docs/javascript/modules-commonjs) — `__dirname` without URL helpers
* [fetch](/docs/javascript/fetch) — requesting http(s) URLs
* [fs](/docs/javascript/fs) — open paths from `fileURLToPath`


# URL & URLSearchParams (/docs/javascript/url)



# URL & URLSearchParams [#url--urlsearchparams]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

The `URL` API parses and builds absolute URLs safely. `URLSearchParams` reads and writes the query string without manual encoding mistakes. Prefer these over string concatenation.

## 🔧 Core concepts [#-core-concepts]

* **`new URL(url, base?)`**: parse; throws `TypeError` on invalid input.
* **Parts**: `protocol`, `username`, `password`, `host`, `hostname`, `port`, `pathname`, `search`, `hash`, `href`, `origin`.
* **`searchParams`**: live `URLSearchParams` view of the query.
* **Params API**: `get`, `getAll`, `set`, `append`, `delete`, `has`, `sort`, iterate.
* **Relative resolve**: `new URL("/x", "https://example.com/a/")`.

```js
const u = new URL("https://example.com:443/path?q=1#top");
u.hostname; // example.com
u.searchParams.get("q"); // "1"
```

## 💡 Examples [#-examples]

```js
// Build safely
const url = new URL("https://api.example.com/v1/search");
url.searchParams.set("q", "café & tea");
url.searchParams.set("page", "2");
console.log(url.href);

// Resolve relative
const abs = new URL("../img/a.png", "https://cdn.example.com/assets/css/");
// https://cdn.example.com/assets/img/a.png

// Read from location (browser)
const page = new URL(location.href);
const tab = page.searchParams.get("tab") ?? "home";

// From form-urlencoded body
const params = new URLSearchParams("a=1&a=2&b=3");
params.getAll("a"); // ["1","2"]

// Iterate
for (const [k, v] of url.searchParams) {
  console.log(k, v);
}

// Update path
url.pathname = "/v2/search";

// canParse (modern)
URL.canParse?.("https://ok.test"); // true
```

```js
await fetch(url, { method: "GET" });

// POST as form body
await fetch("/login", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ user: "ada", remember: "1" }),
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* `new URL("/path")` without base throws in many environments — provide base or use absolute href.
* `searchParams.set` replaces all values for a key; use `append` for multi-value keys.
* Mutating `url.search` and `searchParams` stay in sync — pick one style.
* `pathname` encoding differs from full component encoding — use `encodeURIComponent` for segments you insert.
* `origin` is read-only; change via protocol/host/port pieces.

## 🔗 Related [#-related]

* [encode.md](/docs/javascript/encode) — encodeURIComponent
* [fetch.md](/docs/javascript/fetch) — requesting URLs
* [strings.md](/docs/javascript/strings) — string building
* [api.md](/docs/javascript/api) — related web APIs
* [DOM/window.md](/docs/javascript/dom/window) — location
* [DOM/navigation.md](/docs/javascript/dom/navigation) — history / location


# util (/docs/javascript/util)



# util [#util]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js `node:util` offers helpers for promisifying callback APIs, debugging inspection, type checks, and text formatting. Small but frequently used when bridging older Node APIs to async/await.

```js
import util from "node:util";
```

## 🔧 Core concepts [#-core-concepts]

* **`promisify(fn)`**: wrap `(…args, (err, result) => …)` into a function returning a Promise.
* **`callbackify(fn)`**: opposite direction — Promise function → error-first callback.
* **`inspect(obj, options?)`**: rich string representation for logging (depth, colors, getters).
* **`util.types`**: precise type predicates (`isPromise`, `isDate`, `isRegExp`, `isUint8Array`, …).
* **`format` / `styleText`**: printf-like formatting; styled terminal text (Node 20+ for `styleText`).
* **`deprecate(fn, msg)`**: wrap APIs to emit deprecation warnings once.

## 💡 Examples [#-examples]

```js
import util from "node:util";
import { readFile } from "node:fs";
import { execFile } from "node:child_process";

const readFileP = util.promisify(readFile);
const text = await readFileP("a.txt", "utf8");

const execFileP = util.promisify(execFile);
const { stdout } = await execFileP("node", ["-v"]);

console.log(util.inspect({ a: 1, nest: { b: [1, 2] } }, { depth: 3, colors: true }));

const { types } = util;
types.isPromise(Promise.resolve(1)); // true
types.isDate(new Date()); // true
types.isRegExp(/x/); // true

util.format("%s: %d", "count", 3); // 'count: 3'

const oldApi = util.deprecate(function legacy() {}, "legacy() is deprecated");
oldApi();
```

```js
// Custom inspect
const box = {
  value: 42,
  [util.inspect.custom](depth, opts) {
    return `Box(${this.value})`;
  },
};
console.log(util.inspect(box)); // Box(42)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `promisify` expects error-first callbacks; nonstandard APIs need a custom promisify symbol or manual wrapper.
* `inspect` default depth can hide nested data — raise `depth` or use `depth: null` carefully (huge output).
* `typeof` is weaker than `util.types` for built-ins (e.g. promises, typed arrays).
* Do not use `inspect` output as a serialization format — use JSON or a real serializer.
* Some APIs already return Promises (`fs/promises`) — no need to promisify.

## 🔗 Related [#-related]

* [Async](/docs/javascript/async) — async/await with promisified APIs
* [Promise](/docs/javascript/promise) — Promise basics
* [fs](/docs/javascript/fs) — prefer `fs/promises` over promisify
* [child\_process](/docs/javascript/child-process) — promisify `execFile`
* [typeof basics](/docs/javascript/typeof-basics) — `typeof` vs precise checks
* [console](/docs/javascript/console) — logging alternatives


# Variables: let and const (/docs/javascript/variables-let-const)



# Variables: let and const [#variables-let-and-const]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Modern JavaScript declares variables with `let` and `const`. Avoid `var` in new code. `const` prevents reassignment of the binding; `let` allows reassignment. Both are block-scoped.

## 🔧 Core concepts [#-core-concepts]

| Keyword | Reassign? | Scope        | Typical use        |
| ------- | --------- | ------------ | ------------------ |
| `const` | No        | Block `\{\}` | Default choice     |
| `let`   | Yes       | Block `\{\}` | Values that change |
| `var`   | Yes       | Function     | Legacy only        |

`const` objects/arrays can still have their *contents* mutated — the binding cannot point to a new object.

## 💡 Examples [#-examples]

**Basic declarations:**

```js
const name = "Sam";
let score = 0;

score = score + 10;
// name = "Alex"; // TypeError
console.log(name, score);
```

**Block scope:**

```js
let x = 1;
{
  let x = 2;
  console.log(x); // 2
}
console.log(x); // 1
```

**const with objects:**

```js
const user = { id: 1, role: "guest" };
user.role = "admin"; // OK — mutating property
// user = {};       // TypeError — rebinding

const nums = [1, 2];
nums.push(3); // OK
console.log(user, nums);
```

**Temporal dead zone (use before declare):**

```js
// console.log(a); // ReferenceError
let a = 5;
console.log(a);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Prefer `const` until you know a value must change.
* `const` ≠ deeply immutable.
* Redeclaring the same `let`/`const` in one scope is a SyntaxError.
* Forgetting `let`/`const` creates an accidental global in non-strict sloppy mode.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/javascript/hello-world)
* [typeof\_basics.md](/docs/javascript/typeof-basics)
* [null\_undefined.md](/docs/javascript/null-undefined)
* [template\_basics.md](/docs/javascript/template-basics)


# WeakMap & WeakSet (/docs/javascript/weakmap-weakset)



# WeakMap & WeakSet [#weakmap--weakset]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`WeakMap` and `WeakSet` hold **weak** references to object keys/values so entries can be garbage-collected when nothing else references the key. They are not iterable and have no `.size` — designed for private metadata, caching, and DOM-associated state without leaks.

## 🔧 Core concepts [#-core-concepts]

* **WeakMap**: keys must be objects (or non-registered symbols in modern engines); values any.
* **API**: `get`, `set`, `has`, `delete` — no iteration.
* **WeakSet**: objects only; `add`, `has`, `delete`.
* **GC**: when key is unreachable, entry may disappear.
* **vs Map/Set**: strong refs keep keys alive forever if the collection lives.

```js
const wm = new WeakMap();
const el = document.createElement("div");
wm.set(el, { clicks: 0 });
wm.get(el).clicks++;
```

## 💡 Examples [#-examples]

```js
// Private data per instance (pre-#fields pattern)
const _balance = new WeakMap();
class Account {
  constructor(amount) {
    _balance.set(this, amount);
  }
  deposit(n) {
    _balance.set(this, _balance.get(this) + n);
  }
  get balance() {
    return _balance.get(this);
  }
}

// DOM metadata without expando properties
const state = new WeakMap();
function track(el) {
  if (!state.has(el)) state.set(el, { seen: 0 });
  state.get(el).seen++;
}

// Visited set for graph walk (objects)
const seen = new WeakSet();
function walk(node) {
  if (seen.has(node)) return;
  seen.add(node);
  for (const child of node.children ?? []) walk(child);
}

// Cache expensive computation keyed by object
const cache = new WeakMap();
function meta(obj) {
  if (cache.has(obj)) return cache.get(obj);
  const value = compute(obj);
  cache.set(obj, value);
  return value;
}
```

```js
// WeakRef / FinalizationRegistry (related, stronger control)
const ref = new WeakRef(obj);
ref.deref(); // obj or undefined if collected
```

## ⚠️ Pitfalls [#️-pitfalls]

* Primitives cannot be WeakMap keys (except allowed symbols) — box or use Map.
* Not enumerable: you cannot list keys for debugging easily.
* Do not rely on *when* GC runs — only that entries *may* go away.
* WeakMap values stay alive while the key is reachable — value holding key = leak cycle still collectable if only weakly held… avoid mutual strong cycles via other roots.
* `WeakSet` has no get — membership only.

## 🔗 Related [#-related]

* [map.md](/docs/javascript/map) — strong Map
* [set.md](/docs/javascript/set) — strong Set
* [oop.md](/docs/javascript/oop) — `#private` fields
* [DOM/storage.md](/docs/javascript/dom/storage) — not for persistence
* [objects.md](/docs/javascript/objects) — object identity as keys


# Web Workers (/docs/javascript/web-workers)



# Web Workers [#web-workers]

*JavaScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Web Workers run scripts off the main thread so heavy CPU work does not block UI. Dedicated workers are owned by one page; shared workers can be used by multiple; service workers intercept network (separate topic). Communicate via `postMessage` and structured clone / transferables.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new Worker(new URL("./worker.js", import.meta.url), \{ type: "module" \})`.
* **Messages**: `worker.postMessage(data, transfer?)` / `onmessage` / `message` event.
* **Terminate**: `worker.terminate()`; inside worker `self.close()`.
* **No DOM**: no `document`/`window` UI APIs; have `fetch`, timers, IndexedDB, WebAssembly, etc.
* **Transfer**: `ArrayBuffer`, `MessagePort`, some streams — zero-copy move.
* **Errors**: `worker.onerror`, `unhandledrejection` in module workers.

```js
const worker = new Worker(new URL("./heavy.js", import.meta.url), {
  type: "module",
});
worker.postMessage({ op: "sum", values: [1, 2, 3] });
worker.onmessage = (e) => console.log(e.data);
```

## 💡 Examples [#-examples]

```js
// main.js
const w = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
w.postMessage({ n: 40 });
w.addEventListener("message", (e) => {
  console.log("fib", e.data);
  w.terminate();
});

// worker.js
self.onmessage = (e) => {
  const { n } = e.data;
  self.postMessage(fib(n));
};
function fib(n) {
  return n < 2 ? n : fib(n - 1) + fib(n - 2);
}

// Transfer large buffer
const bytes = new Uint8Array(1_000_000);
worker.postMessage(bytes, [bytes.buffer]); // bytes.buffer detached

// MessageChannel for ports
const { port1, port2 } = new MessageChannel();
worker.postMessage({ port: port2 }, [port2]);
port1.onmessage = (e) => console.log(e.data);
```

```js
// Pool sketch
class Pool {
  constructor(size, url) {
    this.idle = Array.from(
      { length: size },
      () => new Worker(url, { type: "module" }),
    );
  }
  run(data) {
    const w = this.idle.pop();
    return new Promise((resolve, reject) => {
      w.onmessage = (e) => {
        this.idle.push(w);
        resolve(e.data);
      };
      w.onerror = reject;
      w.postMessage(data);
    });
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Classic workers need separate classic scripts; prefer `\{ type: "module" \}` + `import.meta.url`.
* Cloning large object graphs is expensive — transfer buffers or use `SharedArrayBuffer` (COOP/COEP).
* Workers don’t share memory with the page (except SAB) — no shared closures.
* Forgetting `terminate()` leaks threads.
* DOM / most Web APIs involving UI are unavailable — design data in/out carefully.

## 🔗 Related [#-related]

* [structured\_clone.md](/docs/javascript/structured-clone) — clone/transfer
* [typed\_arrays.md](/docs/javascript/typed-arrays) — binary payloads
* [event\_loop.md](/docs/javascript/event-loop) — main thread vs worker
* [abort\_controller.md](/docs/javascript/abort-controller) — cancel work
* [performance.md](/docs/javascript/performance) — measuring offload wins


# while / do...while (/docs/javascript/while)



# while / do...while [#while--dowhile]

*JavaScript · Reference cheat sheet*

## 📋 Overview [#-overview]

`while` repeats while a condition is truthy. `do...while` runs the body at least once. Use when the end condition is not a simple index range — and always ensure progress toward termination.

## 🔧 Core concepts [#-core-concepts]

* **`while (cond) \{ body \}`**: test first.
* **`do \{ body \} while (cond)`**: test after.
* **Control**: `break`, `continue`, labels.
* **Condition**: coerced with ToBoolean.
* **vs `for`**: `for` is clearer for known bounds; `while` for sentinel / stream / backoff loops.

```js
let n = 3;
while (n > 0) {
  console.log(n);
  n -= 1;
}
```

## 💡 Examples [#-examples]

```js
// Read until sentinel
let line;
while ((line = readLine()) !== null) {
  process(line);
}

// do...while menu
let choice;
do {
  choice = prompt("1) go  0) quit");
} while (choice !== "0" && choice !== null);

// Exponential backoff
async function retry(fn, attempts = 5) {
  let i = 0;
  let delay = 100;
  while (true) {
    try {
      return await fn();
    } catch (err) {
      if (++i >= attempts) throw err;
      await new Promise((r) => setTimeout(r, delay));
      delay *= 2;
    }
  }
}

// Linked list walk
let node = head;
while (node) {
  visit(node);
  node = node.next;
}

// continue / break
let i = 0;
while (i < 10) {
  i += 1;
  if (i % 2 === 0) continue;
  if (i > 7) break;
  console.log(i);
}
```

```js
// Poll with abort
async function waitFor(pred, signal, ms = 50) {
  while (!signal.aborted) {
    if (await pred()) return true;
    await new Promise((r) => setTimeout(r, ms));
  }
  return false;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Infinite loops from missing updates or always-true conditions — guard with counters/timeouts.
* `while (await fetch...)` without delay can hammer servers.
* Assignments in conditions (`while (x = next())`) need parentheses and careful null checks.
* `continue` in `do...while` still re-checks the condition — know your flow.
* Prefer `for...of` when iterating collections.

## 🔗 Related [#-related]

* [iteration.md](/docs/javascript/iteration) — loop overview
* [for\_of.md](/docs/javascript/for-of) — for...of
* [boolean.md](/docs/javascript/boolean) — truthiness
* [async.md](/docs/javascript/async) — async loops
* [promise.md](/docs/javascript/promise) — delays / retry
* [iterator.md](/docs/javascript/iterator) — generator loops


# App Router (/docs/nextjs/app-router)



# App Router [#app-router]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The App Router uses the `app/` directory for routes, layouts, loading UI, and nested segments. Folders define URL segments; special files define UI and behavior.

## 🔧 Core concepts [#-core-concepts]

| File            | Role                                                     |
| --------------- | -------------------------------------------------------- |
| `page.tsx`      | UI for a route (required for that URL)                   |
| `layout.tsx`    | Shared UI wrapping children; persists across navigations |
| `loading.tsx`   | Instant loading UI (Suspense boundary)                   |
| `error.tsx`     | Error boundary for the segment                           |
| `not-found.tsx` | 404 UI                                                   |
| `route.ts`      | Route Handler (API endpoint)                             |
| `template.tsx`  | Like layout but remounts on navigation                   |
| `default.tsx`   | Fallback for parallel routes                             |

| Convention    | Meaning                      |
| ------------- | ---------------------------- |
| `[id]`        | Dynamic segment              |
| `[...slug]`   | Catch-all                    |
| `[[...slug]]` | Optional catch-all           |
| `(group)`     | Route group — no URL segment |
| `@slot`       | Parallel route slot          |

## 💡 Examples [#-examples]

**Nested layout:**

```
app/
  layout.tsx
  page.tsx          → /
  blog/
    layout.tsx
    page.tsx        → /blog
    [slug]/
      page.tsx      → /blog/:slug
```

**Dynamic page:**

```tsx
// app/blog/[slug]/page.tsx
export default async function Post({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  return <h1>{slug}</h1>;
}
```

**Route group (no URL impact):**

```
app/(marketing)/about/page.tsx  → /about
app/(shop)/cart/page.tsx        → /cart
```

## ⚠️ Pitfalls [#️-pitfalls]

* `layout.tsx` does not remount on soft navigation — don't put one-shot client state there expecting reset.
* `params` and `searchParams` are async in recent Next.js — await them.
* A folder without `page.tsx` is not a reachable route by itself.

## 🔗 Related [#-related]

* [pages\_router.md](/docs/nextjs/pages-router)
* [server\_components.md](/docs/nextjs/server-components)
* [route\_handlers.md](/docs/nextjs/route-handlers)
* [link\_navigation.md](/docs/nextjs/link-navigation)
* [getting\_started.md](/docs/nextjs/getting-started)


# Caching (/docs/nextjs/caching)



# Caching [#caching]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

App Router caching spans the Request Memoization, Data Cache, Full Route Cache, and Router Cache. Defaults favor static where possible; opt into dynamic when data must be fresh.

## 🔧 Core concepts [#-core-concepts]

| Cache               | What it stores                                |
| ------------------- | --------------------------------------------- |
| Request Memoization | Dedupes identical `fetch` in one render pass  |
| Data Cache          | Persistent server fetch cache across requests |
| Full Route Cache    | Pre-rendered HTML/RSC payload at build        |
| Router Cache        | Client-side cache of visited segments         |

| Control                                       | Effect                               |
| --------------------------------------------- | ------------------------------------ |
| `fetch(url, \{ cache: 'no-store' \})`         | Skip Data Cache                      |
| `fetch(url, \{ next: \{ revalidate: N \} \})` | ISR-style revalidate every N seconds |
| `revalidatePath` / `revalidateTag`            | On-demand invalidation               |
| `export const dynamic = 'force-dynamic'`      | Always dynamic route                 |
| `export const revalidate = 60`                | Segment revalidate window            |

## 💡 Examples [#-examples]

**Time-based revalidation:**

```ts
const res = await fetch("https://api.example.com/items", {
  next: { revalidate: 3600, tags: ["items"] },
});
```

**On-demand revalidate (Server Action / Route Handler):**

```ts
import { revalidateTag } from "next/cache";

export async function refreshItems() {
  revalidateTag("items");
}
```

**Force dynamic:**

```ts
export const dynamic = "force-dynamic";
```

## ⚠️ Pitfalls [#️-pitfalls]

* Stale UI after mutations usually means missing `revalidatePath`/`revalidateTag`.
* Caching behavior differs between local `next dev` and production builds.
* Mixing `no-store` fetches inside otherwise static layouts can turn the whole route dynamic.

## 🔗 Related [#-related]

* [server\_components.md](/docs/nextjs/server-components)
* [route\_handlers.md](/docs/nextjs/route-handlers)
* [deployment.md](/docs/nextjs/deployment)
* [app\_router.md](/docs/nextjs/app-router)


# Deployment (/docs/nextjs/deployment)



# Deployment [#deployment]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Deploy Next.js with a Node server (`next start`), a Platform-as-a-Service (Vercel, etc.), or a static export when the app has no server-only features.

## 🔧 Core concepts [#-core-concepts]

| Mode          | Command / config            | Fits                     |
| ------------- | --------------------------- | ------------------------ |
| Node server   | `next build` → `next start` | SSR, Route Handlers, ISR |
| Vercel        | Git integration             | Full Next.js feature set |
| Docker        | Multi-stage Node image      | Self-hosted              |
| Static export | `output: 'export'`          | Fully static sites only  |

| Checklist               | Why                            |
| ----------------------- | ------------------------------ |
| Set production env vars | Secrets and `NEXT_PUBLIC_*`    |
| `NODE_ENV=production`   | Optimizations                  |
| Health endpoint         | Orchestrators / load balancers |
| Match Node version      | Avoid native module mismatches |

## 💡 Examples [#-examples]

**Build & start:**

```shellscript
npm run build
npm run start
```

**Static export (`next.config.ts`):**

```ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "export",
};
export default nextConfig;
```

**Docker (sketch):**

```dockerfile
FROM node:22-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
EXPOSE 3000
CMD ["npm", "start"]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Static export cannot use server features (SSR cookies, many Route Handlers, ISR the same way).
* Forgetting to set env vars on the host causes runtime crashes that never appeared locally.
* Binding only to `localhost` inside containers breaks external access — listen on `0.0.0.0` when required by the host.

## 🔗 Related [#-related]

* [env.md](/docs/nextjs/env)
* [caching.md](/docs/nextjs/caching)
* [middleware.md](/docs/nextjs/middleware)
* [getting\_started.md](/docs/nextjs/getting-started)
* [Docker/getting\_started.md](/docs/nextjs/../docker/getting-started)


# Environment Variables (/docs/nextjs/env)



# Environment Variables [#environment-variables]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Next.js loads `.env*` files and exposes variables to Node (server) and, with a prefix, to the browser bundle. Never ship secrets with the public prefix.

## 🔧 Core concepts [#-core-concepts]

| File                                   | Typical use                         |
| -------------------------------------- | ----------------------------------- |
| `.env`                                 | Default for all environments        |
| `.env.local`                           | Local secrets (gitignored)          |
| `.env.development` / `.env.production` | Env-specific defaults               |
| `.env*.local`                          | Overrides; highest priority locally |

| Access                             | Visibility                                 |
| ---------------------------------- | ------------------------------------------ |
| `process.env.MY_SECRET`            | Server only                                |
| `process.env.NEXT_PUBLIC_*`        | Inlined into client JS                     |
| `NEXT_PUBLIC_*` in Edge/Middleware | Available if set at build/runtime per host |

## 💡 Examples [#-examples]

**`.env.local`:**

```shellscript
DATABASE_URL=postgres://...
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

**Server usage:**

```ts
const url = process.env.DATABASE_URL;
if (!url) throw new Error("DATABASE_URL is required");
```

**Client usage:**

```tsx
"use client";
export function Banner() {
  return <p>{process.env.NEXT_PUBLIC_APP_URL}</p>;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing env vars often requires restarting `next dev` / rebuilding.
* `NEXT_PUBLIC_` values are baked in at build time for many hosts — treat them as public.
* Don't put API keys in `NEXT_PUBLIC_*` even "temporarily".

## 🔗 Related [#-related]

* [server\_components.md](/docs/nextjs/server-components)
* [deployment.md](/docs/nextjs/deployment)
* [middleware.md](/docs/nextjs/middleware)
* [caching.md](/docs/nextjs/caching)


# Getting Started with Next.js (/docs/nextjs/getting-started)



# Getting Started with Next.js [#getting-started-with-nextjs]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Next.js is a React framework for full-stack web apps. It adds routing, rendering modes, image optimization, and deployment conventions on top of React.

## 🔧 Core concepts [#-core-concepts]

| Idea         | Meaning                                               |
| ------------ | ----------------------------------------------------- |
| App Router   | File-based routing under `app/` (default in new apps) |
| Pages Router | Legacy file-based routing under `pages/`              |
| RSC          | React Server Components — default in App Router       |
| SSR / SSG    | Server-render on request vs pre-render at build       |
| Turbopack    | Fast bundler used by `next dev` (newer versions)      |

**Create a project:**

```shellscript
npx create-next-app@latest my-app
cd my-app
npm run dev
```

| Script       | Purpose                  |
| ------------ | ------------------------ |
| `next dev`   | Local development server |
| `next build` | Production build         |
| `next start` | Serve production build   |
| `next lint`  | Run ESLint               |

## 💡 Examples [#-examples]

**Minimal `app/page.tsx`:**

```tsx
export default function Home() {
  return <h1>Hello Next.js</h1>;
}
```

**`package.json` scripts:**

```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}
```

**Check version:**

```shellscript
npx next --version
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing App Router (`app/`) and Pages Router (`pages/`) without a clear plan causes confusion.
* Client hooks (`useState`, `useEffect`) need `'use client'` in App Router.
* Forgetting `next build` before `next start` serves a stale or missing build.

## 🔗 Related [#-related]

* [app\_router.md](/docs/nextjs/app-router)
* [pages\_router.md](/docs/nextjs/pages-router)
* [server\_components.md](/docs/nextjs/server-components)
* [deployment.md](/docs/nextjs/deployment)
* [glossary.md](/docs/nextjs/glossary)


# Glossary (/docs/nextjs/glossary)



# Glossary [#glossary]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of Next.js terms spanning App Router, rendering, caching, and deployment.

## 🔧 Core concepts [#-core-concepts]

| Term                 | Definition                                                          |
| -------------------- | ------------------------------------------------------------------- |
| App Router           | Routing system based on the `app/` directory and special files.     |
| CSR                  | Client-side rendering in the browser after JS loads.                |
| Dynamic segment      | Folder like `[id]` that captures a URL parameter.                   |
| Edge runtime         | Lightweight runtime for Middleware and some Route Handlers.         |
| Hydration            | Attaching client React to server-rendered HTML.                     |
| ISR                  | Incremental Static Regeneration — update static pages after deploy. |
| Layout               | Persistent UI wrapper (`layout.tsx`) shared by child routes.        |
| Middleware           | Edge code that runs before a request is completed.                  |
| Partial Prerendering | Hybrid static shell + dynamic holes (version-dependent).            |
| Prefetch             | Loading a route in the background via `Link`.                       |
| Route Handler        | `route.ts` exporting HTTP methods as an API endpoint.               |
| Route group          | `(name)` folder that organizes routes without affecting the URL.    |
| RSC                  | React Server Component rendered on the server by default.           |
| Soft navigation      | Client transition without full document reload.                     |
| SSG                  | Static Site Generation at build time.                               |
| SSR                  | Server-Side Rendering on each request.                              |
| Streaming            | Sending UI in chunks via Suspense / `loading.tsx`.                  |
| Turbopack            | Rust-based bundler used in modern `next dev`.                       |

## 💡 Examples [#-examples]

**Dynamic segment mental model:**

```
app/shop/[slug]/page.tsx  →  /shop/shoes
```

**RSC vs client:**

```tsx
// Server (default)
export default async function Page() { /* fetch, await */ }

// Client
"use client";
export function Widget() { /* useState, onClick */ }
```

## ⚠️ Pitfalls [#️-pitfalls]

* Glossaries drift — verify behavior against your installed Next.js major version.
* “Static” vs “dynamic” depends on APIs used (`cookies`, `headers`, `no-store`), not folder names alone.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/nextjs/getting-started)
* [app\_router.md](/docs/nextjs/app-router)
* [caching.md](/docs/nextjs/caching)
* [server\_components.md](/docs/nextjs/server-components)
* [README.md](/docs/nextjs)


# next/image (/docs/nextjs/image)



# next/image [#nextimage]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`next/image` optimizes images: resizing, modern formats, lazy loading, and layout shift prevention via required dimensions or `fill`.

## 🔧 Core concepts [#-core-concepts]

| Prop               | Purpose                                         |
| ------------------ | ----------------------------------------------- |
| `src`              | Path or remote URL                              |
| `alt`              | Required accessibility text                     |
| `width` / `height` | Intrinsic size (static imports can infer)       |
| `fill`             | Fill parent (parent needs `position: relative`) |
| `sizes`            | Hint for responsive `srcset`                    |
| `priority`         | Preload above-the-fold images                   |
| `placeholder`      | `"blur"` or `"empty"`                           |

| Config (`next.config`)              | Purpose               |
| ----------------------------------- | --------------------- |
| `images.remotePatterns`             | Allow remote hosts    |
| `images.formats`                    | AVIF/WebP preferences |
| `images.deviceSizes` / `imageSizes` | Generated widths      |

## 💡 Examples [#-examples]

**Local image:**

```tsx
import Image from "next/image";
import hero from "@/public/hero.jpg";

export function Hero() {
  return <Image src={hero} alt="Product hero" priority />;
}
```

**Remote with sizes:**

```tsx
<Image
  src="https://cdn.example.com/photo.jpg"
  alt="Photo"
  width={800}
  height={600}
  sizes="(max-width: 768px) 100vw, 800px"
/>
```

**Fill layout:**

```tsx
<div style={{ position: "relative", width: "100%", height: 320 }}>
  <Image src="/banner.jpg" alt="Banner" fill style={{ objectFit: "cover" }} />
</div>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Remote images fail without `remotePatterns` (or legacy `domains`).
* Missing `sizes` with `fill` can download oversized images on mobile.
* Overusing `priority` defeats lazy loading and hurts LCP for other assets.

## 🔗 Related [#-related]

* [link\_navigation.md](/docs/nextjs/link-navigation)
* [metadata.md](/docs/nextjs/metadata)
* [caching.md](/docs/nextjs/caching)
* [deployment.md](/docs/nextjs/deployment)


# Next.js (/docs/nextjs)



# Next.js [#nextjs]

App Router, RSC, deployment.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Link & Navigation (/docs/nextjs/link-navigation)



# Link & Navigation [#link--navigation]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Use `next/link` for client-side soft navigation and `next/navigation` hooks for programmatic routing in the App Router. Prefer Link over raw `<a>` for internal routes.

## 🔧 Core concepts [#-core-concepts]

| API                               | Router       | Purpose                              |
| --------------------------------- | ------------ | ------------------------------------ |
| `Link`                            | Both         | Prefetch + soft navigate             |
| `useRouter` (`next/navigation`)   | App          | `push`, `replace`, `refresh`, `back` |
| `usePathname` / `useSearchParams` | App          | Read location                        |
| `useRouter` (`next/router`)       | Pages        | Legacy router                        |
| `redirect` / `notFound`           | App (Server) | Server-side navigation / 404         |

| `Link` prop | Notes                                               |
| ----------- | --------------------------------------------------- |
| `href`      | String or URL object                                |
| `prefetch`  | Default true in many cases; disable for rare routes |
| `replace`   | Replace history entry                               |
| `scroll`    | Scroll to top (default true)                        |

## 💡 Examples [#-examples]

**Basic Link:**

```tsx
import Link from "next/link";

export function Nav() {
  return <Link href="/docs">Docs</Link>;
}
```

**Programmatic navigation (Client):**

```tsx
"use client";
import { useRouter } from "next/navigation";

export function Go() {
  const router = useRouter();
  return <button onClick={() => router.push("/dashboard")}>Open</button>;
}
```

**Server redirect:**

```tsx
import { redirect } from "next/navigation";

export default function Page() {
  redirect("/login");
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `useRouter` from `next/router` vs `next/navigation` — wrong import breaks App Router pages.
* `useSearchParams()` can force a client Suspense boundary — wrap accordingly.
* External URLs should use `<a>` (or `Link` with absolute URL); don't treat them like soft navigations for SEO-critical exit links without care.

## 🔗 Related [#-related]

* [app\_router.md](/docs/nextjs/app-router)
* [pages\_router.md](/docs/nextjs/pages-router)
* [middleware.md](/docs/nextjs/middleware)
* [server\_components.md](/docs/nextjs/server-components)


# Metadata (/docs/nextjs/metadata)



# Metadata [#metadata]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

App Router metadata APIs set `<title>`, `<meta>`, Open Graph, icons, and more — statically via `metadata` export or dynamically via `generateMetadata`.

## 🔧 Core concepts [#-core-concepts]

| API                     | When                                             |
| ----------------------- | ------------------------------------------------ |
| `export const metadata` | Static, known at build                           |
| `generateMetadata`      | Dynamic per request/params                       |
| `generateViewport`      | Viewport / theme-color                           |
| File conventions        | `favicon.ico`, `opengraph-image.tsx`, `icon.tsx` |

| Field                   | Purpose                              |
| ----------------------- | ------------------------------------ |
| `title`                 | Document title (supports `template`) |
| `description`           | Meta description                     |
| `openGraph` / `twitter` | Social cards                         |
| `robots`                | Indexing directives                  |
| `alternates.canonical`  | Canonical URL                        |

## 💡 Examples [#-examples]

**Static metadata:**

```tsx
import type { Metadata } from "next";

export const metadata: Metadata = {
  title: { default: "My App", template: "%s · My App" },
  description: "Product docs and dashboard",
};
```

**Dynamic metadata:**

```tsx
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  return { title: slug };
}
```

**Root layout title template:**

```tsx
// app/layout.tsx
export const metadata = {
  title: { default: "Home", template: "%s | Acme" },
};
```

## ⚠️ Pitfalls [#️-pitfalls]

* Metadata in Client Components is ignored — keep it in Server layouts/pages.
* Duplicate titles across nested layouts can fight; use `template` deliberately.
* Social crawlers need absolute OG image URLs in production.

## 🔗 Related [#-related]

* [app\_router.md](/docs/nextjs/app-router)
* [server\_components.md](/docs/nextjs/server-components)
* [image.md](/docs/nextjs/image)
* [getting\_started.md](/docs/nextjs/getting-started)


# Middleware (/docs/nextjs/middleware)



# Middleware [#middleware]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Middleware runs on the Edge before a request is completed. Use it for redirects, rewrites, auth gates, A/B headers, and geo-based routing — not heavy business logic.

## 🔧 Core concepts [#-core-concepts]

| API                       | Role                             |
| ------------------------- | -------------------------------- |
| `middleware.ts`           | File at project root or `src/`   |
| `NextRequest`             | Incoming request                 |
| `NextResponse.next()`     | Continue                         |
| `NextResponse.redirect()` | Redirect                         |
| `NextResponse.rewrite()`  | Internal rewrite                 |
| `matcher`                 | Limit which paths run middleware |

| Runtime                     | Notes                                  |
| --------------------------- | -------------------------------------- |
| Edge                        | Default; limited Node APIs             |
| Node (experimental options) | Check current Next.js docs for support |

## 💡 Examples [#-examples]

**Redirect unauthenticated users:**

```ts
import { NextResponse } from "next/server";
import type { NextRequest } from "next/server";

export function middleware(req: NextRequest) {
  const token = req.cookies.get("session")?.value;
  if (!token && req.nextUrl.pathname.startsWith("/dashboard")) {
    return NextResponse.redirect(new URL("/login", req.url));
  }
  return NextResponse.next();
}

export const config = {
  matcher: ["/dashboard/:path*"],
};
```

**Rewrite:**

```ts
export function middleware(req: NextRequest) {
  if (req.nextUrl.pathname === "/old") {
    return NextResponse.rewrite(new URL("/new", req.url));
  }
  return NextResponse.next();
}
```

**Set a header:**

```ts
export function middleware(req: NextRequest) {
  const res = NextResponse.next();
  res.headers.set("x-pathname", req.nextUrl.pathname);
  return res;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Middleware runs on many requests — keep it fast and matcher-scoped.
* Avoid DB calls and large dependency graphs in Edge middleware.
* Infinite redirect loops are easy if login ↔ protected matchers overlap badly.

## 🔗 Related [#-related]

* [route\_handlers.md](/docs/nextjs/route-handlers)
* [env.md](/docs/nextjs/env)
* [app\_router.md](/docs/nextjs/app-router)
* [deployment.md](/docs/nextjs/deployment)


# Pages Router (/docs/nextjs/pages-router)



# Pages Router [#pages-router]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The Pages Router is the original Next.js routing model: each file under `pages/` maps to a URL. Still supported and common in older codebases.

## 🔧 Core concepts [#-core-concepts]

| File / pattern        | URL                  |
| --------------------- | -------------------- |
| `pages/index.tsx`     | `/`                  |
| `pages/about.tsx`     | `/about`             |
| `pages/blog/[id].tsx` | `/blog/:id`          |
| `pages/api/hello.ts`  | `/api/hello`         |
| `pages/_app.tsx`      | App wrapper          |
| `pages/_document.tsx` | Custom HTML document |
| `pages/404.tsx`       | Custom 404           |

| Data API             | When it runs                     |
| -------------------- | -------------------------------- |
| `getStaticProps`     | Build time (SSG)                 |
| `getStaticPaths`     | Build time paths for dynamic SSG |
| `getServerSideProps` | Every request (SSR)              |

## 💡 Examples [#-examples]

**Static page with props:**

```tsx
export async function getStaticProps() {
  return { props: { title: "Home" } };
}

export default function Home({ title }: { title: string }) {
  return <h1>{title}</h1>;
}
```

**Dynamic SSR:**

```tsx
export async function getServerSideProps(ctx: { params: { id: string } }) {
  return { props: { id: ctx.params.id } };
}
```

**API route:**

```ts
// pages/api/hello.ts
import type { NextApiRequest, NextApiResponse } from "next";

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ ok: true });
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don't put secrets in `getStaticProps` props — they ship to the client HTML.
* `_document.tsx` only runs on the server; no React context/hooks from `_app` there.
* Prefer App Router for new projects unless you have a Pages-only constraint.

## 🔗 Related [#-related]

* [app\_router.md](/docs/nextjs/app-router)
* [route\_handlers.md](/docs/nextjs/route-handlers)
* [link\_navigation.md](/docs/nextjs/link-navigation)
* [Comparisons/pages\_vs\_app\_router.md](/docs/nextjs/../comparisons/pages-vs-app-router)


# Route Handlers (/docs/nextjs/route-handlers)



# Route Handlers [#route-handlers]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Route Handlers live in `app/**/route.ts` (or `.js`) and export HTTP method functions. They replace many `pages/api` use cases in the App Router.

## 🔧 Core concepts [#-core-concepts]

| Export             | HTTP method     |
| ------------------ | --------------- |
| `GET`              | Read            |
| `POST`             | Create / submit |
| `PUT` / `PATCH`    | Update          |
| `DELETE`           | Delete          |
| `HEAD` / `OPTIONS` | Meta / CORS     |

| Helper         | Use                                   |
| -------------- | ------------------------------------- |
| `NextRequest`  | Extended Request (cookies, `nextUrl`) |
| `NextResponse` | JSON, redirects, cookies              |
| `params`       | Dynamic segment values                |

## 💡 Examples [#-examples]

**JSON GET:**

```ts
// app/api/hello/route.ts
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "hi" });
}
```

**POST with body:**

```ts
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
  const body = await req.json();
  return NextResponse.json({ received: body }, { status: 201 });
}
```

**Dynamic segment:**

```ts
// app/api/users/[id]/route.ts
export async function GET(
  _req: Request,
  ctx: { params: Promise<{ id: string }> },
) {
  const { id } = await ctx.params;
  return Response.json({ id });
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don't export a `page.tsx` and `route.ts` for the same path segment.
* Default caching of `GET` can surprise you — set `export const dynamic = 'force-dynamic'` when needed.
* Large file uploads need streaming/`FormData` care; don't assume unlimited body size.

## 🔗 Related [#-related]

* [app\_router.md](/docs/nextjs/app-router)
* [middleware.md](/docs/nextjs/middleware)
* [caching.md](/docs/nextjs/caching)
* [pages\_router.md](/docs/nextjs/pages-router)


# Server Components (/docs/nextjs/server-components)



# Server Components [#server-components]

*Next.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

In the App Router, components are Server Components by default. They render on the server, can access backend resources directly, and send a compact RSC payload to the client.

## 🔧 Core concepts [#-core-concepts]

| Kind             | Directive      | Can use                                  |
| ---------------- | -------------- | ---------------------------------------- |
| Server Component | (default)      | `async`, DB, secrets, `fetch` with cache |
| Client Component | `'use client'` | hooks, events, browser APIs              |

| Rule              | Detail                                           |
| ----------------- | ------------------------------------------------ |
| Pass data down    | Server → Client via serializable props           |
| Import direction  | Client can import Client; Server can import both |
| No server secrets | Never pass secrets as Client props               |

**Server-only APIs:** `fs`, DB clients, private env vars, `cookies()`, `headers()`.

## 💡 Examples [#-examples]

**Async Server Component:**

```tsx
async function Users() {
  const res = await fetch("https://api.example.com/users", {
    next: { revalidate: 60 },
  });
  const users = await res.json();
  return <ul>{users.map((u: { id: string; name: string }) => (
    <li key={u.id}>{u.name}</li>
  ))}</ul>;
}
```

**Client boundary:**

```tsx
"use client";

import { useState } from "react";

export function Counter() {
  const [n, setN] = useState(0);
  return <button onClick={() => setN(n + 1)}>{n}</button>;
}
```

**Compose both:**

```tsx
// app/page.tsx (Server)
import { Counter } from "./Counter";

export default function Page() {
  return (
    <main>
      <h1>Dashboard</h1>
      <Counter />
    </main>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Putting `'use client'` at the top of a large tree ships more JS than needed — push the boundary down.
* Non-serializable props (functions, class instances) cannot cross the server→client boundary.
* `useEffect` / `onClick` in a Server Component is a build error.

## 🔗 Related [#-related]

* [app\_router.md](/docs/nextjs/app-router)
* [caching.md](/docs/nextjs/caching)
* [env.md](/docs/nextjs/env)
* [route\_handlers.md](/docs/nextjs/route-handlers)


# Backups & Restore (/docs/postgres/backups-restore)



# Backups & Restore [#backups--restore]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Backups are only real if restores are rehearsed. Use logical dumps for portability and physical/base backups for large clusters and PITR with WAL archiving.

## 🔧 Core concepts [#-core-concepts]

| Method          | Tooling                   | Notes                           |
| --------------- | ------------------------- | ------------------------------- |
| Logical         | `pg_dump`, `pg_dumpall`   | Flexible, slower for huge DBs   |
| Logical restore | `psql`, `pg_restore`      | Custom format supports parallel |
| Physical        | `pg_basebackup`           | Cluster-level                   |
| PITR            | Base backup + WAL archive | Restore to timestamp            |

| Format    | Flag                    |
| --------- | ----------------------- |
| Plain SQL | `pg_dump` default       |
| Custom    | `-Fc` for `pg_restore`  |
| Directory | `-Fd` parallel friendly |

## 💡 Examples [#-examples]

**Dump one database:**

```shellscript
pg_dump -Fc -f app.dump "$DATABASE_URL"
```

**Restore custom format:**

```shellscript
pg_restore --clean --if-exists -d "$DATABASE_URL" app.dump
```

**SQL dump:**

```shellscript
pg_dump "$DATABASE_URL" > app.sql
psql "$DATABASE_URL" -f app.sql
```

## ⚠️ Pitfalls [#️-pitfalls]

* Untested backups fail when you need them — schedule restore drills.
* Dumping a live DB without awareness of long transactions can capture inconsistent app-level state (DB is consistent; apps may need quiesce).
* Restoring over production without a rename/canary is a career-limiting move.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/postgres/getting-started)
* [connect\_psql.md](/docs/postgres/connect-psql)
* [migrations\_ops.md](/docs/postgres/migrations-ops)
* [connection\_pooling.md](/docs/postgres/connection-pooling)


# Connect with psql (/docs/postgres/connect-psql)



# Connect with psql [#connect-with-psql]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`psql` is the primary admin CLI: run SQL, inspect catalogs with meta-commands, and script automation with variables and `\copy`.

## 🔧 Core concepts [#-core-concepts]

| Connection form | Example                                |
| --------------- | -------------------------------------- |
| URL             | `postgres://user:pass@host:5432/db`    |
| Flags           | `psql -h host -U user -d db`           |
| `.pgpass`       | Password file for non-interactive auth |
| `PG*` env       | `PGHOST`, `PGUSER`, `PGDATABASE`       |

| Meta-command | Purpose                 |
| ------------ | ----------------------- |
| `\l`         | List databases          |
| `\c db`      | Connect to db           |
| `\dt`        | List tables             |
| `\d table`   | Describe table          |
| `\du`        | List roles              |
| `\x`         | Expanded display toggle |
| `\timing`    | Show query time         |
| `\q`         | Quit                    |

## 💡 Examples [#-examples]

**Connect and list tables:**

```shellscript
psql -h 127.0.0.1 -U app -d app
```

```
\dt
\d users
```

**Run file / one-shot:**

```shellscript
psql "$DATABASE_URL" -f migrate.sql
psql "$DATABASE_URL" -c "SELECT now();"
```

**CSV copy out:**

```
\copy (SELECT id, email FROM users) TO 'users.csv' CSV HEADER
```

## ⚠️ Pitfalls [#️-pitfalls]

* Passwords on the command line leak via process lists — prefer `.pgpass` or env URL carefully.
* `\d` shows one schema search\_path view — check `\dn` / qualify schema names.
* Interactive transactions left open (`BEGIN` without `COMMIT`) block others.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/postgres/getting-started)
* [roles\_privileges.md](/docs/postgres/roles-privileges)
* [explain\_analyze.md](/docs/postgres/explain-analyze)
* [backups\_restore.md](/docs/postgres/backups-restore)


# Connection Pooling (/docs/postgres/connection-pooling)



# Connection Pooling [#connection-pooling]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Each Postgres connection is expensive (memory, process). Poolers like PgBouncer multiplex many client connections onto fewer server connections — essential for serverless and high-churn apps.

## 🔧 Core concepts [#-core-concepts]

| Mode (PgBouncer) | Behavior                                    |
| ---------------- | ------------------------------------------- |
| Session          | One server conn per client session          |
| Transaction      | Return conn after each transaction (common) |
| Statement        | Extreme multiplexing; breaks many features  |

| Concept             | Detail                           |
| ------------------- | -------------------------------- |
| `max_connections`   | Server hard limit                |
| Pool size           | App + pooler sizing              |
| Idle timeouts       | Reap abandoned clients           |
| Prepared statements | Need care in transaction pooling |

## 💡 Examples [#-examples]

**Check connections:**

```sql
SELECT count(*), state FROM pg_stat_activity GROUP BY state;
SHOW max_connections;
```

**Terminate idle (careful):**

```sql
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE state = 'idle in transaction'
  AND state_change < now() - interval '10 minutes';
```

**App URL via pooler (sketch):**

```
postgres://user:pass@pgbouncer-host:6432/app
```

## ⚠️ Pitfalls [#️-pitfalls]

* Opening a new DB connection per serverless invoke without a pooler exhausts `max_connections`.
* Session-level features (temp tables, advisory locks, prepared statements) break under transaction pooling.
* Pooler + ORM defaults can still stampede — size pools per instance deliberately.

## 🔗 Related [#-related]

* [roles\_privileges.md](/docs/postgres/roles-privileges)
* [vacuum\_analyze.md](/docs/postgres/vacuum-analyze)
* [getting\_started.md](/docs/postgres/getting-started)
* [connect\_psql.md](/docs/postgres/connect-psql)


# EXPLAIN & ANALYZE (/docs/postgres/explain-analyze)



# EXPLAIN & ANALYZE [#explain--analyze]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`EXPLAIN` shows the planner’s chosen plan; `EXPLAIN ANALYZE` executes the query and adds actual timings/rows. Essential for diagnosing slow queries and verifying indexes.

## 🔧 Core concepts [#-core-concepts]

| Option     | Adds                            |
| ---------- | ------------------------------- |
| `ANALYZE`  | Actual runtime stats            |
| `BUFFERS`  | Shared/hit/read buffer counts   |
| `VERBOSE`  | Extra detail                    |
| `WAL`      | WAL generation (newer versions) |
| `SETTINGS` | Relevant GUCs                   |

| Node tip                   | Meaning            |
| -------------------------- | ------------------ |
| Seq Scan                   | Full table read    |
| Index Scan / Only          | Using index        |
| Nested Loop / Hash / Merge | Join strategies    |
| rows vs actual rows        | Estimator accuracy |

## 💡 Examples [#-examples]

**Basic:**

```sql
EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 42;
```

**With buffers:**

```sql
EXPLAIN (ANALYZE, BUFFERS)
SELECT o.*
FROM orders o
JOIN users u ON u.id = o.user_id
WHERE u.email = 'ada@example.com';
```

**Compare plans:**

```sql
SET enable_seqscan = off; -- diagnostic only
EXPLAIN ANALYZE SELECT ...;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `EXPLAIN ANALYZE` runs the query — careful with writes (use a transaction + `ROLLBACK` when testing DML).
* Stale statistics → bad plans — `ANALYZE` the tables.
* Reading plans takes practice — start with the most expensive node (time).

## 🔗 Related [#-related]

* [indexes.md](/docs/postgres/indexes)
* [vacuum\_analyze.md](/docs/postgres/vacuum-analyze)
* [connect\_psql.md](/docs/postgres/connect-psql)
* [json\_jsonb.md](/docs/postgres/json-jsonb)


# Extensions (/docs/postgres/extensions)



# Extensions [#extensions]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Extensions add types, functions, and index methods packaged with Postgres or from contrib/third parties. Enable per database with `CREATE EXTENSION`.

## 🔧 Core concepts [#-core-concepts]

| Extension                    | Common use                     |
| ---------------------------- | ------------------------------ |
| `pgcrypto`                   | Crypto helpers                 |
| `uuid-ossp` / `pgcrypto` gen | UUID generation                |
| `pg_trgm`                    | Trigram fuzzy search / indexes |
| `citext`                     | Case-insensitive text          |
| `btree_gin` / `btree_gist`   | Combined index support         |
| `postgres_fdw`               | Foreign data wrapper           |
| `vector` (pgvector)          | Embeddings (external)          |

| Command                   | Role                       |
| ------------------------- | -------------------------- |
| `CREATE EXTENSION`        | Install in current DB      |
| `DROP EXTENSION`          | Remove                     |
| `\dx`                     | List installed             |
| `pg_available_extensions` | What’s available on server |

## 💡 Examples [#-examples]

**Enable trigram:**

```sql
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX users_name_trgm ON users USING GIN (name gin_trgm_ops);
```

**List:**

```
\dx
```

```sql
SELECT * FROM pg_available_extensions ORDER BY name;
```

**UUID:**

```sql
CREATE EXTENSION IF NOT EXISTS pgcrypto;
SELECT gen_random_uuid();
```

## ⚠️ Pitfalls [#️-pitfalls]

* Extension availability differs on managed hosts — check provider allowlists.
* Dump/restore may require extensions created before data load.
* Superuser is often required to create extensions.

## 🔗 Related [#-related]

* [indexes.md](/docs/postgres/indexes)
* [json\_jsonb.md](/docs/postgres/json-jsonb)
* [roles\_privileges.md](/docs/postgres/roles-privileges)
* [getting\_started.md](/docs/postgres/getting-started)


# Getting Started with Postgres Ops (/docs/postgres/getting-started)



# Getting Started with Postgres Ops [#getting-started-with-postgres-ops]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

PostgreSQL is a relational database used as a system of record. This folder focuses on operations and administration: connections, roles, indexes, vacuum, explain, backups, pooling, and JSONB — not basic SELECT tutorials.

## 🔧 Core concepts [#-core-concepts]

| Idea      | Meaning                                     |
| --------- | ------------------------------------------- |
| Cluster   | A Postgres data directory + running server  |
| Database  | Named DB inside a cluster                   |
| Role      | User/group identity for authz               |
| WAL       | Write-ahead log for durability/replication  |
| Extension | Packaged server plugin (`CREATE EXTENSION`) |

| Tool                     | Purpose                         |
| ------------------------ | ------------------------------- |
| `psql`                   | Interactive SQL + meta-commands |
| `pg_dump` / `pg_restore` | Logical backup/restore          |
| `pg_basebackup`          | Physical base backup            |
| Connection pooler        | PgBouncer / cloud poolers       |

## 💡 Examples [#-examples]

**Run Postgres (Docker):**

```shellscript
docker run --rm -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16
```

**Connect:**

```shellscript
psql "postgres://postgres:postgres@127.0.0.1:5432/postgres"
```

**Version + basics:**

```sql
SELECT version();
SELECT current_database(), current_user;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Exposing `5432` publicly without TLS/auth hardening is dangerous.
* Superuser for app runtimes violates least privilege.
* Skipping backups until first incident is not a strategy.

## 🔗 Related [#-related]

* [connect\_psql.md](/docs/postgres/connect-psql)
* [roles\_privileges.md](/docs/postgres/roles-privileges)
* [backups\_restore.md](/docs/postgres/backups-restore)
* [glossary.md](/docs/postgres/glossary)


# Glossary (/docs/postgres/glossary)



# Glossary [#glossary]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of PostgreSQL operations and administration terms.

## 🔧 Core concepts [#-core-concepts]

| Term             | Definition                                               |
| ---------------- | -------------------------------------------------------- |
| Autovacuum       | Background process that vacuums and analyzes tables.     |
| Bloat            | Excess space from dead tuples / index waste.             |
| Checkpoint       | Flush dirty buffers and advance WAL recovery point.      |
| Concurrent index | Index build that avoids long write locks.                |
| Extension        | Packaged set of DB objects installed per database.       |
| Hot standby      | Replica open for read-only queries.                      |
| MVCC             | Multi-version concurrency control for readers/writers.   |
| PITR             | Point-in-time recovery using base backup + WAL.          |
| Pooler           | Middleware multiplexing client connections.              |
| Role             | Auth identity that can own objects and hold privileges.  |
| TOAST            | Out-of-line storage for large field values.              |
| Vacuum           | Cleanup of dead row versions for reuse.                  |
| WAL              | Write-ahead log guaranteeing durability and replication. |
| Wraparound       | Transaction ID exhaustion risk mitigated by freezing.    |

## 💡 Examples [#-examples]

**Activity snapshot:**

```sql
SELECT pid, usename, state, query_start, left(query, 80)
FROM pg_stat_activity
WHERE state <> 'idle';
```

**Extension list:**

```
\dx
```

## ⚠️ Pitfalls [#️-pitfalls]

* Glossaries compress nuance — always confirm behavior for your major version (14/15/16/17).
* Managed Postgres may rename or restrict low-level ops (superuser, FS access).

## 🔗 Related [#-related]

* [getting\_started.md](/docs/postgres/getting-started)
* [vacuum\_analyze.md](/docs/postgres/vacuum-analyze)
* [backups\_restore.md](/docs/postgres/backups-restore)
* [README.md](/docs/postgres)


# Postgres (/docs/postgres)



# Postgres [#postgres]

Ops, indexes, backups, EXPLAIN.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Indexes (/docs/postgres/indexes)



# Indexes [#indexes]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Indexes speed lookups and enforce uniqueness at the cost of write overhead and storage. Choose type based on query patterns (equality, range, JSON, text search).

## 🔧 Core concepts [#-core-concepts]

| Type             | Good for                                |
| ---------------- | --------------------------------------- |
| B-tree (default) | `=`, `&lt;`, `>`, `BETWEEN`, `ORDER BY` |
| Hash             | Equality only (less common)             |
| GIN              | JSONB, arrays, full-text                |
| GiST             | Geometry, ranges, some text             |
| BRIN             | Very large append-only time series      |

| Command                     | Role                |
| --------------------------- | ------------------- |
| `CREATE INDEX`              | Add index           |
| `CREATE UNIQUE INDEX`       | Uniqueness          |
| `CREATE INDEX CONCURRENTLY` | Online create (ops) |
| `DROP INDEX`                | Remove              |
| `REINDEX`                   | Rebuild             |

## 💡 Examples [#-examples]

**B-tree + partial:**

```sql
CREATE INDEX CONCURRENTLY users_email_lower_idx
  ON users (lower(email));

CREATE INDEX CONCURRENTLY orders_open_idx
  ON orders (created_at)
  WHERE status = 'open';
```

**JSONB GIN:**

```sql
CREATE INDEX CONCURRENTLY events_payload_gin
  ON events USING GIN (payload jsonb_path_ops);
```

**Find unused-ish indexes (heuristic):**

```sql
SELECT * FROM pg_stat_user_indexes ORDER BY idx_scan NULLS FIRST LIMIT 20;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Over-indexing slows writes and bloats storage.
* Non-concurrent index builds lock writes — use `CONCURRENTLY` in prod (with caveats).
* Function indexes only help when queries use the same expression.

## 🔗 Related [#-related]

* [explain\_analyze.md](/docs/postgres/explain-analyze)
* [vacuum\_analyze.md](/docs/postgres/vacuum-analyze)
* [json\_jsonb.md](/docs/postgres/json-jsonb)
* [migrations\_ops.md](/docs/postgres/migrations-ops)


# JSON & JSONB (/docs/postgres/json-jsonb)



# JSON & JSONB [#json--jsonb]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`json` stores text as-is; `jsonb` stores a binary decomposed form — better for indexing and containment queries. Prefer `jsonb` for operational query patterns.

## 🔧 Core concepts [#-core-concepts]

| Type    | Trait                                      |
| ------- | ------------------------------------------ |
| `json`  | Preserves whitespace/key order; reparsed   |
| `jsonb` | Dedupes keys; indexable; usually preferred |

| Operator / fn | Role                           |            |
| ------------- | ------------------------------ | ---------- |
| `->` / `->>`  | Get object field (json / text) |            |
| `#>` / `#>>`  | Path extract                   |            |
| `@>`          | Contains                       |            |
| `?` / \`?     | `/`?&\`                        | Key exists |
| `jsonb_set`   | Modify                         |            |
| GIN index     | Accelerate `@>` / path ops     |            |

## 💡 Examples [#-examples]

**Query fields:**

```sql
SELECT payload->>'event'
FROM events
WHERE payload @> '{"type":"signup"}';
```

**GIN index:**

```sql
CREATE INDEX CONCURRENTLY events_payload_gin
  ON events USING GIN (payload jsonb_path_ops);
```

**Update key:**

```sql
UPDATE users
SET prefs = jsonb_set(prefs, '{theme}', '"dark"', true)
WHERE id = 42;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Unindexed `payload->>'x' =` on large tables seq-scans — express as jsonb ops + GIN when possible.
* Turning everything into JSONB abandons relational constraints — hybrid carefully.
* `json` vs `jsonb` equality and duplicate-key behavior differ.

## 🔗 Related [#-related]

* [indexes.md](/docs/postgres/indexes)
* [explain\_analyze.md](/docs/postgres/explain-analyze)
* [extensions.md](/docs/postgres/extensions)
* [migrations\_ops.md](/docs/postgres/migrations-ops)


# Migrations Ops (/docs/postgres/migrations-ops)



# Migrations Ops [#migrations-ops]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Schema changes in production need expand/contract discipline, lock awareness, and backwards-compatible deploys. Tooling (Flyway, Liquibase, Prisma, Alembic, golang-migrate) applies SQL — ops principles stay the same.

## 🔧 Core concepts [#-core-concepts]

| Practice                        | Why                          |
| ------------------------------- | ---------------------------- |
| Expand/contract                 | Avoid dual-write downtime    |
| Backwards compatible migrations | Old app + new schema coexist |
| Short transactions              | Reduce lock duration         |
| `CONCURRENTLY` indexes          | Avoid long write locks       |
| Migration history table         | Idempotent applies           |

| Risky DDL                   | Safer approach                     |
| --------------------------- | ---------------------------------- |
| Rewrite huge table in place | Add column → backfill → switch     |
| `ALTER TYPE` recreates      | Add new column/type carefully      |
| Long `ALTER TABLE` locks    | Check `pg_locks` / schedule window |

## 💡 Examples [#-examples]

**Add nullable column (safe):**

```sql
ALTER TABLE users ADD COLUMN locale text;
```

**Backfill in batches (app job):**

```sql
UPDATE users SET locale = 'en' WHERE locale IS NULL AND id IN (
  SELECT id FROM users WHERE locale IS NULL ORDER BY id LIMIT 1000
);
```

**Online index:**

```sql
CREATE INDEX CONCURRENTLY users_locale_idx ON users (locale);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Running `CREATE INDEX` without `CONCURRENTLY` on large tables locks writes.
* Multi-statement migrations without transactions (or with ones that can't run in a txn, like concurrent index) need clear tool support.
* Ignoring failed mid-migration state leaves environments drifted.

## 🔗 Related [#-related]

* [indexes.md](/docs/postgres/indexes)
* [roles\_privileges.md](/docs/postgres/roles-privileges)
* [backups\_restore.md](/docs/postgres/backups-restore)
* [explain\_analyze.md](/docs/postgres/explain-analyze)


# Roles & Privileges (/docs/postgres/roles-privileges)



# Roles & Privileges [#roles--privileges]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Postgres uses roles for authentication and authorization. Prefer least privilege: separate owner, migrator, and runtime app roles.

## 🔧 Core concepts [#-core-concepts]

| Concept            | Meaning                     |
| ------------------ | --------------------------- |
| LOGIN role         | Can connect (user)          |
| NOLOGIN role       | Group / ownership bucket    |
| GRANT / REVOKE     | Privilege changes           |
| `SEARCH_PATH`      | Schema resolution order     |
| Row Level Security | Per-row policies (advanced) |

| Privilege                      | Typical on tables     |
| ------------------------------ | --------------------- |
| `SELECT`                       | Read                  |
| `INSERT` / `UPDATE` / `DELETE` | Write                 |
| `TRUNCATE`                     | Fast empty            |
| `REFERENCES`                   | FK creation           |
| `USAGE` on schema              | See objects in schema |

## 💡 Examples [#-examples]

**Create app role:**

```sql
CREATE ROLE app_login LOGIN PASSWORD 'change-me';
CREATE ROLE app_owner NOLOGIN;
GRANT app_owner TO migrator; -- migrator assumes ownership duties
```

**Grants:**

```sql
GRANT USAGE ON SCHEMA public TO app_login;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO app_login;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_login;
```

**Inspect:**

```
\du
```

```sql
SELECT * FROM information_schema.role_table_grants WHERE grantee = 'app_login';
```

## ⚠️ Pitfalls [#️-pitfalls]

* Objects created by superuser may not grant to app roles unless `ALTER DEFAULT PRIVILEGES` is set.
* Public schema open grants are a common over-exposure.
* Rotating passwords in URLs requires updating all poolers/clients.

## 🔗 Related [#-related]

* [connect\_psql.md](/docs/postgres/connect-psql)
* [migrations\_ops.md](/docs/postgres/migrations-ops)
* [connection\_pooling.md](/docs/postgres/connection-pooling)
* [getting\_started.md](/docs/postgres/getting-started)


# VACUUM & ANALYZE (/docs/postgres/vacuum-analyze)



# VACUUM & ANALYZE [#vacuum--analyze]

*Postgres · Reference cheat sheet*

***

## 📋 Overview [#-overview]

MVCC leaves dead row versions. `VACUUM` reclaims space for reuse; `ANALYZE` updates planner statistics. Autovacuum handles most cases — watch bloat and freeze age.

## 🔧 Core concepts [#-core-concepts]

| Command                     | Role                           |
| --------------------------- | ------------------------------ |
| `VACUUM`                    | Cleanup dead tuples            |
| `VACUUM (VERBOSE, ANALYZE)` | Cleanup + stats                |
| `VACUUM FULL`               | Rewrite table (exclusive lock) |
| `ANALYZE`                   | Refresh stats only             |
| Autovacuum                  | Background workers             |

| Monitor             | View                             |
| ------------------- | -------------------------------- |
| Dead tuples         | `pg_stat_user_tables`            |
| Autovacuum activity | logs / `pg_stat_progress_vacuum` |
| Wraparound risk     | `age(datfrozenxid)`              |

## 💡 Examples [#-examples]

**Targeted maintenance:**

```sql
VACUUM (ANALYZE) orders;
```

**Check bloat signals:**

```sql
SELECT relname, n_live_tup, n_dead_tup, last_autovacuum
FROM pg_stat_user_tables
ORDER BY n_dead_tup DESC
LIMIT 20;
```

**Aggressive rewrite (maintenance window):**

```sql
VACUUM FULL orders; -- locks heavily; prefer wisely
```

## ⚠️ Pitfalls [#️-pitfalls]

* `VACUUM FULL` is not routine — it locks and needs disk headroom.
* Disabling autovacuum “for performance” causes wraparound emergencies.
* Long transactions delay vacuum — find idle-in-transaction sessions.

## 🔗 Related [#-related]

* [explain\_analyze.md](/docs/postgres/explain-analyze)
* [indexes.md](/docs/postgres/indexes)
* [connection\_pooling.md](/docs/postgres/connection-pooling)
* [getting\_started.md](/docs/postgres/getting-started)


# Environment & Config (/docs/node/env-config)



# Environment & Config [#environment--config]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Configure Node apps with environment variables, optionally loaded from `.env` files via `dotenv` or platform secrets. Validate required keys at startup.

## 🔧 Core concepts [#-core-concepts]

| Source          | Use                                    |
| --------------- | -------------------------------------- |
| `process.env`   | Primary config bag                     |
| `.env` + dotenv | Local development                      |
| Host secrets    | Production (Vercel, Docker, K8s, etc.) |
| `NODE_ENV`      | `development` / `production` / `test`  |

| Practice            | Why                               |
| ------------------- | --------------------------------- |
| Fail fast           | Crash if required vars missing    |
| No secrets in repo  | Use `.env.example` templates only |
| Typed config module | Single parse point                |

## 💡 Examples [#-examples]

**Fail-fast config:**

```js
function required(name) {
  const v = process.env[name];
  if (!v) throw new Error(`Missing env: ${name}`);
  return v;
}

export const config = {
  port: Number(process.env.PORT || 9000),
  databaseUrl: required("DATABASE_URL"),
};
```

**dotenv (dev):**

```js
import "dotenv/config";
```

**`.env.example`:**

```shellscript
PORT=9000
DATABASE_URL=postgres://user:pass@localhost:5432/app
```

## ⚠️ Pitfalls [#️-pitfalls]

* `process.env` values are strings — `PORT` needs `Number(...)`.
* Loading `.env` in production can accidentally override platform secrets if misordered.
* Never log raw env objects — they often contain credentials.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/node/getting-started)
* [error\_handling.md](/docs/node/error-handling)
* [packaging.md](/docs/node/packaging)
* [Next.js/env.md](/docs/node/../next.js/env)


# Error Handling (/docs/node/error-handling)



# Error Handling [#error-handling]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Robust Node services distinguish operational errors (expected failures) from programmer bugs, return safe HTTP responses, and log details server-side.

## 🔧 Core concepts [#-core-concepts]

| Layer           | Approach                                                 |
| --------------- | -------------------------------------------------------- |
| Sync throw      | Caught by try/catch or framework                         |
| Async rejection | Must be handled or process warns/crashes                 |
| HTTP mapping    | Map errors → status codes                                |
| Process hooks   | `uncaughtException` / `unhandledRejection` (last resort) |

| Status    | Typical meaning           |
| --------- | ------------------------- |
| 400       | Bad input                 |
| 401 / 403 | Auth / forbidden          |
| 404       | Missing resource          |
| 409       | Conflict                  |
| 500       | Unexpected server failure |

## 💡 Examples [#-examples]

**Express async wrapper:**

```js
const wrap = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get("/user/:id", wrap(async (req, res) => {
  const user = await db.find(req.params.id);
  if (!user) {
    const err = new Error("Not found");
    err.status = 404;
    throw err;
  }
  res.json(user);
}));
```

**Central error middleware:**

```js
app.use((err, req, res, next) => {
  const status = err.status || 500;
  if (status >= 500) console.error(err);
  res.status(status).json({
    error: status >= 500 ? "Internal error" : err.message,
  });
});
```

**Fastify setErrorHandler:**

```js
fastify.setErrorHandler((err, req, reply) => {
  reply.status(err.statusCode || 500).send({ error: err.message });
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Leaking stack traces to clients exposes internals.
* Swallowing errors (`catch (e) \{\}`) hides outages.
* `uncaughtException` handlers that continue serving are unsafe — shut down and restart.

## 🔗 Related [#-related]

* [express\_middleware.md](/docs/node/express-middleware)
* [fastify\_basics.md](/docs/node/fastify-basics)
* [http\_server.md](/docs/node/http-server)
* [env\_config.md](/docs/node/env-config)


# Express Basics (/docs/node/express-basics)



# Express Basics [#express-basics]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Express is a minimal Node HTTP framework: an app, middleware stack, and route handlers. Widely used and flexible; you wire most pieces yourself.

## 🔧 Core concepts [#-core-concepts]

| API                | Role                                 |
| ------------------ | ------------------------------------ |
| `express()`        | Create app                           |
| `app.get/post/...` | Register route + method              |
| `app.use`          | Mount middleware or sub-app          |
| `req` / `res`      | Incoming request / outgoing response |
| `next`             | Pass control to next middleware      |

| `res` helper   | Effect                      |
| -------------- | --------------------------- |
| `res.send`     | Send string/Buffer/object   |
| `res.json`     | JSON + content-type         |
| `res.status`   | Set status code (chainable) |
| `res.redirect` | 3xx redirect                |

## 💡 Examples [#-examples]

**Minimal app:**

```js
import express from "express";

const app = express();
app.get("/", (req, res) => res.json({ ok: true }));
app.listen(9000);
```

**JSON body parsing:**

```js
app.use(express.json());

app.post("/users", (req, res) => {
  res.status(201).json(req.body);
});
```

**404 fallback:**

```js
app.use((req, res) => {
  res.status(404).json({ error: "Not found" });
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `express.json()` leaves `req.body` undefined for JSON POSTs.
* Error-handling middleware must have 4 args `(err, req, res, next)` or Express skips it.
* Listening on a port already in use crashes at startup — check availability (9000+).

## 🔗 Related [#-related]

* [express\_middleware.md](/docs/node/express-middleware)
* [express\_routing.md](/docs/node/express-routing)
* [error\_handling.md](/docs/node/error-handling)
* [Comparisons/express\_vs\_fastify.md](/docs/node/../comparisons/express-vs-fastify)


# Express Middleware (/docs/node/express-middleware)



# Express Middleware [#express-middleware]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Middleware functions run in order on a request. Each can read/modify `req`/`res`, end the response, or call `next()`. Most Express power comes from composing middleware.

## 🔧 Core concepts [#-core-concepts]

| Signature               | Role                                |
| ----------------------- | ----------------------------------- |
| `(req, res, next)`      | Normal middleware                   |
| `(err, req, res, next)` | Error middleware (must be 4 params) |
| `app.use(fn)`           | All methods / paths (or mount path) |
| `app.use('/api', fn)`   | Only under `/api`                   |

| Built-in               | Purpose            |
| ---------------------- | ------------------ |
| `express.json()`       | Parse JSON bodies  |
| `express.urlencoded()` | Parse form bodies  |
| `express.static(dir)`  | Serve static files |
| `express.Router()`     | Modular mini-app   |

## 💡 Examples [#-examples]

**Logger middleware:**

```js
function logger(req, res, next) {
  console.log(req.method, req.url);
  next();
}
app.use(logger);
```

**Auth gate:**

```js
function requireAuth(req, res, next) {
  if (!req.headers.authorization) {
    return res.status(401).json({ error: "Unauthorized" });
  }
  next();
}
app.get("/private", requireAuth, (req, res) => res.send("ok"));
```

**Error middleware (last):**

```js
app.use((err, req, res, next) => {
  console.error(err);
  res.status(err.status || 500).json({ error: err.message });
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Calling `next()` after `res.send` can throw "Cannot set headers after they are sent".
* Order matters: parsers before handlers; error middleware after routes.
* Async errors need `try/catch` + `next(err)` or a wrapper — Express 4 does not catch rejected promises by default (Express 5 improves this).

## 🔗 Related [#-related]

* [express\_basics.md](/docs/node/express-basics)
* [express\_routing.md](/docs/node/express-routing)
* [error\_handling.md](/docs/node/error-handling)
* [fastify\_plugins.md](/docs/node/fastify-plugins)


# Express Routing (/docs/node/express-routing)



# Express Routing [#express-routing]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Express matches HTTP method + path patterns to handlers. Use `Router` to split large apps into mountable modules.

## 🔧 Core concepts [#-core-concepts]

| Pattern              | Matches                             |
| -------------------- | ----------------------------------- |
| `/users`             | Exact path                          |
| `/users/:id`         | Param `req.params.id`               |
| `/files/*`           | Wildcard (version-dependent syntax) |
| `/` + `Router` mount | Prefixed paths                      |

| API                             | Role                       |
| ------------------------------- | -------------------------- |
| `app.METHOD(path, ...handlers)` | Method-specific            |
| `app.all`                       | Any method                 |
| `router.route(path)`            | Chain verbs for one path   |
| `req.params` / `req.query`      | Path params / query string |

## 💡 Examples [#-examples]

**Params and query:**

```js
app.get("/users/:id", (req, res) => {
  res.json({ id: req.params.id, q: req.query.q });
});
// GET /users/42?q=active
```

**Router module:**

```js
import { Router } from "express";

const users = Router();
users.get("/", (req, res) => res.json([]));
users.get("/:id", (req, res) => res.json({ id: req.params.id }));

app.use("/users", users);
```

**Route chaining:**

```js
router
  .route("/items/:id")
  .get((req, res) => res.send("get"))
  .put((req, res) => res.send("put"))
  .delete((req, res) => res.send("delete"));
```

## ⚠️ Pitfalls [#️-pitfalls]

* More specific routes must be registered before generic `/:id` catchers.
* `req.params` values are strings — coerce IDs explicitly.
* Trailing-slash behavior depends on settings; be consistent in clients and routes.

## 🔗 Related [#-related]

* [express\_basics.md](/docs/node/express-basics)
* [express\_middleware.md](/docs/node/express-middleware)
* [fastify\_basics.md](/docs/node/fastify-basics)
* [http\_server.md](/docs/node/http-server)


# Fastify Basics (/docs/node/fastify-basics)



# Fastify Basics [#fastify-basics]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Fastify is a high-performance Node web framework focused on schemas, plugins, and low overhead. Validation and serialization are first-class via JSON Schema.

## 🔧 Core concepts [#-core-concepts]

| API                      | Role                                  |
| ------------------------ | ------------------------------------- |
| `Fastify()`              | Create instance                       |
| `fastify.route` / `.get` | Register routes                       |
| `schema`                 | Validate request + serialize response |
| `reply`                  | Response object (`send`, `code`)      |
| `listen`                 | Bind host/port                        |

| Hook (examples) | When                |
| --------------- | ------------------- |
| `onRequest`     | Early request       |
| `preHandler`    | Before handler      |
| `onSend`        | Before payload sent |
| `onError`       | Error path          |

## 💡 Examples [#-examples]

**Minimal server:**

```js
import Fastify from "fastify";

const app = Fastify({ logger: true });
app.get("/", async () => ({ ok: true }));
await app.listen({ port: 9000, host: "0.0.0.0" });
```

**Schema validation:**

```js
app.post(
  "/users",
  {
    schema: {
      body: {
        type: "object",
        required: ["email"],
        properties: { email: { type: "string", format: "email" } },
      },
    },
  },
  async (req, reply) => {
    reply.code(201);
    return req.body;
  },
);
```

**Async handler errors:**

```js
app.get("/boom", async () => {
  throw Object.assign(new Error("nope"), { statusCode: 400 });
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Prefer `async` handlers or call `reply.send` — don't mix both carelessly.
* Validation errors return 400 by default; customize with `setErrorHandler`.
* Plugin encapsulation means decorations are not always global — register shared plugins at the right scope.

## 🔗 Related [#-related]

* [fastify\_plugins.md](/docs/node/fastify-plugins)
* [express\_basics.md](/docs/node/express-basics)
* [error\_handling.md](/docs/node/error-handling)
* [Comparisons/express\_vs\_fastify.md](/docs/node/../comparisons/express-vs-fastify)


# Fastify Plugins (/docs/node/fastify-plugins)



# Fastify Plugins [#fastify-plugins]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Fastify organizes features as plugins. Each plugin gets an encapsulated context (decorators, hooks, routes) unless you break encapsulation deliberately.

## 🔧 Core concepts [#-core-concepts]

| API                              | Role                          |
| -------------------------------- | ----------------------------- |
| `fastify.register(plugin, opts)` | Load plugin                   |
| `fp` (`fastify-plugin`)          | Share decorations with parent |
| `decorate` / `decorateRequest`   | Attach utilities              |
| `prefix` option                  | Mount routes under a path     |

| Pattern                  | Use when                                 |
| ------------------------ | ---------------------------------------- |
| Encapsulated plugin      | Isolate routes/hooks per feature         |
| `fastify-plugin` wrapper | Share DB client, auth, config            |
| Nested `register`        | Create contexts (e.g. `/v1` vs `/admin`) |

## 💡 Examples [#-examples]

**Feature plugin:**

```js
async function usersPlugin(fastify, opts) {
  fastify.get("/", async () => []);
}
await fastify.register(usersPlugin, { prefix: "/users" });
```

**Shared decoration with `fp`:**

```js
import fp from "fastify-plugin";

async function dbPlugin(fastify) {
  fastify.decorate("db", { query: async () => [] });
}
export default fp(dbPlugin);
```

**Nested context:**

```js
await fastify.register(async (scope) => {
  scope.addHook("preHandler", async (req) => {
    /* admin-only */
  });
  scope.get("/stats", async () => ({ ok: true }));
}, { prefix: "/admin" });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `fastify-plugin` means parent routes cannot see `fastify.db`.
* Circular plugin dependencies are hard to debug — keep a clear register order.
* Registering the same plugin twice can duplicate routes/hooks.

## 🔗 Related [#-related]

* [fastify\_basics.md](/docs/node/fastify-basics)
* [express\_middleware.md](/docs/node/express-middleware)
* [env\_config.md](/docs/node/env-config)
* [packaging.md](/docs/node/packaging)


# Getting Started with Node.js (/docs/node/getting-started)



# Getting Started with Node.js [#getting-started-with-nodejs]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node.js is a JavaScript runtime built on V8 for building servers, CLIs, and tooling outside the browser. Packages are managed with npm, pnpm, or yarn.

## 🔧 Core concepts [#-core-concepts]

| Idea       | Meaning                                              |
| ---------- | ---------------------------------------------------- |
| Runtime    | Executes JS with Node APIs (`fs`, `http`, `process`) |
| Module     | CommonJS (`require`) or ESM (`import`) unit          |
| npm        | Default package manager + registry client            |
| Event loop | Schedules async I/O callbacks                        |
| LTS        | Long-term support release line (prefer for prod)     |

**Check install:**

```shellscript
node --version
npm --version
```

| Command               | Purpose                            |
| --------------------- | ---------------------------------- |
| `node app.js`         | Run a script                       |
| `npm init -y`         | Create `package.json`              |
| `npm install express` | Add dependency                     |
| `node --watch app.js` | Restart on file changes (Node 18+) |

## 💡 Examples [#-examples]

**Hello server:**

```js
import http from "node:http";

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Hello Node\n");
});

server.listen(9000, () => console.log("http://localhost:9000"));
```

**`package.json` type module:**

```json
{
  "name": "demo",
  "type": "module",
  "scripts": { "start": "node index.js" }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing CJS and ESM without clear `"type"` / extensions causes cryptic import errors.
* Global `npm install -g` tools can conflict across projects — prefer local + `npx`.
* Blocking the event loop with heavy sync CPU work starves all requests.

## 🔗 Related [#-related]

* [http\_server.md](/docs/node/http-server)
* [express\_basics.md](/docs/node/express-basics)
* [env\_config.md](/docs/node/env-config)
* [packaging.md](/docs/node/packaging)
* [glossary.md](/docs/node/glossary)


# Glossary (/docs/node/glossary)



# Glossary [#glossary]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of Node.js runtime, modules, and server-framework terms.

## 🔧 Core concepts [#-core-concepts]

| Term             | Definition                                                   |
| ---------------- | ------------------------------------------------------------ |
| Buffer           | Fixed-size binary data type for bytes.                       |
| CJS              | CommonJS modules using `require` / `module.exports`.         |
| Event loop       | Core scheduler for timers, I/O, and microtasks.              |
| ESM              | ECMAScript modules using `import` / `export`.                |
| Express          | Minimal, unopinionated HTTP framework.                       |
| Fastify          | Schema-oriented, high-performance HTTP framework.            |
| libuv            | C library providing Node’s async I/O and threadpool.         |
| Middleware       | Function in a pipeline that can handle or forward a request. |
| npm              | Default package manager and registry client.                 |
| package.json     | Manifest for deps, scripts, and package metadata.            |
| Plugin (Fastify) | Encapsulated unit of routes, hooks, and decorations.         |
| semver           | Semantic versioning (`major.minor.patch`).                   |
| Stream           | Abstract interface for streaming data (readable/writable).   |
| Worker thread    | Separate V8 isolate for CPU-heavy work.                      |
| `node:` prefix   | Built-in module import specifier (`node:fs`).                |

## 💡 Examples [#-examples]

**Built-in import:**

```js
import fs from "node:fs/promises";
import { createServer } from "node:http";
```

**Detect ESM vs CJS mentally:**

```json
{ "type": "module" }
```

```js
// with "type": "module" → import works
// without → require is default unless .mjs
```

## ⚠️ Pitfalls [#️-pitfalls]

* “Node version” vs “framework version” — always note both when debugging.
* Global installs hide which binary your shell resolves — prefer local tooling.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/node/getting-started)
* [http\_server.md](/docs/node/http-server)
* [express\_basics.md](/docs/node/express-basics)
* [fastify\_basics.md](/docs/node/fastify-basics)
* [README.md](/docs/node)


# HTTP Server (node:http) (/docs/node/http-server)



# HTTP Server (node:http) [#http-server-nodehttp]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`node:http` (and `node:https`) provide low-level servers and clients. Frameworks like Express/Fastify wrap these primitives.

## 🔧 Core concepts [#-core-concepts]

| API                       | Role                     |
| ------------------------- | ------------------------ |
| `http.createServer`       | Create server            |
| `IncomingMessage` (`req`) | Request stream + headers |
| `ServerResponse` (`res`)  | Writable response        |
| `server.listen`           | Bind port/host           |
| `http.request` / `fetch`  | Outbound HTTP            |

| Header tip      | Detail                                |
| --------------- | ------------------------------------- |
| Set before body | Call `writeHead` or `setHeader` early |
| `Content-Type`  | Required for correct client parsing   |
| Keep-alive      | Default in modern Node                |

## 💡 Examples [#-examples]

**Plain text server:**

```js
import http from "node:http";

http
  .createServer((req, res) => {
    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ path: req.url }));
  })
  .listen(9000, "0.0.0.0");
```

**Read POST body:**

```js
async function readBody(req) {
  const chunks = [];
  for await (const c of req) chunks.push(c);
  return Buffer.concat(chunks).toString("utf8");
}
```

**Global fetch (Node 18+):**

```js
const res = await fetch("https://example.com");
const text = await res.text();
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting to `end()` the response leaves the client hanging.
* Unbounded body reads enable memory DoS — enforce size limits.
* `req.url` includes query string; parse with `URL` + host header carefully.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/node/getting-started)
* [express\_basics.md](/docs/node/express-basics)
* [fastify\_basics.md](/docs/node/fastify-basics)
* [error\_handling.md](/docs/node/error-handling)


# Node.js (/docs/node)



# Node.js [#nodejs]

Express, Fastify, HTTP servers.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Packaging (/docs/node/packaging)



# Packaging [#packaging]

*Node.js · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Node projects are defined by `package.json`: dependencies, scripts, entry points, and module format. Publish libraries to npm or run apps via scripts.

## 🔧 Core concepts [#-core-concepts]

| Field              | Purpose                    |
| ------------------ | -------------------------- |
| `name` / `version` | Package identity (semver)  |
| `type`             | `"module"` for ESM default |
| `main` / `exports` | Entry points               |
| `dependencies`     | Runtime deps               |
| `devDependencies`  | Build/test-only deps       |
| `scripts`          | `npm run` commands         |
| `engines`          | Supported Node versions    |

| Command        | Effect                |
| -------------- | --------------------- |
| `npm install`  | Install from lockfile |
| `npm ci`       | Clean CI install      |
| `npm outdated` | Check updates         |
| `npm pack`     | Dry-run tarball       |

## 💡 Examples [#-examples]

**Minimal library `exports`:**

```json
{
  "name": "@acme/utils",
  "version": "1.0.0",
  "type": "module",
  "exports": {
    ".": "./dist/index.js"
  },
  "files": ["dist"]
}
```

**Useful scripts:**

```json
{
  "scripts": {
    "dev": "node --watch src/index.js",
    "start": "node src/index.js",
    "test": "node --test"
  }
}
```

**Install exact tree in CI:**

```shellscript
npm ci
```

## ⚠️ Pitfalls [#️-pitfalls]

* Committing without a lockfile leads to non-reproducible installs.
* Publishing secrets or `.env` via bad `"files"` / missing `.npmignore` is catastrophic.
* Dual CJS/ESM packages need careful `exports` — test both consumers.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/node/getting-started)
* [env\_config.md](/docs/node/env-config)
* [glossary.md](/docs/node/glossary)
* [error\_handling.md](/docs/node/error-handling)


# Aliases Basics (/docs/powershell/aliases-basics)



# Aliases Basics [#aliases-basics]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Aliases** are short names for commands (`ls` → `Get-ChildItem`, `cd` → `Set-Location`). They help newcomers from Bash/cmd, but scripts should prefer full cmdlet names for clarity and portability.

## 🔧 Core concepts [#-core-concepts]

| Idea             | Detail                                     |
| ---------------- | ------------------------------------------ |
| Built-in aliases | Ship with PowerShell                       |
| Custom aliases   | `Set-Alias` / `New-Alias` for your session |
| Discovery        | `Get-Alias`, `Alias:` drive                |
| Good practice    | Use full names in `.ps1` files             |
| Gal              | Alias for `Get-Alias`                      |

Aliases do not support custom parameters the way functions do — use a function for anything non-trivial.

## 💡 Examples [#-examples]

**Common aliases:**

```powershell
ls          # Get-ChildItem
cd $HOME    # Set-Location
pwd         # Get-Location
cat file.txt  # Get-Content (if file exists)
echo "hi"   # Write-Output
```

**Resolve an alias:**

```powershell
Get-Alias ls
Get-Alias | Where-Object Definition -Match "ChildItem"
Get-Command ls
```

**Create a temporary alias:**

```powershell
Set-Alias -Name npp -Value notepad
# npp .\readme.md
Get-Alias npp
```

**Prefer full names in scripts:**

```powershell
# Good in scripts
Get-ChildItem -Path . -File

# Fine interactively
ls -File
```

## ⚠️ Pitfalls [#️-pitfalls]

* `curl` may alias to `Invoke-WebRequest` in Windows PowerShell — very different from real curl.
* Aliases you set in a session vanish unless added to your profile.
* Overloading familiar names can confuse teammates.
* Aliases are not expanded in all remoting / constrained sessions the same way.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/powershell/getting-started)
* [get\_help.md](/docs/powershell/get-help)
* [providers\_basics.md](/docs/powershell/providers-basics)
* [cmdlets.md](/docs/powershell/cmdlets)


# Cmdlets (/docs/powershell/cmdlets)



# Cmdlets [#cmdlets]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Cmdlets are PowerShell’s native commands: Verb-Noun names, structured objects as output, and common parameters (`-ErrorAction`, `-WhatIf`, …). Discover them with `Get-Command`, learn them with `Get-Help`, and inspect objects with `Get-Member`.

## 🔧 Core concepts [#-core-concepts]

| Idea          | Detail                                                      |
| ------------- | ----------------------------------------------------------- |
| Naming        | Approved verbs: `Get`, `Set`, `New`, `Remove`, `Add`, …     |
| Discovery     | `Get-Command *item*`, `Get-Alias`                           |
| Help          | `Get-Help cmd -Full`, `Update-Help`                         |
| Members       | `Get-Member` / `gm`                                         |
| Common params | `-Verbose`, `-Debug`, `-ErrorAction`, `-WhatIf`, `-Confirm` |
| Parameters    | Positional or named; tab-completion helps                   |
| Modules       | Cmdlets ship in modules (`Get-Module -ListAvailable`)       |

Aliases (`gci` → `Get-ChildItem`) are fine interactively; prefer full names in scripts.

## 💡 Examples [#-examples]

**Discover and inspect:**

```powershell
Get-Command -Noun Process
Get-Help Get-Process -Examples
Get-Process | Get-Member
Get-Process pwsh | Select-Object Name, Id, CPU
```

**Common parameters:**

```powershell
Remove-Item .\tmp\* -Recurse -WhatIf
Copy-Item .\a.txt .\b.txt -ErrorAction Stop
Get-ChildItem -Verbose
```

**Approved verb pattern (advanced function):**

```powershell
function Get-Something {
  [CmdletBinding()]
  param([string]$Name)
  process { "Hello $Name" }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* External programs return strings/exit codes—not objects—unless you parse them.
* Aliases differ across platforms; scripts should use canonical cmdlet names.
* `-Confirm` / `-WhatIf` only work when the command supports `SupportsShouldProcess`.
* Parameter binding errors often mean pipeline input type mismatch—check `Get-Help -Parameter`.
* `curl` / `wget` may be aliases to `Invoke-WebRequest` on Windows PowerShell 5.1.
* Don’t assume Linux binaries exist in Windows PowerShell sessions.

## 🔗 Related [#-related]

* [pipeline.md](/docs/powershell/pipeline)
* [objects.md](/docs/powershell/objects)
* [modules.md](/docs/powershell/modules)
* [useful\_commands.md](/docs/powershell/useful-commands)
* [scripting.md](/docs/powershell/scripting)


# Conditionals (/docs/powershell/conditionals)



# Conditionals [#conditionals]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Branch with `if` / `elseif` / `else`, `switch`, and ternary (`? :` in PowerShell 7+). Comparison operators are letter-based (`-eq`, `-lt`, …) and case-insensitive by default for strings. Use `-match` for regex and `-in` / `-contains` for membership.

## 🔧 Core concepts [#-core-concepts]

| Operator                 | Meaning                     |
| ------------------------ | --------------------------- |
| `-eq -ne`                | Equal / not equal           |
| `-lt -le -gt -ge`        | Ordering                    |
| `-like -notlike`         | Wildcard                    |
| `-match -notmatch`       | Regex (`$matches`)          |
| `-in -notin`             | Item in collection          |
| `-contains -notcontains` | Collection contains item    |
| `-and -or -not` / `!`    | Logic                       |
| `switch`                 | Multi-branch / regex / file |

Null-conditional: `$x?.Prop`. Null-coalescing: `$x ?? 'default'` (PS 7+).

## 💡 Examples [#-examples]

**If / elseif:**

```powershell
if ($null -eq $path) {
  throw 'path required'
} elseif (Test-Path $path -PathType Leaf) {
  'file'
} else {
  'missing or directory'
}
```

**Switch:**

```powershell
switch -Regex ($name) {
  '^ERROR'   { 'err'; break }
  '^WARN'    { 'warn'; break }
  default    { 'info' }
}
```

**Ternary and null coalesce (PS 7+):**

```powershell
$mode = $IsWindows ? 'win' : 'unix'
$port = $env:PORT ?? '8080'
```

**Membership:**

```powershell
if ($ext -in @('.jpg', '.png')) { 'image' }
if (@(1,2,3) -contains 2) { 'yes' }
```

## ⚠️ Pitfalls [#️-pitfalls]

* Put `$null` on the left: `$null -eq $x` avoids array comparison surprises.
* `-contains` is for collections on the **left**; `-in` reads more naturally for scalars.
* String compares are case-insensitive unless you use `-ceq` / `-clike` / `-cmatch`.
* `if (@())` is false; `if @(0)` is true (non-empty array)—don’t confuse with truthiness of elements.
* Assignment inside conditions is uncommon; `=` is not comparison—use `-eq`.
* `switch` falls through without `break` in some modes—be explicit.

## 🔗 Related [#-related]

* [variables.md](/docs/powershell/variables)
* [loops.md](/docs/powershell/loops)
* [error\_handling.md](/docs/powershell/error-handling)
* [pipeline.md](/docs/powershell/pipeline)
* [vs\_bash.md](/docs/powershell/vs-bash)


# Error Handling (/docs/powershell/error-handling)



# Error Handling [#error-handling]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

PowerShell has terminating and non-terminating errors. Use `-ErrorAction`, `try/catch/finally`, and `$Error` to control behavior. Prefer terminating errors for scripts that must stop; use `-ErrorVariable` to capture without stopping.

## 🔧 Core concepts [#-core-concepts]

| Mechanism                | Role                                                        |
| ------------------------ | ----------------------------------------------------------- |
| Non-terminating          | Writes to error stream; continues                           |
| Terminating              | Stops statement / enters `catch`                            |
| `-ErrorAction`           | `Stop`, `Continue`, `SilentlyContinue`, `Inquire`, `Ignore` |
| `$ErrorActionPreference` | Default for non-terminating                                 |
| `try / catch / finally`  | Structured handling                                         |
| `throw` / `Write-Error`  | Raise errors                                                |
| `$Error`                 | Automatic error list                                        |
| `$LASTEXITCODE`          | Native command exit code                                    |

`catch [System.IO.IOException]` filters by type. `$PSItem` / `$_` in `catch` is the error record.

## 💡 Examples [#-examples]

**Try/catch:**

```powershell
try {
  Get-Content -LiteralPath .\missing.txt -ErrorAction Stop
} catch {
  Write-Error "Failed: $($_.Exception.Message)"
} finally {
  'cleanup'
}
```

**Capture without stop:**

```powershell
Get-ChildItem .\nope -ErrorAction SilentlyContinue -ErrorVariable e
if ($e) { $e | ForEach-Object Message }
```

**Native commands:**

```powershell
git rev-parse HEAD
if ($LASTEXITCODE -ne 0) { throw "git failed: $LASTEXITCODE" }
```

**Preference scope:**

```powershell
$ErrorActionPreference = 'Stop'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Default `-ErrorAction Continue` means scripts keep going after many failures.
* `try/catch` only catches terminating errors—add `-ErrorAction Stop` to cmdlets.
* Swallowing errors with `SilentlyContinue` hides root causes.
* `$Error[0]` is the newest; clear carefully (`$Error.Clear()`).
* Mixing `throw` strings vs `ErrorRecord` changes catch behavior slightly.
* Pipeline errors may not abort the whole pipeline unless preference is `Stop`.

## 🔗 Related [#-related]

* [cmdlets.md](/docs/powershell/cmdlets)
* [scripting.md](/docs/powershell/scripting)
* [functions.md](/docs/powershell/functions)
* [jobs.md](/docs/powershell/jobs)
* [conditionals.md](/docs/powershell/conditionals)


# Execution Policy (/docs/powershell/execution-policy)



# Execution Policy [#execution-policy]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Execution policy is a safety gate controlling which scripts can run—not a security boundary. Policies differ by scope (Process, CurrentUser, LocalMachine). Prefer `RemoteSigned` for interactive machines; use process-scoped bypasses for CI without changing machine policy.

## 🔧 Core concepts [#-core-concepts]

| Policy         | Effect                              |
| -------------- | ----------------------------------- |
| `Restricted`   | No scripts                          |
| `AllSigned`    | Only signed scripts                 |
| `RemoteSigned` | Local OK; downloaded need signature |
| `Unrestricted` | Warn on remote; run                 |
| `Bypass`       | Nothing blocked                     |
| `Undefined`    | Defer to other scopes               |

| Scope          | Typical use          |
| -------------- | -------------------- |
| `Process`      | Current session only |
| `CurrentUser`  | Per-user registry    |
| `LocalMachine` | Machine-wide (admin) |

Zone Identifier alternate data streams mark “downloaded” files on Windows.

## 💡 Examples [#-examples]

**Inspect and set:**

```powershell
Get-ExecutionPolicy -List
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

**One-off bypass (CI / troubleshooting):**

```powershell
pwsh -ExecutionPolicy Bypass -File .\deploy.ps1
Set-ExecutionPolicy Bypass -Scope Process
```

**Unblock downloaded file:**

```powershell
Unblock-File -Path .\Install-Thing.ps1
Get-Item .\Install-Thing.ps1 -Stream *
```

## ⚠️ Pitfalls [#️-pitfalls]

* Execution policy does not stop a determined user (`powershell -Command`, bypass, copying contents).
* Group Policy may override your `Set-ExecutionPolicy`—check `-List`.
* USB/network files may still be treated as remote.
* Signing requires certificates and maintenance—don’t adopt `AllSigned` casually.
* On non-Windows, policies are largely `Unrestricted` / less relevant—still use `-File` carefully.
* Don’t set `LocalMachine` Bypass on shared workstations without need.

## 🔗 Related [#-related]

* [scripting.md](/docs/powershell/scripting)
* [profiles.md](/docs/powershell/profiles)
* [modules.md](/docs/powershell/modules)
* [error\_handling.md](/docs/powershell/error-handling)
* [useful\_commands.md](/docs/powershell/useful-commands)


# Functions (/docs/powershell/functions)



# Functions [#functions]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Functions encapsulate reusable logic. Advanced functions use `[CmdletBinding()]` to gain common parameters, pipeline binding, and `-WhatIf` support. Prefer Verb-Noun names and explicit `param()` blocks.

## 🔧 Core concepts [#-core-concepts]

| Feature            | Detail                                     |
| ------------------ | ------------------------------------------ |
| Simple             | `function Name \{ param(...) … \}`         |
| Advanced           | `[CmdletBinding()]` + `param` attributes   |
| Pipeline           | `ValueFromPipeline`, `process \{\}`        |
| Output             | Write objects; avoid `Write-Host` for data |
| Scope              | Functions see parent scope unless `local`  |
| Dynamic params     | Advanced scenarios                         |
| Comment-based help | `.SYNOPSIS` in comments                    |

Blocks: `begin`, `process`, `end`, `clean` (PS 7.3+). Use `process` for pipeline streaming.

## 💡 Examples [#-examples]

**Advanced function:**

```powershell
function Get-FileSizeMb {
  [CmdletBinding()]
  param(
    [Parameter(Mandatory, ValueFromPipeline, ValueFromPipelineByPropertyName)]
    [Alias('FullName')]
    [string]$Path
  )
  process {
    $item = Get-Item -LiteralPath $Path
    [pscustomobject]@{
      Path = $item.FullName
      SizeMB = [math]::Round($item.Length / 1MB, 2)
    }
  }
}

Get-ChildItem *.log | Get-FileSizeMb
```

**ShouldProcess:**

```powershell
function Remove-OldLog {
  [CmdletBinding(SupportsShouldProcess)]
  param([string]$Path)
  if ($PSCmdlet.ShouldProcess($Path, 'Remove')) {
    Remove-Item -LiteralPath $Path
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `Write-Host` bypasses the pipeline—use `Write-Output` / implicit output for data.
* Forgetting `process \{\}` breaks per-object pipeline behavior (only runs once).
* `$args` is unstructured—prefer `param()`.
* Name collisions with cmdlets: use a module prefix or approved verbs.
* Returning arrays may get flattened—use `Write-Output -NoEnumerate` or unary comma when needed.
* Don’t use `exit` inside library functions; throw or return instead.

## 🔗 Related [#-related]

* [cmdlets.md](/docs/powershell/cmdlets)
* [pipeline.md](/docs/powershell/pipeline)
* [modules.md](/docs/powershell/modules)
* [error\_handling.md](/docs/powershell/error-handling)
* [scripting.md](/docs/powershell/scripting)


# Get-Help (/docs/powershell/get-help)



# Get-Help [#get-help]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Get-Help` is the built-in manual for cmdlets, functions, and about topics. Learning to read help is faster than memorizing every parameter. Update help once so examples are available offline.

## 🔧 Core concepts [#-core-concepts]

| Command                   | Purpose                       |
| ------------------------- | ----------------------------- |
| `Get-Help Name`           | Show help for a command       |
| `Get-Help Name -Examples` | Example-focused view          |
| `Get-Help Name -Full`     | Complete help                 |
| `Get-Help Name -Online`   | Open web docs                 |
| `Update-Help`             | Download latest help files    |
| `Get-Command`             | Find commands by name/pattern |

Tab completion and `Get-Command *Item*` pair well with help.

## 💡 Examples [#-examples]

**Basic help:**

```powershell
Get-Help Get-ChildItem
Get-Help Get-ChildItem -Examples
Get-Help Get-ChildItem -Parameter Filter
```

**Discover commands then read help:**

```powershell
Get-Command *process*
Get-Help Get-Process -Full
```

**About topics (concepts):**

```powershell
Get-Help about_Pipelines
Get-Help about_Variables
Get-Help about_* | Select-Object -First 10
```

**Update help (may need admin for some scopes):**

```powershell
Update-Help -ErrorAction SilentlyContinue
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fresh installs often have *minimal* help until `Update-Help` runs.
* Help for third-party modules only appears after the module is installed/imported.
* `-Online` needs a browser and network.
* Alias help: `Get-Help ls` works, but learning `Get-ChildItem` is clearer long-term.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/powershell/getting-started)
* [hello\_world.md](/docs/powershell/hello-world)
* [aliases\_basics.md](/docs/powershell/aliases-basics)
* [cmdlets.md](/docs/powershell/cmdlets)


# Getting Started with PowerShell (/docs/powershell/getting-started)



# Getting Started with PowerShell [#getting-started-with-powershell]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

PowerShell is a cross-platform shell and scripting language from Microsoft. Commands are usually **cmdlets** named `Verb-Noun` (like `Get-ChildItem`). It works with .NET objects, not only text.

## 🔧 Core concepts [#-core-concepts]

| Idea             | Meaning                                  |
| ---------------- | ---------------------------------------- |
| Cmdlet           | Built-in command: `Get-Process`          |
| Pipeline         | Pass objects between commands with `\|`  |
| Object           | Structured data with properties/methods  |
| Profile          | Startup script for customizations        |
| Execution policy | Controls which scripts may run (Windows) |

Open **Windows PowerShell**, &#x2A;*PowerShell 7+** (`pwsh`), or the integrated terminal in VS Code / Cursor.

## 💡 Examples [#-examples]

**Version and help discovery:**

```powershell
$PSVersionTable.PSVersion
Get-Command Get-ChildItem
Get-Help Get-ChildItem -Examples
```

**List files (like `ls`):**

```powershell
Get-ChildItem
Get-ChildItem -Force
pwd
```

**Hello in the shell:**

```powershell
Write-Output "Hello from PowerShell"
"Hello" | Write-Host
```

**Simple script (`hello.ps1`):**

```powershell
Write-Output "Hello, World!"
```

```powershell
pwsh ./hello.ps1
```

## ⚠️ Pitfalls [#️-pitfalls]

* Execution policy may block scripts — see `Get-ExecutionPolicy`; fix carefully, not by disabling security blindly.
* Aliases like `ls` / `curl` may not match Linux behavior exactly.
* Windows PowerShell 5.1 ≠ PowerShell 7 — prefer `pwsh` when possible.
* Paths with spaces need quotes: `cd "C:\My Projects"`.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/powershell/hello-world)
* [get\_help.md](/docs/powershell/get-help)
* [providers\_basics.md](/docs/powershell/providers-basics)
* [aliases\_basics.md](/docs/powershell/aliases-basics)


# Glossary (/docs/powershell/glossary)



# Glossary [#glossary]

*Powershell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core PowerShell terms for cmdlets, objects, pipelines, remoting, and scripting.

## 🔧 Core concepts [#-core-concepts]

| Term              | Definition                                                                           |                                                            |
| ----------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| Alias             | An alternate short name for a cmdlet or function, such as `gci` for `Get-ChildItem`. |                                                            |
| Array             | An ordered collection of objects, often created with `@()` or comma lists.           |                                                            |
| Cmdlet            | A compiled .NET command following Verb-Noun naming, like `Get-Process`.              |                                                            |
| Common parameter  | Shared parameters such as `-ErrorAction` and `-Verbose` available on many commands.  |                                                            |
| Execution policy  | A setting that restricts which scripts may run on a machine.                         |                                                            |
| Filter            | A scriptblock used in the pipeline to include/exclude objects.                       |                                                            |
| Function          | A reusable named scriptblock defined with `function Name \{ \}`.                     |                                                            |
| Hash table        | A key/value map written as `@\{ Key = Value \}`.                                     |                                                            |
| Job               | A background task started with `Start-Job` or `-AsJob`.                              |                                                            |
| Member            | A property or method on a PowerShell object.                                         |                                                            |
| Module            | A package of commands loaded with `Import-Module`.                                   |                                                            |
| Object            | The structured .NET data item flowing through the PowerShell pipeline.               |                                                            |
| Parameter         | A named input to a command, often bound by name or position.                         |                                                            |
| Parameter binding | The process that maps pipeline input and arguments to parameters.                    |                                                            |
| Pipeline          | The \`                                                                               | \` chain that passes objects from one command to the next. |
| Profile           | A script that runs when a PowerShell host starts.                                    |                                                            |
| Provider          | A drive-like data store interface such as `FileSystem` or `Registry`.                |                                                            |
| PSCredential      | An object holding a username and secure password for auth.                           |                                                            |
| Remoting          | Running commands on remote machines via WinRM/`Invoke-Command`.                      |                                                            |
| Scope             | The visibility boundary for variables and functions (`Global`, `Script`, `Local`).   |                                                            |
| Scriptblock       | An anonymous block of code written as `\{ ... \}`.                                   |                                                            |
| Splatting         | Passing a hashtable of parameters with `@params`.                                    |                                                            |
| Switch            | A boolean parameter present when named, or a `switch` statement for branching.       |                                                            |
| Variable          | A named storage slot referenced as `$name`.                                          |                                                            |
| Verb-Noun         | The conventional cmdlet naming pattern (`Get-`, `Set-`, `New-`, …).                  |                                                            |
| WhatIf            | A common risk-mitigation switch that previews changes without applying them.         |                                                            |

## 💡 Examples [#-examples]

**Cmdlets and pipeline:**

```powershell
Get-ChildItem -Path . -Filter *.md |
  Where-Object { $_.Length -gt 1KB } |
  Select-Object Name, Length
```

**Splatting and functions:**

```powershell
function Get-Greeting {
  param([string]$Name)
  "Hello, $Name"
}
$params = @{ Name = "Ada" }
Get-Greeting @params
```

**Remoting:**

```powershell
Invoke-Command -ComputerName web01 -ScriptBlock {
  Get-Service nginx
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **text pipelines** (Bash) with **object pipelines** (PowerShell).
* Mixing **aliases** in scripts with full **cmdlet** names — aliases hurt readability.
* Treating **execution policy** as security boundary — it is a safety rail, not a sandbox.
* Equating &#x2A;*`$null`**, empty string, and empty array in conditionals — truthiness differs.
* Assuming **Where-Object** filters like SQL — it runs script logic per object.

## 🔗 Related [#-related]

* [cmdlets](/docs/powershell/cmdlets)
* [pipeline](/docs/powershell/pipeline)
* [functions](/docs/powershell/functions)
* [variables](/docs/powershell/variables)
* [modules](/docs/powershell/modules)
* [remoting](/docs/powershell/remoting)


# Hello World (/docs/powershell/hello-world)



# Hello World [#hello-world]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

PowerShell Hello World prints a string to the host. Use `Write-Output` (pipeline-friendly) or `Write-Host` (host UI). A `.ps1` script stores commands for reuse.

## 🔧 Core concepts [#-core-concepts]

| Piece          | Role                                                |
| -------------- | --------------------------------------------------- |
| `Write-Output` | Sends objects down the pipeline / to success stream |
| `Write-Host`   | Writes directly to the host UI                      |
| `.ps1`         | PowerShell script file                              |
| String         | `"Hello"` or `'Hello'`                              |
| Comment        | `#` starts a line comment                           |

For scripts that return data, prefer `Write-Output` (or just emit the value).

## 💡 Examples [#-examples]

**Interactive:**

```powershell
Write-Output "Hello, World!"
"Hello, World!"
```

**Script file (`hello.ps1`):**

```powershell
# hello.ps1
$name = "Ada"
Write-Output "Hello, $name!"
```

```powershell
pwsh ./hello.ps1
```

**Formatted string:**

```powershell
$version = $PSVersionTable.PSVersion
Write-Output "Hello from PowerShell $version"
```

**Write-Host vs Output:**

```powershell
Write-Host "visible on screen" -ForegroundColor Green
Write-Output "can be piped" | ForEach-Object { $_.ToUpper() }
```

## ⚠️ Pitfalls [#️-pitfalls]

* Double quotes expand `$variables`; single quotes do not.
* Running scripts may require a less restrictive execution policy in your user scope.
* `echo` is an alias for `Write-Output` — fine, but learn the real name.
* Saving with a wrong encoding can break non-ASCII characters.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/powershell/getting-started)
* [get\_help.md](/docs/powershell/get-help)
* [variables.md](/docs/powershell/variables)
* [aliases\_basics.md](/docs/powershell/aliases-basics)


# PowerShell (/docs/powershell)



# PowerShell [#powershell]

Windows shell & automation.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Jobs (/docs/powershell/jobs)



# Jobs [#jobs]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Jobs run work in the background. Classic jobs (`Start-Job`) use separate processes; thread jobs (`Start-ThreadJob`) are lighter. PowerShell 7 also offers `ForEach-Object -Parallel`. Use jobs for fan-out, long tasks, and remoting aggregation.

## 🔧 Core concepts [#-core-concepts]

| Cmdlet                  | Role                         |
| ----------------------- | ---------------------------- |
| `Start-Job`             | Background process job       |
| `Start-ThreadJob`       | Same-process thread (module) |
| `Get-Job`               | List                         |
| `Wait-Job`              | Block until done             |
| `Receive-Job`           | Collect output               |
| `Remove-Job`            | Cleanup                      |
| `Stop-Job`              | Cancel                       |
| `Invoke-Command -AsJob` | Remote as job                |

Child jobs appear under parent job objects for remoting fan-out. Always `Receive-Job` + `Remove-Job` to avoid leaks.

## 💡 Examples [#-examples]

**Local jobs:**

```powershell
$j = Start-Job -ScriptBlock {
  Start-Sleep -Seconds 2
  Get-Date
}
Wait-Job $j | Out-Null
Receive-Job $j
Remove-Job $j
```

**ThreadJob:**

```powershell
Install-Module ThreadJob -Scope CurrentUser
$jobs = 1..5 | ForEach-Object {
  Start-ThreadJob { param($n) Start-Sleep 1; $n * 2 } -ArgumentList $_
}
$jobs | Wait-Job | Receive-Job
$jobs | Remove-Job
```

**Parallel foreach (PS 7+):**

```powershell
1..10 | ForEach-Object -Parallel {
  Invoke-RestMethod "https://httpbin.org/get?n=$_"
} -ThrottleLimit 4
```

## ⚠️ Pitfalls [#️-pitfalls]

* Jobs don’t share live variables with the parent—pass `-ArgumentList` or `$using:` (remote/parallel).
* Forgetting `Receive-Job` leaves output buffered and jobs in Completed state forever.
* `Start-Job` is heavy (new runspace/process)—prefer ThreadJob/parallel for many small tasks.
* Errors surface when receiving—check job `State` and `ChildJobs`.
* UI/host-interactive cmdlets fail inside jobs.
* Remoting jobs need sessions cleaned up (`Remove-PSSession`).

## 🔗 Related [#-related]

* [remoting.md](/docs/powershell/remoting)
* [loops.md](/docs/powershell/loops)
* [error\_handling.md](/docs/powershell/error-handling)
* [scripting.md](/docs/powershell/scripting)
* [pipeline.md](/docs/powershell/pipeline)


# JSON & CSV (/docs/powershell/json-csv)



# JSON & CSV [#json--csv]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

PowerShell converts between objects and text formats with `ConvertTo-Json` / `ConvertFrom-Json` and `Export-Csv` / `Import-Csv`. Prefer object pipelines over hand-rolled string parsing. Watch depth limits and type fidelity when round-tripping JSON.

## 🔧 Core concepts [#-core-concepts]

| Cmdlet             | Role                        |
| ------------------ | --------------------------- |
| `ConvertTo-Json`   | Objects → JSON string       |
| `ConvertFrom-Json` | JSON → objects              |
| `Get-Content -Raw` | Read whole file             |
| `Export-Csv`       | Objects → CSV file          |
| `Import-Csv`       | CSV → objects (all strings) |
| `ConvertTo-Csv`    | CSV as strings in pipeline  |

PowerShell 7+ improved JSON depth defaults and added `-AsHashtable`. CSV exports include type metadata comments unless `-NoTypeInformation` (default in PS 6+).

## 💡 Examples [#-examples]

**JSON:**

```powershell
$data = Get-Content -Raw .\config.json | ConvertFrom-Json
$data.Port = 8080
$data | ConvertTo-Json -Depth 6 | Set-Content -Path .\config.json -Encoding utf8

# PS 7+
$h = Get-Content -Raw .\config.json | ConvertFrom-Json -AsHashtable
```

**CSV:**

```powershell
Get-Process |
  Select-Object Name, Id, CPU |
  Export-Csv .\procs.csv -NoTypeInformation

Import-Csv .\procs.csv |
  Where-Object { [int]$_.Id -gt 1000 }
```

**REST body:**

```powershell
$body = @{ name = 'Ada'; roles = @('dev') } | ConvertTo-Json
```

## ⚠️ Pitfalls [#️-pitfalls]

* `ConvertTo-Json` truncates nested objects when `-Depth` is too low (default historically 2).
* `Import-Csv` properties are strings—cast numbers/dates explicitly.
* `Export-Csv` of `Format-Table` output is wrong—select objects first.
* Hashtable key order / `PSCustomObject` differences affect JSON shape.
* Large JSON: streaming parsers may be better than loading entirely.
* Encoding: prefer UTF-8 without unexpected BOM issues across tools.

## 🔗 Related [#-related]

* [objects.md](/docs/powershell/objects)
* [rest\_api.md](/docs/powershell/rest-api)
* [pipeline.md](/docs/powershell/pipeline)
* [useful\_commands.md](/docs/powershell/useful-commands)
* [scripting.md](/docs/powershell/scripting)


# Loops (/docs/powershell/loops)



# Loops [#loops]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

PowerShell provides `foreach`, `for`, `while`, `do/while`, `do/until`, and pipeline-oriented `ForEach-Object`. Prefer streaming pipelines for large collections; use `foreach` statements when you need `break`/`continue` with clearer scopes.

## 🔧 Core concepts [#-core-concepts]

| Loop                       | Use                           |
| -------------------------- | ----------------------------- |
| `foreach ($x in $coll)`    | Iterate collection            |
| `ForEach-Object`           | Pipeline iteration            |
| `for (;;) / for ($i=0; …)` | Index loops                   |
| `while` / `do`             | Condition-driven              |
| `break` / `continue`       | Control flow                  |
| `return`                   | Exit function (not just loop) |

`%` is an alias for `ForEach-Object`; `?` for `Where-Object`. In scripts, prefer full names.

## 💡 Examples [#-examples]

**foreach vs pipeline:**

```powershell
foreach ($f in Get-ChildItem .\logs -File) {
  if ($f.Length -eq 0) { continue }
  $f.FullName
}

Get-ChildItem .\logs -File | ForEach-Object {
  $_.Name.ToUpper()
}
```

**for / while:**

```powershell
for ($i = 0; $i -lt 3; $i++) { $i }

$n = 0
while ($n -lt 3) { $n++; $n }
```

**do/until:**

```powershell
do {
  $r = Get-Random -Maximum 5
} until ($r -eq 0)
```

**Parallel (PS 7+):**

```powershell
1..5 | ForEach-Object -Parallel {
  Start-Sleep -Seconds 1
  $_
} -ThrottleLimit 3
```

## ⚠️ Pitfalls [#️-pitfalls]

* `return` inside `ForEach-Object` acts like `continue` for the scriptblock in some mental models—actually it exits the scriptblock only; use carefully inside functions.
* Modifying a collection while enumerating it throws—copy first or collect changes.
* `foreach ($x in Get-ChildItem -Recurse)` can be huge; filter early.
* Pipeline `ForEach-Object -Parallel` has session/state limits—avoid shared mutable state.
* `$foreach` automatic variable exists inside `foreach` statements—don’t overwrite casually.
* Prefer `Where-Object` before heavy `ForEach-Object` work.

## 🔗 Related [#-related]

* [pipeline.md](/docs/powershell/pipeline)
* [conditionals.md](/docs/powershell/conditionals)
* [functions.md](/docs/powershell/functions)
* [jobs.md](/docs/powershell/jobs)
* [objects.md](/docs/powershell/objects)


# Modules (/docs/powershell/modules)



# Modules [#modules]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Modules package functions, cmdlets, and resources for reuse. Import with `Import-Module`; discover with `Get-Module -ListAvailable`. Prefer versioned modules from the PowerShell Gallery and explicit manifests (`.psd1`) for production.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                              |
| ------------------- | --------------------------------- |
| `.psm1`             | Script module                     |
| `.psd1`             | Manifest (exports, deps, version) |
| `Import-Module`     | Load                              |
| `Remove-Module`     | Unload                            |
| `Get-Module`        | Loaded / available                |
| `Install-Module`    | From Gallery (PSGet)              |
| `$env:PSModulePath` | Search paths                      |
| Autoloading         | Commands trigger import           |

Export explicitly via `Export-ModuleMember` or manifest `FunctionsToExport`—avoid accidental exports.

## 💡 Examples [#-examples]

**Import and find:**

```powershell
Get-Module -ListAvailable | Select-Object Name, Version
Import-Module ThreadJob -Force
Get-Command -Module ThreadJob
```

**Install from Gallery:**

```powershell
Set-PSRepository PSGallery -InstallationPolicy Trusted
Install-Module -Name PSScriptAnalyzer -Scope CurrentUser
```

**Minimal module:**

```powershell
# MyUtils.psm1
function Get-Hello { 'hello' }
Export-ModuleMember -Function Get-Hello
```

```powershell
# MyUtils.psd1 (sketch)
@{
  RootModule = 'MyUtils.psm1'
  ModuleVersion = '1.0.0'
  FunctionsToExport = @('Get-Hello')
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Multiple versions on `PSModulePath`—pin with `-RequiredVersion` when needed.
* CurrentUser vs AllUsers install scopes (admin rights).
* Binary modules differ by edition (Windows PowerShell 5.1 vs PowerShell 7+).
* Dot-sourcing `.ps1` is not a module—state and exports behave differently.
* Gallery modules: review publishers; use `Install-Module -WhatIf` / checksums where required.
* Circular imports and side effects at import time make debugging hard—keep imports thin.

## 🔗 Related [#-related]

* [functions.md](/docs/powershell/functions)
* [cmdlets.md](/docs/powershell/cmdlets)
* [profiles.md](/docs/powershell/profiles)
* [scripting.md](/docs/powershell/scripting)
* [execution\_policy.md](/docs/powershell/execution-policy)


# Objects (/docs/powershell/objects)



# Objects [#objects]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Almost everything in PowerShell is a .NET object with properties and methods. Pipelines pass objects; formatting is a display concern. Use `Select-Object`, `Add-Member`, and custom `PSCustomObject` for shaping data.

## 🔧 Core concepts [#-core-concepts]

| Tool                     | Use                             |
| ------------------------ | ------------------------------- |
| `Get-Member`             | Discover properties/methods     |
| `.Property`              | Access property                 |
| `.Method()`              | Call method                     |
| `Select-Object`          | Calculated properties           |
| `[pscustomobject]@\{…\}` | Ad-hoc objects                  |
| `ConvertTo-Json`         | Serialize                       |
| ETS                      | Extended type system / adapters |

Common types: `String`, `Int32`, `DateTime`, `Hashtable`, `Array`, `PSCustomObject`, file/process/service objects from cmdlets.

## 💡 Examples [#-examples]

**Inspect and select:**

```powershell
Get-ChildItem | Get-Member -MemberType Property
Get-Process |
  Select-Object Name, Id, @{N='MemMB';E={[math]::Round($_.WS/1MB,1)}}
```

**Create objects:**

```powershell
$user = [pscustomobject]@{
  Name = 'Ada'
  Roles = @('admin', 'dev')
}
$user | Add-Member -NotePropertyName Active -NotePropertyValue $true
```

**Hashtable vs object:**

```powershell
$map = @{ a = 1; b = 2 }          # unordered dictionary
$obj = [pscustomobject]$map       # note: key order may vary pre-PS6
```

**Methods:**

```powershell
'hello'.ToUpper()
(Get-Date).AddDays(7)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hashtables are not `PSCustomObject`—property access and JSON shape differ.
* `Format-Table` output is not the original object—don’t pipe formats to `Export-Csv`.
* Value types vs references: arrays/hashtables are reference-like when passed around.
* `Select-Object -ExpandProperty` unwraps; without it you get objects with one property.
* Comparing objects with `-eq` often compares references or limited members—compare properties explicitly.
* Remote/serialized objects may be “deserialized” (methods stripped)—check `Get-Member`.

## 🔗 Related [#-related]

* [pipeline.md](/docs/powershell/pipeline)
* [json\_csv.md](/docs/powershell/json-csv)
* [cmdlets.md](/docs/powershell/cmdlets)
* [variables.md](/docs/powershell/variables)
* [remoting.md](/docs/powershell/remoting)


# Pipeline (/docs/powershell/pipeline)



# Pipeline [#pipeline]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The PowerShell pipeline passes **objects** (not text) between commands. ByValue and ByPropertyName binding decide how properties map to the next cmdlet’s parameters. Use `ForEach-Object`, `Where-Object`, and `Select-Object` as the core filters.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                                 |
| ---------------------- | ------------------------------------ |
| `\|`                   | Send objects downstream              |
| ByValue                | Entire object matches parameter type |
| ByPropertyName         | Property name matches parameter name |
| `$_` / `$PSItem`       | Current pipeline object              |
| `ForEach-Object` (`%`) | Per-object script                    |
| `Where-Object` (`?`)   | Filter                               |
| `Select-Object`        | Project / expand properties          |
| `Tee-Object`           | Copy to variable/file and continue   |

Begin/Process/End blocks in advanced functions enable true streaming.

## 💡 Examples [#-examples]

**Filter and project:**

```powershell
Get-ChildItem .\logs -File |
  Where-Object { $_.Length -gt 1MB } |
  Select-Object Name, Length, LastWriteTime |
  Sort-Object Length -Descending
```

**ForEach and Tee:**

```powershell
Get-Service |
  Where-Object Status -eq 'Running' |
  ForEach-Object { $_.Name } |
  Tee-Object -Variable names
```

**Property binding:**

```powershell
# Stop-Process binds -Id ByPropertyName
Get-Process notepad -ErrorAction SilentlyContinue |
  Stop-Process -WhatIf
```

**Collect vs stream:**

```powershell
# Parentheses collect all output first
(Get-ChildItem -Recurse).Count
```

## ⚠️ Pitfalls [#️-pitfalls]

* Wrapping a pipeline in `(…)` buffers everything—can exhaust memory on large sets.
* Native executables receive text; format may break object pipelines.
* `Format-*` cmdlets emit formatting objects—don’t pipe them to exporters; use `Select-Object` first.
* `ForEach-Object` vs `foreach` statement: the statement doesn’t stream in the same way.
* Nulls in the pipeline can surprise `-eq` filters; be explicit.
* Pipeline-bound parameters need correct attributes in custom functions.

## 🔗 Related [#-related]

* [cmdlets.md](/docs/powershell/cmdlets)
* [objects.md](/docs/powershell/objects)
* [loops.md](/docs/powershell/loops)
* [functions.md](/docs/powershell/functions)
* [vs\_bash.md](/docs/powershell/vs-bash)


# Profiles (/docs/powershell/profiles)



# Profiles [#profiles]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A profile is a script that runs when a host starts. Use it for aliases, prompt customization, and module imports—keep it fast and idempotent. Different hosts (Console, VS Code, ISE) have separate profile paths.

## 🔧 Core concepts [#-core-concepts]

| Variable / cmdlet                    | Role                           |
| ------------------------------------ | ------------------------------ |
| `$PROFILE`                           | Current host current user path |
| `$PROFILE.AllUsersAllHosts`          | All users, all hosts           |
| `$PROFILE.CurrentUserAllHosts`       | Your user, all hosts           |
| `Test-Path $PROFILE`                 | Exists?                        |
| `New-Item $PROFILE -Force`           | Create                         |
| `notepad $PROFILE` / `code $PROFILE` | Edit                           |

Hosts: Windows PowerShell vs PowerShell 7 have different profile locations. Prefer `CurrentUserAllHosts` for shared settings across VS Code and terminal.

## 💡 Examples [#-examples]

**Create and open:**

```powershell
if (-not (Test-Path -Path $PROFILE)) {
  New-Item -Path $PROFILE -ItemType File -Force
}
ise $PROFILE   # or: code $PROFILE
```

**Lean profile sketch:**

```powershell
# $PROFILE.CurrentUserAllHosts
$ErrorActionPreference = 'Continue'
Set-PSReadLineOption -EditMode Windows
function prompt {
  "PS $($executionContext.SessionState.Path.CurrentLocation)> "
}
Import-Module posh-git -ErrorAction SilentlyContinue
```

**Measure startup cost:**

```powershell
Measure-Command { pwsh -NoLogo -Command exit }
Measure-Command { . $PROFILE }
```

## ⚠️ Pitfalls [#️-pitfalls]

* Heavy imports in the profile slow every shell—lazy-load or use modules on demand.
* Don’t put secrets in profiles; use SecretManagement / env vars.
* Editing the wrong `$PROFILE` host path leads to “changes not applying”.
* `-NoProfile` in automation skips profiles—scripts should not rely on them.
* Syntax errors in a profile can break interactive sessions—keep a backup.
* Avoid changing global machine state from a user profile.

## 🔗 Related [#-related]

* [modules.md](/docs/powershell/modules)
* [execution\_policy.md](/docs/powershell/execution-policy)
* [scripting.md](/docs/powershell/scripting)
* [useful\_commands.md](/docs/powershell/useful-commands)
* [variables.md](/docs/powershell/variables)


# Providers Basics (/docs/powershell/providers-basics)



# Providers Basics [#providers-basics]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Providers** expose hierarchical data stores as if they were drives: the filesystem, registry, environment variables, certificates, and more. You navigate them with familiar cmdlets like `Set-Location` and `Get-ChildItem`.

## 🔧 Core concepts [#-core-concepts]

| Provider / Drive  | What it surfaces       |
| ----------------- | ---------------------- |
| `FileSystem`      | Disks (`C:`, `/`)      |
| `Env:`            | Environment variables  |
| `HKLM:` / `HKCU:` | Registry (Windows)     |
| `Variable:`       | PowerShell variables   |
| `Alias:`          | Command aliases        |
| `Function:`       | Functions              |
| `Cert:`           | Certificates (Windows) |

`Get-PSProvider` and `Get-PSDrive` list what is available.

## 💡 Examples [#-examples]

**List providers and drives:**

```powershell
Get-PSProvider
Get-PSDrive
```

**Environment drive:**

```powershell
Set-Location Env:
Get-ChildItem | Select-Object -First 10
Get-Content PATH
Set-Location $HOME
```

**Filesystem navigation (same cmdlets):**

```powershell
Set-Location $HOME
Get-ChildItem
New-Item -ItemType Directory -Path .\ps-practice -Force
```

**Aliases drive:**

```powershell
Get-ChildItem Alias: | Where-Object Name -EQ "ls"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Registry edits can break Windows — practice read-only first (`Get-ChildItem HKCU:\...`).
* Not every provider supports every cmdlet the same way.
* Paths like `Env:\PATH` differ from Bash `$PATH` syntax.
* Leaving yourself in `Env:` or `HKCU:` confuses later relative paths — `cd $HOME` when done.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/powershell/getting-started)
* [aliases\_basics.md](/docs/powershell/aliases-basics)
* [get\_help.md](/docs/powershell/get-help)
* [variables.md](/docs/powershell/variables)


# Remoting (/docs/powershell/remoting)



# Remoting [#remoting]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

PowerShell Remoting runs commands on remote machines over WinRM (classic) or SSH (PowerShell 7+). Use `Enter-PSSession` for interactive work and `Invoke-Command` for one-shot or fan-out automation. Always consider authentication, double-hop limits, and serialization.

## 🔧 Core concepts [#-core-concepts]

| Cmdlet                 | Role                              |
| ---------------------- | --------------------------------- |
| `Enable-PSRemoting`    | Configure WinRM (Windows, admin)  |
| `Enter-PSSession`      | Interactive remote shell          |
| `Exit-PSSession`       | Leave                             |
| `Invoke-Command`       | Run scriptblock remotely          |
| `New-PSSession`        | Persistent session                |
| `Copy-Item -ToSession` | File transfer via session         |
| SSH remoting           | `New-PSSession -HostName` (PS 7+) |

CredSSP / JEA / Just Enough Admin address delegation and least privilege. Objects returned are often deserialized (methods removed).

## 💡 Examples [#-examples]

**Invoke on many hosts:**

```powershell
$servers = 'web1', 'web2'
Invoke-Command -ComputerName $servers -ScriptBlock {
  Get-Service sshd -ErrorAction SilentlyContinue |
    Select-Object Name, Status
}
```

**Persistent session:**

```powershell
$s = New-PSSession -ComputerName web1 -Credential (Get-Credential)
Invoke-Command -Session $s -ScriptBlock { $env:COMPUTERNAME }
Copy-Item -Path .\app.zip -Destination C:\Temp\ -ToSession $s
Remove-PSSession $s
```

**SSH (PS 7+):**

```powershell
Enter-PSSession -HostName ada@linux1 -SSHTransport
```

## ⚠️ Pitfalls [#️-pitfalls]

* Second hop: remote session can’t use your creds for a third machine without CredSSP/Kerberos delegation.
* Deserialized objects lack methods—rehydrate or rematerialize on the remote side.
* Firewall / WinRM service must allow connections; HTTPS listeners for untrusted networks.
* Large fan-out: throttle with sessions and error aggregation (`-ThrottleLimit`).
* Don’t embed plain passwords; use `Get-Credential`, SecretManagement, or managed identities.
* Linux remoting needs SSH configured; WinRM is Windows-centric.

## 🔗 Related [#-related]

* [jobs.md](/docs/powershell/jobs)
* [objects.md](/docs/powershell/objects)
* [error\_handling.md](/docs/powershell/error-handling)
* [scripting.md](/docs/powershell/scripting)
* [useful\_commands.md](/docs/powershell/useful-commands)


# REST API (/docs/powershell/rest-api)



# REST API [#rest-api]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Call HTTP APIs with `Invoke-RestMethod` (JSON → objects) or `Invoke-WebRequest` (full response). PowerShell 7 aligns more closely with modern TLS and HTTP defaults. Pass headers, bodies, and auth securely—never hard-code secrets.

## 🔧 Core concepts [#-core-concepts]

| Cmdlet                       | Best for                      |
| ---------------------------- | ----------------------------- |
| `Invoke-RestMethod`          | JSON/XML APIs → objects       |
| `Invoke-WebRequest`          | Status, headers, raw content  |
| `-Method`                    | GET, POST, PUT, PATCH, DELETE |
| `-Headers`                   | Auth and content negotiation  |
| `-Body`                      | String or byte body           |
| `-ContentType`               | e.g. `application/json`       |
| `-Authentication` / `-Token` | PS 7+ auth helpers            |
| `-SkipCertificateCheck`      | Dev only (PS 7+)              |

Use `ConvertTo-Json` for bodies and splatting for readable calls.

## 💡 Examples [#-examples]

**GET / POST JSON:**

```powershell
$base = 'https://api.example.com'
$headers = @{ Authorization = "Bearer $env:API_TOKEN" }

Invoke-RestMethod -Uri "$base/v1/users/me" -Headers $headers

$body = @{ name = 'Ada'; active = $true } | ConvertTo-Json
Invoke-RestMethod -Uri "$base/v1/users" -Method Post `
  -Headers $headers -ContentType 'application/json' -Body $body
```

**Splatting + status check:**

```powershell
$params = @{
  Uri = "$base/health"
  Method = 'Get'
  TimeoutSec = 30
}
$r = Invoke-WebRequest @params
$r.StatusCode
```

**PS 7 token auth:**

```powershell
$token = ConvertTo-SecureString $env:API_TOKEN -AsPlainText -Force
Invoke-RestMethod -Uri $uri -Authentication Bearer -Token $token
```

## ⚠️ Pitfalls [#️-pitfalls]

* Windows PowerShell 5.1 defaults to older TLS—enable TLS 1.2 if needed.
* `Invoke-RestMethod` throws on many error statuses; catch and read response bodies carefully.
* Secrets in history/transcripts—prefer env vars or SecretManagement.
* Proxy and corporate MITM certs break calls—configure correctly, don’t disable validation in prod.
* Rate limits: respect `Retry-After`; add backoff.
* Large downloads: prefer `Invoke-WebRequest -OutFile` or `curl`.

## 🔗 Related [#-related]

* [json\_csv.md](/docs/powershell/json-csv)
* [error\_handling.md](/docs/powershell/error-handling)
* [variables.md](/docs/powershell/variables)
* [scripting.md](/docs/powershell/scripting)
* [useful\_commands.md](/docs/powershell/useful-commands)


# Scripting (/docs/powershell/scripting)



# Scripting [#scripting]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Scripts are `.ps1` files with parameters, comment-based help, and controlled exit codes. Write them like advanced functions: explicit params, `$ErrorActionPreference = 'Stop'` when appropriate, and no dependency on an interactive profile.

## 🔧 Core concepts [#-core-concepts]

| Topic            | Practice                                 |
| ---------------- | ---------------------------------------- |
| Shebang (Unix)   | `#!/usr/bin/env pwsh`                    |
| Params           | `param(...)` at top                      |
| `$PSScriptRoot`  | Script directory                         |
| `$PSCommandPath` | Full script path                         |
| Exit             | `exit $code` for process status          |
| Requires         | `#Requires -Version 7` / `-Modules`      |
| Dot-source       | `. .\lib.ps1` imports into current scope |
| Call operator    | `& .\script.ps1`                         |

Use approved verbs for exported functions; keep scripts focused and testable.

## 💡 Examples [#-examples]

**Parameterized script:**

```powershell
<#
.SYNOPSIS
  Compress a folder.
#>
#Requires -Version 7
param(
  [Parameter(Mandatory)]
  [string]$Path,
  [string]$OutFile = "$PSScriptRoot\out.zip"
)

Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'

if (-not (Test-Path -LiteralPath $Path)) {
  throw "Path not found: $Path"
}
Compress-Archive -Path $Path -DestinationPath $OutFile -Force
Write-Output $OutFile
```

**Run:**

```powershell
pwsh -File .\backup.ps1 -Path .\data
pwsh -NoProfile -File .\backup.ps1 -Path .\data
```

**Shared library:**

```powershell
. "$PSScriptRoot\lib\helpers.ps1"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Execution policy may block scripts—see [execution\_policy.md](/docs/powershell/execution-policy).
* Dot-sourcing mutates caller scope; prefer modules for libraries.
* Relative paths depend on the **caller's** location unless you use `$PSScriptRoot`.
* Mixing Windows PowerShell 5.1 and PS 7 syntax breaks portability—declare `#Requires`.
* Interactive prompts (`Read-Host`) fail in CI—require parameters instead.
* Don’t assume aliases from your profile exist in automation.

## 🔗 Related [#-related]

* [functions.md](/docs/powershell/functions)
* [error\_handling.md](/docs/powershell/error-handling)
* [execution\_policy.md](/docs/powershell/execution-policy)
* [modules.md](/docs/powershell/modules)
* [profiles.md](/docs/powershell/profiles)


# Useful Commands (/docs/powershell/useful-commands)



# Useful Commands [#useful-commands]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A compact toolkit of high-frequency PowerShell commands for files, processes, networking, and discovery. Prefer cmdlets in scripts; aliases are fine interactively. PowerShell 7+ (`pwsh`) is recommended for cross-platform work.

## 🔧 Core concepts [#-core-concepts]

| Area    | Go-to cmdlets                                                                          |
| ------- | -------------------------------------------------------------------------------------- |
| Files   | `Get-ChildItem`, `Copy-Item`, `Move-Item`, `Remove-Item`, `Get-Content`, `Set-Content` |
| Search  | `Select-String`, `Where-Object`                                                        |
| Process | `Get-Process`, `Stop-Process`, `Start-Process`                                         |
| Net     | `Test-Connection`, `Test-NetConnection`, `Invoke-WebRequest`                           |
| System  | `Get-Service`, `Get-ComputerInfo` (Win)                                                |
| Help    | `Get-Help`, `Get-Command`, `Get-Member`                                                |
| Path    | `Join-Path`, `Resolve-Path`, `Split-Path`, `Test-Path`                                 |

Operators: `-replace`, `-split`, `-join`, redirection `>`, `>>`, `2>`, `*>`.

## 💡 Examples [#-examples]

**Files and search:**

```powershell
Get-ChildItem -Recurse -Filter *.md |
  Select-String -Pattern 'TODO' |
  Select-Object Path, LineNumber, Line

Get-Content .\app.log -Tail 50 -Wait
```

**Processes and ports (Win):**

```powershell
Get-Process | Sort-Object CPU -Descending | Select-Object -First 10
Test-NetConnection example.com -Port 443
Get-NetTCPConnection -State Listen | Select-Object LocalPort, OwningProcess
```

**Quick JSON / clipboard (Win):**

```powershell
Invoke-RestMethod https://api.github.com/zen
Set-Clipboard (Get-Location).Path
```

**Discovery:**

```powershell
Get-Command *Item*
Get-Help about_Operators
```

## ⚠️ Pitfalls [#️-pitfalls]

* `rm`, `ls`, `cat` are aliases—behavior differs from GNU tools.
* `Remove-Item -Recurse` without `-Force` may prompt; in PS 5.1 `-Recurse` quirks exist—test first.
* `curl` alias confusion on Windows PowerShell 5.1.
* Prefer `-LiteralPath` when names contain `[` wildcards.
* Admin-required cmdlets fail silently or access-denied—check elevation.
* Don’t use `Write-Host` when you need pipeline data.

## 🔗 Related [#-related]

* [cmdlets.md](/docs/powershell/cmdlets)
* [pipeline.md](/docs/powershell/pipeline)
* [json\_csv.md](/docs/powershell/json-csv)
* [rest\_api.md](/docs/powershell/rest-api)
* [vs\_bash.md](/docs/powershell/vs-bash)


# Variables (/docs/powershell/variables)



# Variables [#variables]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Variables start with `$` and hold typed .NET objects. Scopes include `local`, `script`, `global`, and `private`. Prefer meaningful names; use `$script:` for module/script-level state and avoid polluting `$global:`.

## 🔧 Core concepts [#-core-concepts]

| Syntax                          | Meaning                                     |
| ------------------------------- | ------------------------------------------- |
| `$name = value`                 | Assign                                      |
| `$\{name-with-dashes\}`         | Unusual names                               |
| `$env:PATH`                     | Environment variable                        |
| `$null`                         | Null                                        |
| `Remove-Variable` / `rv`        | Delete                                      |
| `Get-Variable`                  | Inspect                                     |
| `Set-Variable -Option ReadOnly` | Protect                                     |
| `$true` / `$false`              | Booleans                                    |
| `[int]$n = 5`                   | Constrained type                            |
| `$$` / `$^`                     | Last/first token of last line (interactive) |

Automatic variables: `$_`, `$PSItem`, `$args`, `$PSScriptRoot`, `$PSCommandPath`, `$LASTEXITCODE`, `$?`, `$Error`.

## 💡 Examples [#-examples]

**Types and env:**

```powershell
[int]$port = 8080
$name = 'Ada'
$env:NODE_ENV = 'development'
"$name runs on $port"
```

**Scopes:**

```powershell
$script:counter = 0
function Tick {
  $script:counter++
  $local = 'only here'
}
```

**Null-conditional / coalescing (PS 7+):**

```powershell
$value = $config?.Timeout ?? 30
```

**Splatting:**

```powershell
$params = @{ Path = '.\a.txt'; Destination = '.\b.txt'; Force = $true }
Copy-Item @params
```

## ⚠️ Pitfalls [#️-pitfalls]

* `$false`, `0`, empty string, and empty arrays are all “falsy” in conditionals—know the rules.
* Assigning to `$env:VAR` affects the process environment only (not permanently unless you set user/machine env).
* `$?` is boolean success of last **PowerShell** statement; native commands also set `$LASTEXITCODE`.
* Variable names are not case-sensitive.
* Expanding in double quotes calls `.ToString()`—objects may stringify poorly; use subexpressions `"$($obj.Prop)"`.
* Don’t use `$input` casually—it’s reserved for pipeline enumerators in functions.

## 🔗 Related [#-related]

* [objects.md](/docs/powershell/objects)
* [conditionals.md](/docs/powershell/conditionals)
* [functions.md](/docs/powershell/functions)
* [scripting.md](/docs/powershell/scripting)
* [vs\_bash.md](/docs/powershell/vs-bash)


# PowerShell vs Bash (/docs/powershell/vs-bash)



# PowerShell vs Bash [#powershell-vs-bash]

*PowerShell · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Bash pipelines text; PowerShell pipelines objects. Bash is ubiquitous on Unix; PowerShell is cross-platform (pwsh) with deep .NET integration. Choose based on environment and data shape—many teams use both.

## 🔧 Core concepts [#-core-concepts]

| Topic         | Bash          | PowerShell                       |
| ------------- | ------------- | -------------------------------- |
| Pipeline      | Text streams  | Objects                          |
| Variables     | `$x`, strings | `$x`, typed objects              |
| Compare       | `[[ ]]`, `=`  | `-eq`, `-lt`, …                  |
| Errors        | Exit codes    | Error records + exit codes       |
| Lists         | Arrays / IFS  | Object collections               |
| JSON          | `jq`          | `ConvertFrom-Json`               |
| Common filter | `grep`/`awk`  | `Where-Object` / `Select-String` |
| Script ext    | `.sh`         | `.ps1`                           |

Interop: call bash from pwsh and vice versa when tools are installed.

## 💡 Examples [#-examples]

**Same task:**

```shellscript
# bash
ls -1 *.log | wc -l
cat file.json | jq '.name'
```

```powershell
# PowerShell
@(Get-ChildItem *.log).Count
(Get-Content -Raw file.json | ConvertFrom-Json).name
```

**Call the other shell:**

```powershell
bash -lc 'grep -R TODO .'
```

```shellscript
pwsh -NoProfile -Command 'Get-ChildItem | Select-Object Name'
```

**Environment vars:**

```shellscript
export PORT=8080
```

```powershell
$env:PORT = '8080'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Assuming `curl` means the same thing (alias vs binary) across shells.
* Quoting rules differ—don’t paste bash snippets into PowerShell unchanged.
* Exit codes: bash `set -e` vs PowerShell `$ErrorActionPreference`.
* Line endings and shebangs matter when sharing scripts across OSes.
* Performance: spawning many external processes from either shell is costly—batch work.
* Object formatting in PowerShell can look like “broken text” when piped to bash tools—convert explicitly.

## 🔗 Related [#-related]

* [pipeline.md](/docs/powershell/pipeline)
* [variables.md](/docs/powershell/variables)
* [useful\_commands.md](/docs/powershell/useful-commands)
* [scripting.md](/docs/powershell/scripting)
* [cmdlets.md](/docs/powershell/cmdlets)


# Actions (/docs/playwright/actions)



# Actions [#actions]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Actions (`click`, `fill`, `press`, `check`, …) auto-wait for actionability: attached, visible, stable, enabled, and receiving events. Prefer locator actions over raw mouse coordinates.

## 🔧 Core concepts [#-core-concepts]

| Action                       | Notes                            |
| ---------------------------- | -------------------------------- |
| `click` / `dblclick`         | Scrolls into view, waits         |
| `fill`                       | Clears then types                |
| `type` / `pressSequentially` | Key-by-key (rare)                |
| `press`                      | Shortcuts (`Enter`, `Control+A`) |
| `check` / `uncheck`          | Checkboxes                       |
| `selectOption`               | `<select>`                       |
| `hover` / `focus`            | Pointer / focus                  |
| `dragTo`                     | Drag and drop                    |
| `setInputFiles`              | File uploads                     |

Force: `\{ force: true \}` skips checks — use sparingly.

## 💡 Examples [#-examples]

**Forms:**

```ts
await page.getByLabel('Email').fill('ada@example.com');
await page.getByLabel('Password').fill('secret');
await page.getByRole('checkbox', { name: 'Remember me' }).check();
await page.getByLabel('Country').selectOption('GB');
await page.getByRole('button', { name: 'Sign in' }).click();
```

**Keyboard & mouse:**

```ts
await page.getByRole('textbox').press('Control+A');
await page.getByRole('textbox').press('Backspace');
await page.getByText('Item').hover();
await page.getByTestId('handle').dragTo(page.getByTestId('dropzone'));
```

**Files & dialogs:**

```ts
await page.getByLabel('Avatar').setInputFiles('fixtures/avatar.png');
page.once('dialog', (d) => d.accept());
await page.getByRole('button', { name: 'Delete' }).click();
```

**Position / modifiers:**

```ts
await page.getByRole('button').click({ button: 'right' });
await page.getByRole('button').click({ modifiers: ['Shift'] });
await page.getByTestId('canvas').click({ position: { x: 10, y: 20 } });
```

## ⚠️ Pitfalls [#️-pitfalls]

* `page.click('css')` string API is legacy — use locators.
* `fill` on contenteditable may need `pressSequentially`.
* Clicking covered elements — fix overlay or use proper waits, not only `force`.
* Race with animations — wait for stable state / assert visibility first.
* Uploading absolute paths that don't exist on CI agents.

## 🔗 Related [#-related]

* [Locators](/docs/playwright/locators)
* [Assertions](/docs/playwright/assertions)
* [Navigation](/docs/playwright/navigation)
* [Page object](/docs/playwright/page-object)
* [Network](/docs/playwright/network)
* [Fixtures](/docs/playwright/fixtures)


# API Testing (/docs/playwright/api-testing)



# API Testing [#api-testing]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`APIRequestContext` (`request` fixture) exercises HTTP APIs without a browser. Combine with UI tests for setup, teardown, and contract checks.

## 🔧 Core concepts [#-core-concepts]

| Piece                           | Role                       |
| ------------------------------- | -------------------------- |
| `request` fixture               | Per-test API context       |
| `playwright.request.newContext` | Custom baseURL/headers     |
| `get/post/put/patch/delete`     | HTTP verbs                 |
| `storageState`                  | Share cookies with browser |

Assertions use response helpers + plain `expect`.

## 💡 Examples [#-examples]

**CRUD smoke:**

```ts
import { test, expect } from '@playwright/test';

test('create user via API', async ({ request }) => {
  const res = await request.post('/api/users', {
    data: { name: 'Ada', email: 'ada@ex.com' },
  });
  expect(res.ok()).toBeTruthy();
  const body = await res.json();
  expect(body).toMatchObject({ name: 'Ada' });

  const get = await request.get(`/api/users/${body.id}`);
  expect(get.status()).toBe(200);
});
```

**Auth header context:**

```ts
test('with token', async ({ playwright }) => {
  const api = await playwright.request.newContext({
    baseURL: 'https://api.example.com',
    extraHTTPHeaders: { Authorization: `Bearer ${process.env.TOKEN}` },
  });
  const res = await api.get('/v1/me');
  expect(res.status()).toBe(200);
  await api.dispose();
});
```

**Seed UI from API:**

```ts
test('ui shows seeded item', async ({ request, page }) => {
  await request.post('/api/items', { data: { title: 'Seeded' } });
  await page.goto('/items');
  await expect(page.getByText('Seeded')).toBeVisible();
});
```

**Config `use.baseURL` applies to `request` when relative.**

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `await api.dispose()` on custom contexts.
* Asserting only status codes — check body shape too.
* Sharing mutable server state across parallel API tests.
* Mixing browser cookies and API tokens inconsistently.
* Hitting prod APIs from local suites without guards.

## 🔗 Related [#-related]

* [Network](/docs/playwright/network)
* [Authentication](/docs/playwright/authentication)
* [Fixtures](/docs/playwright/fixtures)
* [Assertions](/docs/playwright/assertions)
* [CI](/docs/playwright/ci)
* [Config](/docs/playwright/config)


# Assertions (/docs/playwright/assertions)



# Assertions [#assertions]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Playwright's `expect` auto-retries until the condition passes or timeout. Prefer web-first assertions (`toBeVisible`, `toHaveURL`) over manual polling.

## 🔧 Core concepts [#-core-concepts]

| Assertion                      | Checks              |
| ------------------------------ | ------------------- |
| `toBeVisible` / `toBeHidden`   | Visibility          |
| `toBeEnabled` / `toBeDisabled` | Interactability     |
| `toHaveText` / `toContainText` | Text content        |
| `toHaveValue`                  | Input value         |
| `toHaveAttribute`              | Attribute           |
| `toHaveCount`                  | Locator match count |
| `toHaveURL` / `toHaveTitle`    | Navigation          |
| `toHaveScreenshot`             | Visual baseline     |

Soft assertions: `expect.soft` continues after failure within the test.

## 💡 Examples [#-examples]

**Element state:**

```ts
import { test, expect } from '@playwright/test';

await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled();
await expect(page.getByText('Saved')).toBeVisible();
await expect(page.getByLabel('Name')).toHaveValue('Ada');
await expect(page.getByRole('listitem')).toHaveCount(3);
```

**Page-level:**

```ts
await expect(page).toHaveURL(/\/dashboard/);
await expect(page).toHaveTitle(/Dashboard/);
await expect(page.getByRole('alert')).toContainText('success');
```

**Custom timeout / soft:**

```ts
await expect(page.getByText('Ready')).toBeVisible({ timeout: 15_000 });
await expect.soft(page.getByTestId('a')).toBeVisible();
await expect.soft(page.getByTestId('b')).toBeVisible();
// test fails at end if any soft failed
```

**API response:**

```ts
const res = await request.get('/api/health');
expect(res.ok()).toBeTruthy();
expect(await res.json()).toMatchObject({ status: 'up' });
```

**Negation:**

```ts
await expect(page.getByText('Error')).not.toBeVisible();
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using Node `assert` or Jest `expect` without auto-wait.
* Asserting immediately after click without waiting for navigation/network.
* Overly strict full-string `toHaveText` when UI adds whitespace/icons.
* Screenshot assertions without stable fonts/animations (see visual comparisons).
* Swallowing failures with try/catch around `expect`.

## 🔗 Related [#-related]

* [Locators](/docs/playwright/locators)
* [Actions](/docs/playwright/actions)
* [Visual comparisons](/docs/playwright/visual-comparisons)
* [API testing](/docs/playwright/api-testing)
* [Network](/docs/playwright/network)
* [Tracing](/docs/playwright/tracing)


# Authentication (/docs/playwright/authentication)



# Authentication [#authentication]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Reuse logged-in state via `storageState` so suites skip UI login every test. Combine setup projects, global setup, or API login for speed and stability.

## 🔧 Core concepts [#-core-concepts]

| Approach                          | When                        |
| --------------------------------- | --------------------------- |
| UI login once → `storageState`    | Cookie/session apps         |
| API login → inject cookies/tokens | Faster, less UI flake       |
| Setup project dependency          | Official multi-role pattern |
| `httpCredentials`                 | Basic auth                  |

`storageState` saves cookies + localStorage from a context.

## 💡 Examples [#-examples]

**Save state after login:**

```ts
// auth.setup.ts
import { test as setup } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill(process.env.USER!);
  await page.getByLabel('Password').fill(process.env.PASS!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.waitForURL('**/home');
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
});
```

**Config projects:**

```ts
projects: [
  { name: 'setup', testMatch: /.*\.setup\.ts/ },
  {
    name: 'chromium',
    use: {
      ...devices['Desktop Chrome'],
      storageState: 'playwright/.auth/user.json',
    },
    dependencies: ['setup'],
  },
],
```

**API login:**

```ts
const res = await request.post('/api/login', {
  data: { email, password },
});
const { token } = await res.json();
await context.addCookies([{
  name: 'session',
  value: token,
  domain: 'localhost',
  path: '/',
}]);
```

**Per-role states:** `admin.json`, `user.json` — separate projects or fixtures.

## ⚠️ Pitfalls [#️-pitfalls]

* Committing real credentials or auth files with secrets.
* Expired tokens in cached `storageState` on long CI runs.
* Sharing one storage file across parallel workers that mutate session.
* Testing login UX only in setup — keep a dedicated login test.
* Ignoring CSRF / SameSite cookie constraints in API injection.

## 🔗 Related [#-related]

* [Fixtures](/docs/playwright/fixtures)
* [Config](/docs/playwright/config)
* [API testing](/docs/playwright/api-testing)
* [Network](/docs/playwright/network)
* [Parallel](/docs/playwright/parallel)
* [CI](/docs/playwright/ci)


# CI (/docs/playwright/ci)



# CI [#ci]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Run Playwright headlessly in CI with browser deps, artifacts (report, trace, video), sharding, and a started app via `webServer` or job services.

## 🔧 Core concepts [#-core-concepts]

| Concern    | Practice                                     |
| ---------- | -------------------------------------------- |
| Browsers   | `npx playwright install --with-deps`         |
| Retries    | `retries: 2` on CI only                      |
| Workers    | Conservative (1–2) on small runners          |
| Artifacts  | Upload `playwright-report/`, `test-results/` |
| Sharding   | `--shard=n/m` across jobs                    |
| Containers | Official Playwright Docker image             |

## 💡 Examples [#-examples]

**GitHub Actions (sketch):**

```yaml
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with: { node-version: 22 }
- run: npm ci
- run: npx playwright install --with-deps
- run: npx playwright test
  env:
    CI: true
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: playwright-report
    path: playwright-report/
```

**Config CI guards:**

```ts
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
workers: process.env.CI ? 2 : undefined,
reporter: process.env.CI
  ? [['github'], ['html'], ['list']]
  : [['list'], ['html']],
```

**Docker:**

```shellscript
docker run --rm -v $PWD:/work -w /work mcr.microsoft.com/playwright:v1.49.0-jammy \
  /bin/bash -c "npm ci && npx playwright test"
```

Pin image tag to the same Playwright version as `package.json`.

**Shard matrix:** `strategy.matrix.shard: [1, 2, 3]` + `--shard=$\{\{ matrix.shard \}\}/3`.

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `--with-deps` on Ubuntu → browser launch errors.
* Not uploading artifacts on failure (`if: always()`).
* Snapshot baselines from a different OS than CI.
* Starting the app twice (`webServer` + manual job step).
* Secrets in logs from `DEBUG=pw:api` in CI.

## 🔗 Related [#-related]

* [Install](/docs/playwright/install)
* [Config](/docs/playwright/config)
* [Parallel](/docs/playwright/parallel)
* [Tracing](/docs/playwright/tracing)
* [Visual comparisons](/docs/playwright/visual-comparisons)
* [Authentication](/docs/playwright/authentication)


# Codegen (/docs/playwright/codegen)



# Codegen [#codegen]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`playwright codegen` records interactions and emits locator-based scripts. Use it to bootstrap tests, then harden selectors and assertions.

## 🔧 Core concepts [#-core-concepts]

| Flag             | Purpose                 |
| ---------------- | ----------------------- |
| `codegen [url]`  | Open recorder           |
| `-o file`        | Write output file       |
| `--target`       | javascript / python / … |
| `--device`       | Emulate device          |
| `--save-storage` | Capture auth state      |
| `--load-storage` | Start authenticated     |

Inspector also opens via `--debug` or the VS Code extension.

## 💡 Examples [#-examples]

**Record a flow:**

```shellscript
npx playwright codegen https://demo.playwright.dev/todomvc
npx playwright codegen --target=javascript -o tests/todo.spec.ts
npx playwright codegen --device="iPhone 13"
```

**With auth:**

```shellscript
npx playwright codegen --load-storage=playwright/.auth/user.json https://app.local
npx playwright codegen --save-storage=playwright/.auth/user.json
```

**Pick locator in UI mode:**

```shellscript
npx playwright test --ui
```

Use the locator tool to copy `getByRole` suggestions.

**Emitted style (edit after):**

```ts
await page.getByPlaceholder('What needs to be done?').click();
await page.getByPlaceholder('What needs to be done?').fill('Buy milk');
await page.getByPlaceholder('What needs to be done?').press('Enter');
await expect(page.getByText('Buy milk')).toBeVisible();
```

Refactor into page objects and replace fragile generated waits.

## ⚠️ Pitfalls [#️-pitfalls]

* Shipping raw codegen output without assertions or cleanup.
* Generated CSS selectors when roles/labels exist.
* Recording on production with real PII.
* Ignoring hover/timing-sensitive steps that codegen under-specifies.
* Mixing codegen languages with a TS project config.

## 🔗 Related [#-related]

* [Locators](/docs/playwright/locators)
* [Actions](/docs/playwright/actions)
* [Page object](/docs/playwright/page-object)
* [Install](/docs/playwright/install)
* [Authentication](/docs/playwright/authentication)
* [Mobile emulation](/docs/playwright/mobile-emulation)


# Config (/docs/playwright/config)



# Config [#config]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`playwright.config.ts` defines projects, timeouts, reporters, base URL, and shared `use` options. One config drives local runs and CI.

## 🔧 Core concepts [#-core-concepts]

| Option           | Purpose                     |
| ---------------- | --------------------------- |
| `testDir`        | Where specs live            |
| `timeout`        | Per-test limit (ms)         |
| `expect.timeout` | Assertion wait              |
| `retries`        | Flake recovery              |
| `workers`        | Parallel processes          |
| `use`            | Shared browser/context opts |
| `projects`       | Browser / device matrix     |
| `reporter`       | list, html, github, etc.    |

## 💡 Examples [#-examples]

**Typical config:**

```ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['html', { open: 'never' }], ['list']],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});
```

**Env overrides:**

```shellscript
npx playwright test --config=playwright.config.ts
npx playwright test --project=chromium --workers=4
PWDEBUG=1 npx playwright test
```

**Timeouts:**

```ts
export default defineConfig({
  timeout: 60_000,
  expect: { timeout: 10_000 },
  use: { actionTimeout: 15_000, navigationTimeout: 30_000 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hardcoding `localhost` without `baseURL` / `webServer` breaks CI.
* Too many workers on shared CI runners causes flakes and OOM.
* `trace: 'on'` for every test balloons artifacts — prefer `on-first-retry`.
* Forgetting `forbidOnly` lets `.only` slip into main.
* Device presets vs custom viewport — pick one strategy per project.

## 🔗 Related [#-related]

* [Install](/docs/playwright/install)
* [Parallel](/docs/playwright/parallel)
* [CI](/docs/playwright/ci)
* [Tracing](/docs/playwright/tracing)
* [Screenshots & video](/docs/playwright/screenshots-video)
* [Mobile emulation](/docs/playwright/mobile-emulation)


# Fixtures (/docs/playwright/fixtures)



# Fixtures [#fixtures]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Fixtures inject `page`, `context`, `browser`, `request`, and custom setup into tests. Extend `test` to share auth, DB seeds, or page objects without globals.

## 🔧 Core concepts [#-core-concepts]

| Built-in  | Provides                 |
| --------- | ------------------------ |
| `page`    | Fresh page per test      |
| `context` | Isolated browser context |
| `browser` | Shared browser instance  |
| `request` | APIRequestContext        |
| `baseURL` | From config `use`        |

Custom fixtures use `test.extend` with setup/teardown and optional scope (`test` | `worker`).

## 💡 Examples [#-examples]

**Built-in usage:**

```ts
import { test, expect } from '@playwright/test';

test('uses page fixture', async ({ page }) => {
  await page.goto('/');
  await expect(page.getByRole('heading')).toBeVisible();
});
```

**Custom fixture:**

```ts
import { test as base, expect } from '@playwright/test';

type Fixtures = {
  todoPage: { add: (text: string) => Promise<void> };
};

export const test = base.extend<Fixtures>({
  todoPage: async ({ page }, use) => {
    await page.goto('/todos');
    const todoPage = {
      add: async (text: string) => {
        await page.getByPlaceholder('What needs doing?').fill(text);
        await page.keyboard.press('Enter');
      },
    };
    await use(todoPage);
  },
});

test('add todo', async ({ todoPage, page }) => {
  await todoPage.add('Buy milk');
  await expect(page.getByText('Buy milk')).toBeVisible();
});
```

**Worker-scoped (expensive setup once per worker):**

```ts
export const test = base.extend<{}, { token: string }>({
  token: [async ({}, use) => {
    const token = await fetchToken();
    await use(token);
  }, { scope: 'worker' }],
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutating shared worker state across tests → order-dependent flakes.
* Creating pages outside fixtures without closing them.
* Overusing worker scope for data that must be isolated per test.
* Forgetting to `await use(...)` — teardown never runs.
* Importing bare `@playwright/test` after extending — use your extended `test`.

## 🔗 Related [#-related]

* [Page object](/docs/playwright/page-object)
* [Authentication](/docs/playwright/authentication)
* [Config](/docs/playwright/config)
* [API testing](/docs/playwright/api-testing)
* [Parallel](/docs/playwright/parallel)
* [Assertions](/docs/playwright/assertions)


# Glossary (/docs/playwright/glossary)



# Glossary [#glossary]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core Playwright terms for browser automation, locators, fixtures, and end-to-end testing.

## 🔧 Core concepts [#-core-concepts]

| Term                 | Definition                                                                 |
| -------------------- | -------------------------------------------------------------------------- |
| Action               | An interaction such as click, fill, or press performed on a locator.       |
| Assertion            | A check that verifies page state, often auto-retrying with `expect`.       |
| Auto-waiting         | Playwright’s habit of waiting for elements to be actionable before acting. |
| Browser              | A launched browser type instance such as Chromium, Firefox, or WebKit.     |
| BrowserContext       | An isolated browser session with its own cookies, storage, and cache.      |
| Codegen              | The recorder that generates Playwright scripts from manual interactions.   |
| Expect               | Playwright’s assertion API that retries until timeout.                     |
| Fixture              | Reusable test setup/teardown provided by the test runner (e.g. `page`).    |
| Frame                | A nested browsing context inside a page, such as an iframe.                |
| Headless             | Running a browser without a visible UI window.                             |
| Locator              | A lazy, strict query describing how to find element(s) on a page.          |
| Network interception | Mocking or observing HTTP requests via route handlers.                     |
| Page                 | A single tab/document you navigate and automate.                           |
| Page Object          | A class that encapsulates selectors and actions for a UI area.             |
| Parallelism          | Running tests concurrently across workers for speed.                       |
| Playwright Test      | The built-in test runner (`@playwright/test`) with projects and reporters. |
| Project              | A named configuration slice (browser, device, or dependency set).          |
| Reporter             | A plugin that formats and outputs test results.                            |
| Screenshot           | A captured image of a page or element for debugging or visual checks.      |
| Selector engine      | The matching strategy behind locators (role, text, CSS, XPath, etc.).      |
| Storage state        | Saved cookies/localStorage used to reuse authenticated sessions.           |
| Timeout              | The maximum wait before an action or assertion fails.                      |
| Trace                | A detailed recording of actions, DOM snapshots, and network for debugging. |
| Video                | An optional recording of the test browser session.                         |
| Worker               | A parallel process that executes a subset of tests.                        |

## 💡 Examples [#-examples]

**Locator and assertion:**

```ts
import { test, expect } from "@playwright/test";

test("login", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill("a@b.com");
  await page.getByRole("button", { name: "Sign in" }).click();
  await expect(page.getByText("Dashboard")).toBeVisible();
});
```

**Network mock:**

```ts
await page.route("**/api/user", async (route) => {
  await route.fulfill({
    status: 200,
    body: JSON.stringify({ name: "Ada" }),
  });
});
```

**Page object sketch:**

```ts
class LoginPage {
  constructor(private page: Page) {}
  async login(email: string, password: string) {
    await this.page.getByLabel("Email").fill(email);
    await this.page.getByLabel("Password").fill(password);
    await this.page.getByRole("button", { name: "Sign in" }).click();
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **locator** (lazy, re-querying) with a one-shot **ElementHandle**.
* Mixing **page** and **context** — auth/storage lives on the context.
* Treating **CSS selectors** as first choice when **role/text** locators are more stable.
* Equating a **trace** with a **screenshot** — traces capture the full timeline.
* Assuming **auto-waiting** removes the need for good assertions and timeouts.

## 🔗 Related [#-related]

* [locators](/docs/playwright/locators)
* [assertions](/docs/playwright/assertions)
* [fixtures](/docs/playwright/fixtures)
* [page\_object](/docs/playwright/page-object)
* [network](/docs/playwright/network)
* [tracing](/docs/playwright/tracing)


# Playwright (/docs/playwright)



# Playwright [#playwright]

E2E browser testing.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Install (/docs/playwright/install)



# Install [#install]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Playwright is a cross-browser E2E library for Chromium, Firefox, and WebKit. Install the Node package, then download browser binaries with `npx playwright install`.

## 🔧 Core concepts [#-core-concepts]

| Piece              | Role                        |
| ------------------ | --------------------------- |
| `@playwright/test` | Test runner + assertions    |
| `playwright`       | Library-only (no runner)    |
| Browser binaries   | Chromium / Firefox / WebKit |
| System deps        | OS libs for headed/headless |

**Install (npm):**

```shellscript
npm init playwright@latest
# or into existing project:
npm i -D @playwright/test
npx playwright install
npx playwright install --with-deps   # CI / Linux
```

**Python / Java / .NET** also exist; this folder focuses on the JS/TS runner.

## 💡 Examples [#-examples]

**Minimal package scripts:**

```json
{
  "scripts": {
    "test": "playwright test",
    "test:ui": "playwright test --ui",
    "test:headed": "playwright test --headed",
    "report": "playwright show-report"
  }
}
```

**Verify browsers:**

```shellscript
npx playwright --version
npx playwright install chromium
npx playwright install firefox webkit
```

**First test (`tests/example.spec.ts`):**

```ts
import { test, expect } from '@playwright/test';

test('homepage has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});
```

**Run:**

```shellscript
npx playwright test
npx playwright test --project=chromium
npx playwright test tests/example.spec.ts
```

## ⚠️ Pitfalls [#️-pitfalls]

* Installing the npm package without `playwright install` → missing browser binaries.
* Mixing global and local CLI — prefer `npx playwright` from the project.
* Skipping `--with-deps` on Linux CI causes cryptic launch failures.
* Pinning `@playwright/test` without reinstalling browsers after upgrades.
* Using `playwright` alone when you need `@playwright/test` fixtures.

## 🔗 Related [#-related]

* [Config](/docs/playwright/config)
* [Codegen](/docs/playwright/codegen)
* [CI](/docs/playwright/ci)
* [Fixtures](/docs/playwright/fixtures)
* [Parallel](/docs/playwright/parallel)
* [Tracing](/docs/playwright/tracing)


# Locators (/docs/playwright/locators)



# Locators [#locators]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Locators find elements lazily and auto-wait until actionable. Prefer user-facing selectors: role, label, text, placeholder — avoid brittle CSS/XPath when possible.

## 🔧 Core concepts [#-core-concepts]

| Locator                       | Use when                          |
| ----------------------------- | --------------------------------- |
| `getByRole`                   | Buttons, links, headings, dialogs |
| `getByLabel`                  | Form controls with labels         |
| `getByPlaceholder`            | Inputs by placeholder             |
| `getByText`                   | Visible text                      |
| `getByTestId`                 | Stable `data-testid`              |
| `getByAltText` / `getByTitle` | Images / titled nodes             |
| `locator('css')`              | Escape hatch                      |

Chain with `filter`, `nth`, `and`, `or`. Locators re-query on each action.

## 💡 Examples [#-examples]

**Preferred patterns:**

```ts
page.getByRole('button', { name: 'Submit' });
page.getByRole('heading', { name: 'Settings', level: 1 });
page.getByLabel('Email');
page.getByPlaceholder('Search…');
page.getByText('Welcome back');
page.getByTestId('user-menu');
```

**Filtering & chaining:**

```ts
const row = page.getByRole('row').filter({ hasText: 'Ada' });
await row.getByRole('button', { name: 'Edit' }).click();

page.locator('ul').filter({ has: page.getByText('Active') });
page.getByRole('listitem').nth(0);
```

**Strict mode:** actions fail if multiple matches. Narrow with filter or `exact: true`:

```ts
page.getByText('Save', { exact: true });
page.getByRole('link', { name: 'Docs', exact: true });
```

**Frame / shadow:**

```ts
page.frameLocator('iframe#editor').getByRole('textbox');
page.locator('my-widget').getByRole('button'); // pierce open shadow
```

## ⚠️ Pitfalls [#️-pitfalls]

* CSS like `.btn-primary:nth-child(3)` breaks on layout changes.
* `getByText` substring matches — use `exact` or role when ambiguous.
* Clicking before visibility — locators auto-wait; don't add blind `waitForTimeout`.
* Ignoring accessible names — fix a11y labels instead of forcing testids everywhere.
* Assuming order of `all()` is stable without sorting assertions.

## 🔗 Related [#-related]

* [Actions](/docs/playwright/actions)
* [Assertions](/docs/playwright/assertions)
* [Page object](/docs/playwright/page-object)
* [Codegen](/docs/playwright/codegen)
* [Fixtures](/docs/playwright/fixtures)
* [Mobile emulation](/docs/playwright/mobile-emulation)


# Mobile Emulation (/docs/playwright/mobile-emulation)



# Mobile Emulation [#mobile-emulation]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Emulate mobile viewports, touch, user agents, and device scale via `devices` presets or custom `use` options. Real device clouds are separate — this is browser emulation.

## 🔧 Core concepts [#-core-concepts]

| Option                        | Controls                   |
| ----------------------------- | -------------------------- |
| `devices['iPhone 13']`        | Viewport, UA, touch, scale |
| `viewport`                    | Width / height             |
| `isMobile` / `hasTouch`       | Mobile heuristics / touch  |
| `deviceScaleFactor`           | DPR                        |
| `geolocation` / `permissions` | Location APIs              |
| `colorScheme`                 | light / dark               |

WebKit project ≈ Safari-like; Chromium ≈ Chrome Android-ish with device UA.

## 💡 Examples [#-examples]

**Project matrix:**

```ts
import { defineConfig, devices } from '@playwright/test';

projects: [
  { name: 'Pixel 7', use: { ...devices['Pixel 7'] } },
  { name: 'iPhone 13', use: { ...devices['iPhone 13'] } },
  {
    name: 'iPhone landscape',
    use: {
      ...devices['iPhone 13 landscape'],
    },
  },
],
```

**Custom phone:**

```ts
use: {
  viewport: { width: 390, height: 844 },
  userAgent: 'Mozilla/5.0 ...',
  isMobile: true,
  hasTouch: true,
  deviceScaleFactor: 3,
},
```

**Geolocation:**

```ts
await context.grantPermissions(['geolocation']);
await context.setGeolocation({ latitude: 51.5, longitude: -0.12 });
```

**Codegen on device:**

```shellscript
npx playwright codegen --device="iPhone 13" https://example.com
```

## ⚠️ Pitfalls [#️-pitfalls]

* Emulation ≠ real iOS/Android WebView quirks.
* Touch gestures differ — use `tap` where needed; hover is desktop-only.
* Fixed desktop locators failing on collapsed mobile nav.
* Ignoring safe-area / soft keyboard overlap in screenshots.
* Running all devices on every PR without sharding — slow CI.

## 🔗 Related [#-related]

* [Config](/docs/playwright/config)
* [Locators](/docs/playwright/locators)
* [Screenshots & video](/docs/playwright/screenshots-video)
* [Visual comparisons](/docs/playwright/visual-comparisons)
* [Codegen](/docs/playwright/codegen)
* [Parallel](/docs/playwright/parallel)


# Navigation (/docs/playwright/navigation)



# Navigation [#navigation]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`page.goto`, history APIs, and wait helpers synchronize tests with loads, SPA route changes, and downloads. Pair navigation with URL assertions.

## 🔧 Core concepts [#-core-concepts]

| API                         | Role                                        |
| --------------------------- | ------------------------------------------- |
| `page.goto(url)`            | Full navigation                             |
| `page.reload()`             | Refresh                                     |
| `page.goBack` / `goForward` | History                                     |
| `waitForURL`                | SPA / redirect                              |
| `waitForLoadState`          | `load` / `domcontentloaded` / `networkidle` |
| `baseURL`                   | Relative paths in config                    |

`goto` waits for `load` by default (`waitUntil` option). Prefer `domcontentloaded` for SPAs that keep connections open.

## 💡 Examples [#-examples]

**Basic:**

```ts
await page.goto('/');
await page.goto('/settings', { waitUntil: 'domcontentloaded' });
await expect(page).toHaveURL(/\/settings/);
```

**Click that navigates:**

```ts
await Promise.all([
  page.waitForURL('**/dashboard'),
  page.getByRole('link', { name: 'Dashboard' }).click(),
]);
// or simply:
await page.getByRole('link', { name: 'Dashboard' }).click();
await expect(page).toHaveURL(/dashboard/);
```

**Load states:**

```ts
await page.goto('/heavy');
await page.waitForLoadState('networkidle'); // avoid if websockets/polling
```

**Popups / new tabs:**

```ts
const [popup] = await Promise.all([
  page.waitForEvent('popup'),
  page.getByRole('link', { name: 'Open report' }).click(),
]);
await popup.waitForLoadState();
await expect(popup).toHaveTitle(/Report/);
```

**Downloads:**

```ts
const [download] = await Promise.all([
  page.waitForEvent('download'),
  page.getByRole('button', { name: 'Export' }).click(),
]);
await download.saveAs('out/report.csv');
```

## ⚠️ Pitfalls [#️-pitfalls]

* `networkidle` flakes on apps with long-polling or analytics.
* Missing `await` on `goto` — race with next assertion.
* Absolute URLs ignoring `baseURL` in multi-env setups.
* Not handling client-side redirects with `waitForURL` / `toHaveURL`.
* Assuming same-tab navigation when target opens a popup.

## 🔗 Related [#-related]

* [Actions](/docs/playwright/actions)
* [Assertions](/docs/playwright/assertions)
* [Network](/docs/playwright/network)
* [Config](/docs/playwright/config)
* [Authentication](/docs/playwright/authentication)
* [Tracing](/docs/playwright/tracing)


# Network (/docs/playwright/network)



# Network [#network]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Intercept, mock, abort, and assert HTTP traffic with `page.route`, `page.waitForResponse`, and HAR. Useful for isolating UI from flaky backends.

## 🔧 Core concepts [#-core-concepts]

| API                                  | Purpose                     |
| ------------------------------------ | --------------------------- |
| `page.route`                         | Intercept matching requests |
| `route.fulfill`                      | Mock response               |
| `route.abort`                        | Block (ads, analytics)      |
| `route.continue`                     | Pass through / modify       |
| `waitForRequest` / `waitForResponse` | Sync on traffic             |
| `page.request`                       | Out-of-band API calls       |

Glob patterns: `**/api/users*`. RegExp also supported.

## 💡 Examples [#-examples]

**Mock JSON:**

```ts
await page.route('**/api/users', async (route) => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify([{ id: 1, name: 'Ada' }]),
  });
});
await page.goto('/users');
await expect(page.getByText('Ada')).toBeVisible();
```

**Abort & modify:**

```ts
await page.route('**/*.{png,jpg}', (route) => route.abort());
await page.route('**/api/**', async (route) => {
  const headers = { ...route.request().headers(), 'X-Test': '1' };
  await route.continue({ headers });
});
```

**Wait for response:**

```ts
const [response] = await Promise.all([
  page.waitForResponse((r) =>
    r.url().includes('/api/save') && r.status() === 200
  ),
  page.getByRole('button', { name: 'Save' }).click(),
]);
expect(await response.json()).toMatchObject({ ok: true });
```

**HAR replay:**

```ts
await context.routeFromHAR('hars/checkout.har', {
  url: '**/api/**',
  update: false,
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Registering routes after navigation — set up before `goto`.
* Over-mocking hides contract bugs — balance with real API tests.
* Glob too broad (`**/*`) intercepts assets and slows tests.
* Forgetting `await route.fulfill()` hangs the request.
* CORS / service workers can bypass simple route handlers.

## 🔗 Related [#-related]

* [API testing](/docs/playwright/api-testing)
* [Authentication](/docs/playwright/authentication)
* [Navigation](/docs/playwright/navigation)
* [Assertions](/docs/playwright/assertions)
* [Tracing](/docs/playwright/tracing)
* [CI](/docs/playwright/ci)


# Page Object (/docs/playwright/page-object)



# Page Object [#page-object]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Page Object Model (POM) wraps locators and flows in classes/modules so specs stay readable. Prefer composition and fixtures over deep inheritance.

## 🔧 Core concepts [#-core-concepts]

| Piece      | Responsibility                    |
| ---------- | --------------------------------- |
| Page class | Locators + actions for one screen |
| Component  | Reusable widget (nav, dialog)     |
| Fixture    | Construct POM with `page`         |
| Spec       | Arrange / act / assert only       |

Keep assertions in tests (or thin expect helpers), not buried only inside pages.

## 💡 Examples [#-examples]

**Page class:**

```ts
import { type Page, type Locator } from '@playwright/test';

export class LoginPage {
  readonly email: Locator;
  readonly password: Locator;
  readonly submit: Locator;

  constructor(private readonly page: Page) {
    this.email = page.getByLabel('Email');
    this.password = page.getByLabel('Password');
    this.submit = page.getByRole('button', { name: 'Sign in' });
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.email.fill(email);
    await this.password.fill(password);
    await this.submit.click();
  }
}
```

**Fixture wiring:**

```ts
export const test = base.extend<{ loginPage: LoginPage }>({
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page));
  },
});

test('signs in', async ({ loginPage, page }) => {
  await loginPage.goto();
  await loginPage.login('ada@ex.com', 'secret');
  await expect(page).toHaveURL(/home/);
});
```

**Component example:**

```ts
export class Nav {
  constructor(private page: Page) {}
  link(name: string) {
    return this.page.getByRole('navigation').getByRole('link', { name });
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* God-objects with every selector in the app.
* Returning raw CSS strings instead of Locators.
* Duplicating waits inside every method — trust locator auto-wait.
* Assertions-only pages that hide failures from the report title.
* Over-abstracting one-off screens used by a single test.

## 🔗 Related [#-related]

* [Fixtures](/docs/playwright/fixtures)
* [Locators](/docs/playwright/locators)
* [Actions](/docs/playwright/actions)
* [Authentication](/docs/playwright/authentication)
* [Assertions](/docs/playwright/assertions)
* [Codegen](/docs/playwright/codegen)


# Parallel (/docs/playwright/parallel)



# Parallel [#parallel]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Playwright runs tests in parallel across workers and shards. Isolate state, avoid shared mutable resources, and tune workers for CI hardware.

## 🔧 Core concepts [#-core-concepts]

| Control                               | Effect                          |
| ------------------------------------- | ------------------------------- |
| `fullyParallel`                       | Parallelize tests inside a file |
| `workers`                             | Process count                   |
| `shard`                               | Split suite across machines     |
| `test.describe.configure(\{ mode \})` | `parallel` / `serial`           |
| Project dependencies                  | Setup before dependents         |

Each worker gets its own browser; contexts isolate cookies/storage.

## 💡 Examples [#-examples]

**Config:**

```ts
export default defineConfig({
  fullyParallel: true,
  workers: process.env.CI ? 2 : undefined,
});
```

**Serial describe (order matters):**

```ts
test.describe.configure({ mode: 'serial' });
test.describe('checkout flow', () => {
  test('add to cart', async ({ page }) => { /* ... */ });
  test('pay', async ({ page }) => { /* ... */ });
});
```

**Sharding in CI:**

```shellscript
npx playwright test --shard=1/3
npx playwright test --shard=2/3
npx playwright test --shard=3/3
```

**Limit parallelism for a file:**

```ts
test.describe.configure({ mode: 'default' }); // file-level sequential workers
```

**Worker index for unique data:**

```ts
test('unique user', async ({}, testInfo) => {
  const email = `user-${testInfo.parallelIndex}@ex.com`;
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Shared DB rows / accounts without unique keys → cross-test collisions.
* `workers: 1` everywhere hides local parallelism bugs until CI.
* Serial suites that are unnecessarily long — prefer independent tests.
* Uneven shards when heavy tests cluster in one file.
* Relying on test order outside `serial` mode.

## 🔗 Related [#-related]

* [Config](/docs/playwright/config)
* [CI](/docs/playwright/ci)
* [Fixtures](/docs/playwright/fixtures)
* [Authentication](/docs/playwright/authentication)
* [Tracing](/docs/playwright/tracing)
* [Page object](/docs/playwright/page-object)


# Screenshots & Video (/docs/playwright/screenshots-video)



# Screenshots & Video [#screenshots--video]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Capture screenshots and video for debugging and visual checks. Configure globally in `use`, or call APIs ad hoc in tests.

## 🔧 Core concepts [#-core-concepts]

| Option            | Values                                                   |
| ----------------- | -------------------------------------------------------- |
| `screenshot`      | `off` \| `on` \| `only-on-failure`                       |
| `video`           | `off` \| `on` \| `retain-on-failure` \| `on-first-retry` |
| `page.screenshot` | Full page / element / clip                               |
| Trace             | Separate — includes snapshots                            |

Videos are WebM; screenshots PNG by default.

## 💡 Examples [#-examples]

**Config:**

```ts
use: {
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
},
```

**Manual screenshots:**

```ts
await page.screenshot({ path: 'artifacts/home.png', fullPage: true });
await page.getByTestId('chart').screenshot({ path: 'artifacts/chart.png' });
await page.screenshot({
  path: 'clip.png',
  clip: { x: 0, y: 0, width: 800, height: 600 },
});
```

**Mask sensitive UI:**

```ts
await page.screenshot({
  path: 'masked.png',
  mask: [page.getByTestId('ssn'), page.getByLabel('Card number')],
});
```

**Element + animations:**

```ts
await page.screenshot({
  path: 'stable.png',
  animations: 'disabled',
  caret: 'hide',
});
```

Artifacts land under `test-results/` with HTML report links when using the html reporter.

## ⚠️ Pitfalls [#️-pitfalls]

* `video: 'on'` for all tests fills disks quickly.
* Full-page screenshots of infinite scroll pages are huge/slow.
* Flaky pixels from fonts, DPI, and animations — prefer visual comparison APIs.
* Paths outside `test-results` may not attach to the HTML report.
* Recording video in headed debug sessions without cleanup.

## 🔗 Related [#-related]

* [Visual comparisons](/docs/playwright/visual-comparisons)
* [Tracing](/docs/playwright/tracing)
* [Config](/docs/playwright/config)
* [CI](/docs/playwright/ci)
* [Assertions](/docs/playwright/assertions)
* [Parallel](/docs/playwright/parallel)


# Tracing (/docs/playwright/tracing)



# Tracing [#tracing]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Traces capture DOM snapshots, network, console, and actions for post-mortem debugging. Open with `npx playwright show-trace` or the HTML report.

## 🔧 Core concepts [#-core-concepts]

| Mode                | Behavior            |
| ------------------- | ------------------- |
| `off`               | No traces           |
| `on`                | Every test          |
| `retain-on-failure` | Keep if failed      |
| `on-first-retry`    | Recommended default |

Trace viewer shows timeline, before/after snapshots, source, and network.

## 💡 Examples [#-examples]

**Config (recommended):**

```ts
use: {
  trace: 'on-first-retry',
},
retries: process.env.CI ? 2 : 0,
```

**CLI:**

```shellscript
npx playwright test --trace on
npx playwright show-trace test-results/.../trace.zip
npx playwright show-report
```

**Programmatic:**

```ts
await browser.startTracing(page, { path: 'trace.json', screenshots: true });
// ... actions
await browser.stopTracing();
```

Prefer context tracing via config over low-level Chrome tracing.

**Debug locally:**

```shellscript
PWDEBUG=1 npx playwright test
npx playwright test --debug
npx playwright test --ui
```

UI mode includes time-travel and locator picker; traces complement CI failures.

## ⚠️ Pitfalls [#️-pitfalls]

* `trace: 'on'` in large suites → huge artifacts and slow uploads.
* Not downloading CI artifacts — traces stay on the runner.
* Comparing traces across different browsers without noting engine differences.
* Expecting traces without retries when using `on-first-retry`.
* Zipping/custom paths that the HTML reporter cannot find.

## 🔗 Related [#-related]

* [Config](/docs/playwright/config)
* [Screenshots & video](/docs/playwright/screenshots-video)
* [CI](/docs/playwright/ci)
* [Parallel](/docs/playwright/parallel)
* [Assertions](/docs/playwright/assertions)
* [Network](/docs/playwright/network)


# Visual Comparisons (/docs/playwright/visual-comparisons)



# Visual Comparisons [#visual-comparisons]

*Playwright · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`toHaveScreenshot` and `toMatchSnapshot` compare pixels/text against committed baselines. Stabilize fonts, animations, and dynamic data before trusting diffs.

## 🔧 Core concepts [#-core-concepts]

| API                                   | Use                      |
| ------------------------------------- | ------------------------ |
| `expect(page).toHaveScreenshot()`     | Full page / viewport     |
| `expect(locator).toHaveScreenshot()`  | Element                  |
| `maxDiffPixels` / `maxDiffPixelRatio` | Tolerance                |
| `stylePath`                           | Inject CSS for stability |
| Update flag                           | `--update-snapshots`     |

Baselines are platform-specific (OS + browser). Generate on the same CI image you run.

## 💡 Examples [#-examples]

**Page screenshot assert:**

```ts
await expect(page).toHaveScreenshot('home.png', {
  animations: 'disabled',
  caret: 'hide',
  maxDiffPixelRatio: 0.01,
});
```

**Element + mask:**

```ts
await expect(page.getByTestId('hero')).toHaveScreenshot({
  mask: [page.getByTestId('clock'), page.getByTestId('avatar')],
});
```

**Config defaults:**

```ts
expect: {
  toHaveScreenshot: {
    maxDiffPixels: 50,
    animations: 'disabled',
  },
},
```

**Update baselines:**

```shellscript
npx playwright test --update-snapshots
npx playwright test --update-snapshots --project=chromium
```

**Text snapshot:**

```ts
expect(await page.locator('pre').textContent()).toMatchSnapshot('dump.txt');
```

## ⚠️ Pitfalls [#️-pitfalls]

* Generating snapshots on Windows and comparing on Linux CI.
* Unmasked timestamps, ads, or lazy-loaded images.
* Fonts not installed in CI → different glyph metrics.
* Animations/caret blinking causing 1-pixel flakes.
* Committing huge full-site screenshots without masking.

## 🔗 Related [#-related]

* [Screenshots & video](/docs/playwright/screenshots-video)
* [Assertions](/docs/playwright/assertions)
* [CI](/docs/playwright/ci)
* [Config](/docs/playwright/config)
* [Mobile emulation](/docs/playwright/mobile-emulation)
* [Tracing](/docs/playwright/tracing)


# Asserts (/docs/pytest/asserts)



# Asserts [#asserts]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

pytest rewrites `assert` for rich introspection — no special assert API required. Use `pytest.raises`, `approx`, and helper matchers for exceptions and floats.

## 🔧 Core concepts [#-core-concepts]

| Tool               | Use                              |
| ------------------ | -------------------------------- |
| `assert`           | Equality, membership, truthiness |
| `pytest.raises`    | Expect exceptions                |
| `pytest.approx`    | Float tolerance                  |
| `pytest.warns`     | Expect warnings                  |
| `unittest` asserts | Still work if preferred          |

Assertion rewriting applies to test modules; helper modules may need `pytest.register_assert_rewrite`.

## 💡 Examples [#-examples]

**Basics:**

```python
def test_list():
    data = [1, 2, 3]
    assert data == [1, 2, 3]
    assert 2 in data
    assert len(data) == 3
```

**Exceptions:**

```python
import pytest

def test_raises():
    with pytest.raises(ZeroDivisionError):
        1 / 0

def test_message():
    with pytest.raises(ValueError, match="invalid"):
        raise ValueError("invalid id")
```

**Approx & warnings:**

```python
assert 0.1 + 0.2 == pytest.approx(0.3)
assert [0.1, 0.2] == pytest.approx([0.1, 0.2])

with pytest.warns(UserWarning, match="deprecated"):
    warn_user()
```

**Failure messages:**

```python
assert result.ok, f"expected ok, got {result!r}"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Writing `assertEqual` from unittest without need — plain assert is fine.
* Comparing floats with `==` without `approx`.
* Catching exceptions with try/except instead of `pytest.raises`.
* Huge diffs from comparing large dicts — use focused keys.
* Assert rewriting disabled in some imported helpers.

## 🔗 Related [#-related]

* [Fixtures](/docs/pytest/fixtures)
* [Parametrize](/docs/pytest/parametrize)
* [Mocking](/docs/pytest/mocking)
* [capsys & caplog](/docs/pytest/capsys-caplog)
* [CLI](/docs/pytest/cli)
* [Coverage](/docs/pytest/coverage)


# Asyncio (/docs/pytest/asyncio-pytest)



# Asyncio [#asyncio]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`pytest-asyncio` runs `async def` tests and fixtures. Modern default is `asyncio_mode = auto` so marked or auto-detected coroutines work cleanly.

## 🔧 Core concepts [#-core-concepts]

| Piece                 | Role                                 |
| --------------------- | ------------------------------------ |
| `pytest.mark.asyncio` | Mark async test (strict mode)        |
| `asyncio_mode`        | `strict` \| `auto`                   |
| Async fixtures        | `async def` + await setup            |
| `event_loop`          | Legacy loop fixture (avoid new code) |
| `AsyncMock`           | Mock awaitables                      |

Prefer one event loop policy per process; be careful with xdist.

## 💡 Examples [#-examples]

**Install & config:**

```shellscript
python -m pip install pytest-asyncio
```

```toml
[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
```

**Async test:**

```python
import pytest
import httpx

@pytest.mark.asyncio
async def test_ping():
    async with httpx.AsyncClient() as client:
        r = await client.get("https://example.com")
    assert r.status_code == 200
```

With `asyncio_mode = auto`, the mark is optional for async tests.

**Async fixture:**

```python
@pytest.fixture
async def db_pool():
    pool = await create_pool()
    yield pool
    await pool.close()

async def test_row(db_pool):
    assert await db_pool.fetchval("SELECT 1") == 1
```

**Mock async:**

```python
from unittest.mock import AsyncMock

async def test_service():
    fetch = AsyncMock(return_value={"id": 1})
    assert await fetch() == {"id": 1}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing sync fixtures that block the loop heavily.
* Forgetting `await` on coroutine mocks → always-true assertions.
* Session-scoped async fixtures with function-scoped loops.
* Sharing aiohttp/httpx clients across tests without reset.
* Nested event loops (`asyncio.run` inside async tests).

## 🔗 Related [#-related]

* [Install](/docs/pytest/install)
* [Fixtures](/docs/pytest/fixtures)
* [Mocking](/docs/pytest/mocking)
* [Plugins](/docs/pytest/plugins)
* [Configuration](/docs/pytest/configuration)
* [xdist](/docs/pytest/xdist)


# capsys & caplog (/docs/pytest/capsys-caplog)



# capsys & caplog [#capsys--caplog]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`capsys` / `capfd` capture stdout/stderr; `caplog` captures logging records. Use them to assert CLI output and log messages without polluting the terminal.

## 🔧 Core concepts [#-core-concepts]

| Fixture           | Captures                |
| ----------------- | ----------------------- |
| `capsys`          | sys.stdout / sys.stderr |
| `capfd`           | OS-level fd 1/2         |
| `capsysbinary`    | Binary stdout/stderr    |
| `caplog`          | logging module records  |
| `caplog.at_level` | Temporary level         |

`readouterr()` returns a named tuple `(out, err)` and clears buffers.

## 💡 Examples [#-examples]

**stdout:**

```python
def test_cli(capsys):
    print("hello")
    captured = capsys.readouterr()
    assert captured.out == "hello\n"
```

**Disable capture temporarily:**

```python
def test_debug(capsys):
    with capsys.disabled():
        print("visible during test")
```

**Logging:**

```python
import logging

def test_log(caplog):
    logger = logging.getLogger("app")
    with caplog.at_level(logging.INFO, logger="app"):
        logger.info("started")
        logger.error("boom")
    assert "started" in caplog.text
    assert any(r.levelname == "ERROR" for r in caplog.records)
```

**capfd for C extensions / subprocess writing to fd:**

```python
def test_fd(capfd):
    import os
    os.write(1, b"raw\n")
    assert "raw" in capfd.readouterr().out
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `readouterr()` clears — second call is empty.
* Using `capsys` when the code writes via OS fds — use `capfd`.
* Asserting on log format strings instead of message/record fields.
* Leaving logger level too high and capturing nothing.
* Relying on capture order with concurrent threads.

## 🔗 Related [#-related]

* [Fixtures](/docs/pytest/fixtures)
* [Asserts](/docs/pytest/asserts)
* [CLI](/docs/pytest/cli)
* [Mocking](/docs/pytest/mocking)
* [tmp\_path](/docs/pytest/tmp-path)
* [conftest](/docs/pytest/conftest)


# CLI (/docs/pytest/cli)



# CLI [#cli]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The pytest CLI selects tests, controls verbosity, stops on failure, and passes plugin options. Learn a small set of flags for daily use and CI.

## 🔧 Core concepts [#-core-concepts]

| Flag            | Purpose                    |
| --------------- | -------------------------- |
| `-q` / `-v`     | Quiet / verbose            |
| `-x`            | Stop on first failure      |
| `--lf` / `--ff` | Last failed / failed first |
| `-k EXPR`       | Name expression            |
| `-m EXPR`       | Mark expression            |
| `-s`            | No capture (show print)    |
| `--pdb`         | Drop into debugger         |
| `--maxfail=N`   | Stop after N failures      |
| `-n`            | xdist workers              |

Node id: `path/test_file.py::TestClass::test_name`.

## 💡 Examples [#-examples]

**Selection:**

```shellscript
pytest tests/test_api.py
pytest tests/test_api.py::test_health
pytest -k "user and not slow"
pytest -m "not integration"
```

**Debugging:**

```shellscript
pytest -x --pdb
pytest --lf
pytest -vv -s
pytest --trace   # break at start of each test
```

**Output & reports:**

```shellscript
pytest -ra
pytest --tb=short
pytest --junitxml=report.xml
```

**Useful combos:**

```shellscript
pytest -q --cov=myapp --cov-report=term-missing
pytest -n auto -m "not slow"
pytest --durations=10
```

**Collect only:**

```shellscript
pytest --collect-only -q
```

## ⚠️ Pitfalls [#️-pitfalls]

* `-s` flooding CI logs.
* Overusing `-k` strings that silently match nothing useful.
* Forgetting quotes around mark expressions in shells.
* Running from the wrong cwd so `testpaths` miss files.
* Passing pytest args after `--` incorrectly in some wrappers.

## 🔗 Related [#-related]

* [Configuration](/docs/pytest/configuration)
* [Markers](/docs/pytest/markers)
* [Coverage](/docs/pytest/coverage)
* [xdist](/docs/pytest/xdist)
* [Install](/docs/pytest/install)
* [Asserts](/docs/pytest/asserts)


# Configuration (/docs/pytest/configuration)



# Configuration [#configuration]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Configure pytest in `pytest.ini`, `pyproject.toml`, or `tox.ini`. Prefer `[tool.pytest.ini_options]` in modern projects; keep discovery and defaults versioned.

## 🔧 Core concepts [#-core-concepts]

| Key                                        | Role                     |
| ------------------------------------------ | ------------------------ |
| `testpaths`                                | Where to look            |
| `python_files` / `_classes` / `_functions` | Discovery patterns       |
| `addopts`                                  | Default CLI flags        |
| `markers`                                  | Register marks           |
| `filterwarnings`                           | Warning policy           |
| `minversion`                               | Require pytest version   |
| `pythonpath`                               | Import roots (pytest 7+) |

INI values are strings; TOML can use lists.

## 💡 Examples [#-examples]

**pyproject.toml:**

```toml
[tool.pytest.ini_options]
minversion = "8.0"
testpaths = ["tests"]
pythonpath = ["src"]
addopts = [
  "-ra",
  "--strict-markers",
  "--strict-config",
]
markers = [
  "slow: long tests",
  "integration: needs services",
]
filterwarnings = [
  "error",
  "ignore::DeprecationWarning:legacy_pkg.*",
]
```

**pytest.ini equivalent:**

```ini
[pytest]
testpaths = tests
addopts = -ra --strict-markers
markers =
    slow: long tests
```

**Env:**

```shellscript
export PYTEST_ADDOPTS="-q --tb=short"
```

**Per-directory:** nested `conftest.py` + local `pytest.ini` (rare; prefer one root config).

## ⚠️ Pitfalls [#️-pitfalls]

* Duplicate config in both `pytest.ini` and `pyproject.toml` — one source of truth.
* `addopts` including `--cov` making bare `pytest` slow for quick runs.
* Forgetting `--strict-markers` then typos silently create new marks.
* Wrong `pythonpath` masking packaging issues.
* Setting `norecursedirs` too aggressively and skipping test folders.

## 🔗 Related [#-related]

* [Install](/docs/pytest/install)
* [CLI](/docs/pytest/cli)
* [Markers](/docs/pytest/markers)
* [conftest](/docs/pytest/conftest)
* [Plugins](/docs/pytest/plugins)
* [Coverage](/docs/pytest/coverage)


# conftest (/docs/pytest/conftest)



# conftest [#conftest]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`conftest.py` holds shared fixtures, hooks, and plugins discovered by directory proximity. Nested conftests apply to their subtree; no import needed in tests.

## 🔧 Core concepts [#-core-concepts]

| Feature          | Role                                                |
| ---------------- | --------------------------------------------------- |
| Local fixtures   | Visible to sibling/child tests                      |
| Hooks            | `pytest_configure`, `pytest_collection_modifyitems` |
| `pytest_plugins` | Load plugin modules                                 |
| Directory scope  | Closest conftest wins for overrides                 |

Do not put `conftest.py` in importable app packages if it confuses packaging.

## 💡 Examples [#-examples]

**Shared fixture:**

```python
# tests/conftest.py
import pytest

@pytest.fixture
def client(app):
    return app.test_client()
```

**Hook — skip by mark in CI:**

```python
# tests/conftest.py
import os
import pytest

def pytest_collection_modifyitems(config, items):
    if os.getenv("CI"):
        return
    skip_ci = pytest.mark.skip(reason="CI only")
    for item in items:
        if "ci_only" in item.keywords:
            item.add_marker(skip_ci)
```

**Nested override:**

```plaintext
tests/
  conftest.py          # db fixture (sqlite)
  api/
    conftest.py        # db fixture (postgres) overrides for api/
    test_users.py
```

**Register plugin:**

```python
pytest_plugins = ["tests.plugins.db"]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Circular imports between conftest and application code.
* Putting secrets in conftest committed to git.
* Too many session fixtures in root conftest slowing collection.
* Expecting conftest fixtures across unrelated directories.
* Naming conflicts when two conftests define the same fixture name.

## 🔗 Related [#-related]

* [Fixtures](/docs/pytest/fixtures)
* [Plugins](/docs/pytest/plugins)
* [Configuration](/docs/pytest/configuration)
* [Markers](/docs/pytest/markers)
* [tmp\_path](/docs/pytest/tmp-path)
* [Django pytest](/docs/pytest/django-pytest)


# Coverage (/docs/pytest/coverage)



# Coverage [#coverage]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`pytest-cov` integrates coverage.py: measure line/branch coverage, fail under thresholds, and emit terminal/HTML/XML reports for CI.

## 🔧 Core concepts [#-core-concepts]

| Flag                 | Meaning                |
| -------------------- | ---------------------- |
| `--cov=pkg`          | Measure package        |
| `--cov-report=`      | term, html, xml        |
| `--cov-fail-under=N` | Exit non-zero if below |
| `--cov-branch`       | Branch coverage        |
| `omit` / `include`   | Scope in `.coveragerc` |

Run from project root so paths resolve correctly.

## 💡 Examples [#-examples]

**CLI:**

```shellscript
pytest --cov=myapp --cov-report=term-missing
pytest --cov=myapp --cov-report=html --cov-report=xml
pytest --cov=myapp --cov-fail-under=85 --cov-branch
```

**pyproject.toml:**

```toml
[tool.coverage.run]
source = ["myapp"]
branch = true
omit = ["*/tests/*", "*/migrations/*"]

[tool.coverage.report]
show_missing = true
skip_covered = false
fail_under = 85

[tool.pytest.ini_options]
addopts = "--cov=myapp --cov-report=term-missing"
```

**HTML:** open `htmlcov/index.html`.

**CI:** publish `coverage.xml` to Codecov/Sonar; keep thresholds realistic for new projects.

## ⚠️ Pitfalls [#️-pitfalls]

* Measuring tests or virtualenv paths — set `source`/`omit`.
* 100% line coverage with zero meaningful assertions.
* Combining xdist without `pytest-cov` concurrency support configured.
* Dynamic imports / `# pragma: no cover` abused to hide gaps.
* Different coverage between local and CI due to optional extras.

## 🔗 Related [#-related]

* [Install](/docs/pytest/install)
* [CLI](/docs/pytest/cli)
* [Configuration](/docs/pytest/configuration)
* [xdist](/docs/pytest/xdist)
* [Plugins](/docs/pytest/plugins)
* [Asserts](/docs/pytest/asserts)


# Django pytest (/docs/pytest/django-pytest)



# Django pytest [#django-pytest]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`pytest-django` replaces `manage.py test` with pytest fixtures: `client`, `admin_client`, `db`, `django_user_model`, and DB access markers.

## 🔧 Core concepts [#-core-concepts]

| Fixture / mark     | Role               |
| ------------------ | ------------------ |
| `db` / `django_db` | Enable DB access   |
| `client`           | Django test client |
| `admin_client`     | Logged-in staff    |
| `rf`               | RequestFactory     |
| `settings`         | Override settings  |
| `live_server`      | Live HTTP server   |

Configure `DJANGO_SETTINGS_MODULE` in pytest config or env.

## 💡 Examples [#-examples]

**Install:**

```shellscript
python -m pip install pytest-django
```

```toml
[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "myproject.settings"
python_files = ["tests.py", "test_*.py", "*_tests.py"]
```

**View test:**

```python
import pytest

@pytest.mark.django_db
def test_home(client):
    res = client.get("/")
    assert res.status_code == 200
```

**Model + user:**

```python
@pytest.mark.django_db
def test_user(django_user_model):
    u = django_user_model.objects.create_user("ada", password="x")
    assert u.username == "ada"
```

**Settings override:**

```python
def test_debug(settings):
    settings.DEBUG = True
    assert settings.DEBUG is True
```

**Transactional / live:**

```python
@pytest.mark.django_db(transaction=True)
def test_signal():
    ...

@pytest.mark.django_db
def test_api(live_server, client):
    assert live_server.url.startswith("http")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Accessing DB without `django_db` / `db` fixture → error.
* Relying on migration state without `pytest-django` DB setup.
* Using unittest `TestCase` transactions mixed with pytest fixtures carelessly.
* Factory Boy / fixtures creating data without cleanup in non-db tests.
* Pointing `DJANGO_SETTINGS_MODULE` at production settings.

## 🔗 Related [#-related]

* [Fixtures](/docs/pytest/fixtures)
* [Markers](/docs/pytest/markers)
* [Configuration](/docs/pytest/configuration)
* [Plugins](/docs/pytest/plugins)
* [Mocking](/docs/pytest/mocking)
* [Install](/docs/pytest/install)


# Fixtures (/docs/pytest/fixtures)



# Fixtures [#fixtures]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Fixtures provide setup/teardown via dependency injection. Tests request fixtures by parameter name; scopes control lifetime (`function`, `class`, `module`, `package`, `session`).

## 🔧 Core concepts [#-core-concepts]

| Concept           | Meaning                      |
| ----------------- | ---------------------------- |
| `@pytest.fixture` | Define reusable resource     |
| `yield`           | Setup before, teardown after |
| `scope`           | How often to recreate        |
| `autouse`         | Apply without requesting     |
| `params`          | Parametrized fixture         |
| Fixture factory   | Return a creator callable    |

Prefer fixtures over setup/teardown methods for composability.

## 💡 Examples [#-examples]

**Basic yield fixture:**

```python
import pytest

@pytest.fixture
def db():
    conn = connect()
    yield conn
    conn.close()

def test_query(db):
    assert db.execute("SELECT 1").fetchone()[0] == 1
```

**Scopes:**

```python
@pytest.fixture(scope="session")
def app():
    return create_app()

@pytest.fixture(scope="module")
def client(app):
    return app.test_client()
```

**Factory:**

```python
@pytest.fixture
def make_user(db):
    created = []
    def _make(**kwargs):
        u = User(**kwargs)
        db.add(u)
        created.append(u)
        return u
    yield _make
    for u in created:
        db.delete(u)
```

**Autouse:**

```python
@pytest.fixture(autouse=True)
def _fast_cache(monkeypatch):
    monkeypatch.setenv("CACHE_URL", "memory://")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Session-scoped mutable state leaking between tests.
* Requesting heavy fixtures unnecessarily — keep scopes tight.
* Using `return` when teardown is needed — use `yield`.
* Circular fixture dependencies.
* Overusing `autouse` — hard to see what a test depends on.

## 🔗 Related [#-related]

* [conftest](/docs/pytest/conftest)
* [Parametrize](/docs/pytest/parametrize)
* [tmp\_path](/docs/pytest/tmp-path)
* [capsys & caplog](/docs/pytest/capsys-caplog)
* [Mocking](/docs/pytest/mocking)
* [Markers](/docs/pytest/markers)


# Glossary (/docs/pytest/glossary)



# Glossary [#glossary]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core Pytest terms for fixtures, assertions, markers, configuration, and test organization.

## 🔧 Core concepts [#-core-concepts]

| Term             | Definition                                                                        |
| ---------------- | --------------------------------------------------------------------------------- |
| Approx           | `pytest.approx` for comparing floating-point numbers with tolerance.              |
| Assert rewriting | Pytest’s enhancement of `assert` statements with rich failure introspection.      |
| Caplog           | A fixture that captures logging output during a test.                             |
| Capsys           | A fixture that captures writes to stdout and stderr.                              |
| Collection       | The phase where Pytest discovers and builds the test suite tree.                  |
| Conftest         | A `conftest.py` file that shares fixtures and hooks with a directory tree.        |
| Coverage         | Measurement of which code lines were executed by tests.                           |
| Fixture          | A reusable setup/teardown provider injected into tests by name.                   |
| Hook             | A plugin callback such as `pytest_runtest_setup` that extends Pytest.             |
| Marker           | A tag like `@pytest.mark.slow` used to select or skip tests.                      |
| Monkeypatch      | A fixture for temporarily changing attributes, env vars, or dict items.           |
| Node id          | The unique path identifying a collected test, used in selection.                  |
| Parametrize      | Running one test function multiple times with different argument sets.            |
| Plugin           | An extension package or module that adds fixtures, hooks, or CLI options.         |
| Pytest.ini       | A common configuration file for options, markers, and paths.                      |
| Raise            | Using `pytest.raises` to assert that code throws an expected exception.           |
| Request          | The fixture that gives access to the current test context and node.               |
| Scope            | How long a fixture lives: `function`, `class`, `module`, `package`, or `session`. |
| Skip             | Marking a test to not run, optionally with a reason.                              |
| Teardown         | Cleanup code that runs after a test or fixture yields.                            |
| Tmp\_path        | A fixture providing a unique temporary `pathlib.Path` per test.                   |
| Traceback        | The failure stack Pytest prints, often shortened for readability.                 |
| Usefixtures      | A marker that applies fixtures to a test or class without parameters.             |
| Xdist            | The `pytest-xdist` plugin that runs tests in parallel workers.                    |
| Xfail            | Expecting a test to fail; unexpected passes are reported specially.               |

## 💡 Examples [#-examples]

**Fixture and assert:**

```python
import pytest

@pytest.fixture
def user():
    return {"name": "Ada"}

def test_user_name(user):
    assert user["name"] == "Ada"
```

**Parametrize and markers:**

```python
@pytest.mark.parametrize("n,expected", [(1, 2), (2, 4)])
def test_double(n, expected):
    assert n * 2 == expected

@pytest.mark.slow
def test_integration():
    ...
```

**CLI selection:**

```shellscript
pytest -k "user and not slow" -q
pytest -m "not slow" --maxfail=1
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **skip** (do not run) with **xfail** (run, expect failure).
* Mixing **fixture scope** (`function` vs `session`) and accidentally sharing mutable state.
* Treating **conftest.py** like a normal importable module — discovery is directory-based.
* Equating **parametrize** ids with test names — node ids include parameters.
* Assuming plain **assert** elsewhere behaves like Pytest’s rewritten asserts.

## 🔗 Related [#-related]

* [fixtures](/docs/pytest/fixtures)
* [asserts](/docs/pytest/asserts)
* [parametrize](/docs/pytest/parametrize)
* [markers](/docs/pytest/markers)
* [conftest](/docs/pytest/conftest)
* [cli](/docs/pytest/cli)


# Pytest (/docs/pytest)



# Pytest [#pytest]

Python testing framework.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Install (/docs/pytest/install)



# Install [#install]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

pytest is the standard Python test runner: discovery, fixtures, asserts, plugins. Install into a venv; optional extras cover coverage, Django, asyncio, and xdist.

## 🔧 Core concepts [#-core-concepts]

| Package          | Role               |
| ---------------- | ------------------ |
| `pytest`         | Core runner        |
| `pytest-cov`     | Coverage           |
| `pytest-xdist`   | Parallel           |
| `pytest-asyncio` | Async tests        |
| `pytest-django`  | Django integration |

Discovery: `test_*.py`, `*_test.py`, `Test*` classes, `test_*` functions.

## 💡 Examples [#-examples]

**Install:**

```shellscript
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
python -m pip install -U pip
python -m pip install pytest pytest-cov
```

**Minimal test:**

```python
# tests/test_math.py
def test_add():
    assert 1 + 1 == 2
```

**Run:**

```shellscript
pytest
pytest -q
pytest tests/test_math.py::test_add
pytest -k "add and not slow"
```

**pyproject.toml:**

```toml
[project.optional-dependencies]
dev = ["pytest>=8.0", "pytest-cov>=5.0"]

[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
addopts = "-ra"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Running system `pytest` outside the venv → wrong packages.
* Putting tests next to app without `pythonpath` / src layout.
* Naming files `test.py` only — discovery still works but prefer packages.
* Mixing unittest discovery expectations with pytest layout.
* Forgetting `__init__.py` when import paths need packages (often optional).

## 🔗 Related [#-related]

* [Configuration](/docs/pytest/configuration)
* [CLI](/docs/pytest/cli)
* [Fixtures](/docs/pytest/fixtures)
* [Plugins](/docs/pytest/plugins)
* [Coverage](/docs/pytest/coverage)
* [xdist](/docs/pytest/xdist)


# Markers (/docs/pytest/markers)



# Markers [#markers]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Markers tag tests for selection, skipping, expected failure, and custom metadata. Register custom marks in config to avoid warnings.

## 🔧 Core concepts [#-core-concepts]

| Built-in          | Effect          |
| ----------------- | --------------- |
| `skip` / `skipif` | Do not run      |
| `xfail`           | Expected fail   |
| `parametrize`     | Multiple cases  |
| `usefixtures`     | Attach fixtures |
| `filterwarnings`  | Warning filters |

Custom: `@pytest.mark.slow`, `@pytest.mark.integration`, etc.

## 💡 Examples [#-examples]

**Skip / xfail:**

```python
import sys
import pytest

@pytest.mark.skip(reason="not ready")
def test_wip():
    ...

@pytest.mark.skipif(sys.platform == "win32", reason="posix only")
def test_fcntl():
    ...

@pytest.mark.xfail(reason="bug #123", strict=True)
def test_known_bug():
    assert False
```

**Custom marks + selection:**

```python
@pytest.mark.slow
def test_big_import():
    ...

# pytest -m "not slow"
# pytest -m "integration and not slow"
```

**Register in pyproject.toml:**

```toml
[tool.pytest.ini_options]
markers = [
  "slow: long-running tests",
  "integration: needs services",
]
```

**Class-level:**

```python
pytestmark = pytest.mark.integration

class TestAPI:
    def test_health(self):
        ...
```

## ⚠️ Pitfalls [#️-pitfalls]

* Unregistered marks → `PytestUnknownMarkWarning`.
* `xfail` without `strict=True` hiding unexpectedly passing tests.
* Overlapping mark expressions that select nothing silently.
* Using skip for environment issues better handled by fixtures.
* Marking entire modules accidentally via `pytestmark`.

## 🔗 Related [#-related]

* [CLI](/docs/pytest/cli)
* [Parametrize](/docs/pytest/parametrize)
* [Configuration](/docs/pytest/configuration)
* [Fixtures](/docs/pytest/fixtures)
* [Asserts](/docs/pytest/asserts)
* [Django pytest](/docs/pytest/django-pytest)


# Mocking (/docs/pytest/mocking)



# Mocking [#mocking]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Isolate units with `monkeypatch`, `unittest.mock`, or `pytest-mock`'s `mocker`. Patch where the name is looked up, not where it is defined.

## 🔧 Core concepts [#-core-concepts]

| Tool                  | Strength                      |
| --------------------- | ----------------------------- |
| `monkeypatch`         | Built-in, env/attrs/dicts     |
| `mocker`              | Convenient MagickMock helpers |
| `unittest.mock`       | patch, Mock, AsyncMock        |
| `respx` / `responses` | HTTP mocking                  |
| `freezegun`           | Time                          |

Prefer fakes/fakes over mocks when behavior matters.

## 💡 Examples [#-examples]

**monkeypatch:**

```python
def test_home(monkeypatch, tmp_path):
    monkeypatch.setenv("HOME", str(tmp_path))
    monkeypatch.setattr("app.service.fetch", lambda: {"ok": True})
    monkeypatch.delenv("SECRET", raising=False)
```

**pytest-mock:**

```python
def test_send(mocker):
    send = mocker.patch("app.mail.send_email", return_value=True)
    assert do_invite("a@b.com") is True
    send.assert_called_once_with("a@b.com")
```

**unittest.mock:**

```python
from unittest.mock import patch, MagicMock

@patch("app.db.Session")
def test_query(Session):
    Session.return_value.query.return_value = []
    assert list_users() == []
```

**Async:**

```python
async def test_async(mocker):
    mocker.patch("app.api.fetch", new_callable=mocker.AsyncMock, return_value=1)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Patching the definition site instead of the import site.
* Over-mocking until the test asserts only the mock.
* Leaving patches active without context managers / fixtures.
* Mocking timestamps without also freezing related clocks.
* Asserting call order when concurrency makes it nondeterministic.

## 🔗 Related [#-related]

* [Fixtures](/docs/pytest/fixtures)
* [Asserts](/docs/pytest/asserts)
* [asyncio](/docs/pytest/asyncio-pytest)
* [Plugins](/docs/pytest/plugins)
* [tmp\_path](/docs/pytest/tmp-path)
* [capsys & caplog](/docs/pytest/capsys-caplog)


# Parametrize (/docs/pytest/parametrize)



# Parametrize [#parametrize]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`@pytest.mark.parametrize` runs one test body with many inputs. Combine with fixture params and `pytest.param` for ids, marks, and expected exceptions.

## 🔧 Core concepts [#-core-concepts]

| Form                        | Use                |
| --------------------------- | ------------------ |
| `@pytest.mark.parametrize`  | Table-driven tests |
| `ids=`                      | Readable node ids  |
| `pytest.param(..., marks=)` | Per-row marks      |
| Indirect parametrization    | Feed fixtures      |
| Stacked parametrize         | Cartesian product  |

## 💡 Examples [#-examples]

**Simple table:**

```python
import pytest

@pytest.mark.parametrize(
    "a,b,expected",
    [
        (1, 1, 2),
        (2, 3, 5),
        (-1, 1, 0),
    ],
)
def test_add(a, b, expected):
    assert a + b == expected
```

**Ids & marks:**

```python
@pytest.mark.parametrize(
    "value",
    [
        pytest.param(1, id="one"),
        pytest.param(0, marks=pytest.mark.xfail(reason="zero")),
        pytest.param(-1, marks=pytest.mark.skip(reason="neg")),
    ],
)
def test_value(value):
    assert value > 0
```

**Indirect:**

```python
@pytest.fixture
def user(request):
    return User(role=request.param)

@pytest.mark.parametrize("user", ["admin", "guest"], indirect=True)
def test_access(user):
    assert user.role in {"admin", "guest"}
```

**Cartesian:**

```python
@pytest.mark.parametrize("x", [1, 2])
@pytest.mark.parametrize("y", ["a", "b"])
def test_grid(x, y):
    assert f"{x}{y}"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Huge cartesian products exploding CI time.
* Unhashable / huge objects as params — use factories/ids.
* Duplicate ids causing confusion in reports.
* Putting setup logic in params instead of fixtures.
* Over-parametrizing when a property-based test fits better.

## 🔗 Related [#-related]

* [Fixtures](/docs/pytest/fixtures)
* [Markers](/docs/pytest/markers)
* [Asserts](/docs/pytest/asserts)
* [CLI](/docs/pytest/cli)
* [conftest](/docs/pytest/conftest)
* [xdist](/docs/pytest/xdist)


# Plugins (/docs/pytest/plugins)



# Plugins [#plugins]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Plugins extend pytest via entry points or local modules. Popular ones cover coverage, Django, asyncio, timeouts, random order, and HTML reports.

## 🔧 Core concepts [#-core-concepts]

| Plugin           | Purpose          |
| ---------------- | ---------------- |
| `pytest-cov`     | Coverage         |
| `pytest-xdist`   | Parallel         |
| `pytest-asyncio` | Async            |
| `pytest-django`  | Django           |
| `pytest-timeout` | Hang protection  |
| `pytest-mock`    | `mocker` fixture |
| `pytest-html`    | HTML report      |

Local plugins: modules with hooks, loaded via `pytest_plugins` or `-p`.

## 💡 Examples [#-examples]

**Install common set:**

```shellscript
python -m pip install pytest-cov pytest-xdist pytest-asyncio pytest-mock
```

**Minimal local plugin:**

```python
# tests/plugins/env.py
def pytest_addoption(parser):
    parser.addoption("--runslow", action="store_true")

def pytest_configure(config):
    config.addinivalue_line("markers", "slow: slow tests")
```

```python
# conftest.py
pytest_plugins = ["tests.plugins.env"]
```

**List plugins:**

```shellscript
pytest --trace-config
pytest -p no:cacheprovider
```

**Entry-point plugin sketch:**

```python
# myplugin.py
def pytest_runtest_setup(item):
    if "network" in item.keywords and not item.config.getoption("--network"):
        pytest.skip("needs --network")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Plugin version skew with pytest major upgrades.
* Loading the same plugin twice (entry point + pytest\_plugins).
* Order-dependent plugins mutating collection unexpectedly.
* Disabling builtin plugins accidentally with `-p no:...`.
* Heavy plugins imported at collection time slowing startup.

## 🔗 Related [#-related]

* [Install](/docs/pytest/install)
* [conftest](/docs/pytest/conftest)
* [Coverage](/docs/pytest/coverage)
* [xdist](/docs/pytest/xdist)
* [asyncio](/docs/pytest/asyncio-pytest)
* [Mocking](/docs/pytest/mocking)


# tmp_path (/docs/pytest/tmp-path)



# tmp\_path [#tmp_path]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`tmp_path` and `tmp_path_factory` give per-test (or session) temporary directories as `pathlib.Path`. Prefer them over manual `tempfile` cleanup.

## 🔧 Core concepts [#-core-concepts]

| Fixture            | Scope                               |
| ------------------ | ----------------------------------- |
| `tmp_path`         | Unique dir per test function        |
| `tmp_path_factory` | Create extra dirs; session-friendly |
| `tmpdir`           | Legacy py.path — prefer `tmp_path`  |
| basetemp           | `--basetemp=` keeps dirs for debug  |

pytest cleans default temp roots between runs unless basetemp is set.

## 💡 Examples [#-examples]

**Write files:**

```python
def test_config(tmp_path):
    cfg = tmp_path / "config.toml"
    cfg.write_text('[app]\nname = "demo"\n', encoding="utf-8")
    assert "demo" in cfg.read_text(encoding="utf-8")
```

**Nested layout:**

```python
def test_project(tmp_path):
    src = tmp_path / "src"
    src.mkdir()
    (src / "main.py").write_text("print(1)\n", encoding="utf-8")
    assert (tmp_path / "src" / "main.py").exists()
```

**Factory (session):**

```python
import pytest

@pytest.fixture(scope="session")
def dataset_dir(tmp_path_factory):
    root = tmp_path_factory.mktemp("data")
    (root / "sample.csv").write_text("a,b\n1,2\n", encoding="utf-8")
    return root
```

**Keep on failure:**

```shellscript
pytest --basetemp=./.pytest-tmp
```

## ⚠️ Pitfalls [#️-pitfalls]

* Storing secrets in tmp dirs on shared CI runners.
* Assuming `tmp_path` survives across tests — it does not.
* Using string paths with APIs that need `Path` or vice versa.
* Parallel xdist workers — each has isolated temps; don't hardcode shared paths.
* Preferring `tmpdir` in new code (deprecated style).

## 🔗 Related [#-related]

* [Fixtures](/docs/pytest/fixtures)
* [capsys & caplog](/docs/pytest/capsys-caplog)
* [conftest](/docs/pytest/conftest)
* [Mocking](/docs/pytest/mocking)
* [CLI](/docs/pytest/cli)
* [xdist](/docs/pytest/xdist)


# xdist (/docs/pytest/xdist)



# xdist [#xdist]

*Pytest · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`pytest-xdist` runs tests in parallel across CPUs or distributed workers. Use `-n auto` locally; ensure tests are isolated (no shared files/DB rows).

## 🔧 Core concepts [#-core-concepts]

| Flag               | Meaning                 |
| ------------------ | ----------------------- |
| `-n N` / `-n auto` | Worker count            |
| `--dist loadscope` | Group by module/class   |
| `--dist loadfile`  | Keep file on one worker |
| `--looponfail`     | Re-run on change (dev)  |
| `worker_id`        | `gw0`, `master`, etc.   |

Each worker is a separate process with its own imports and fixtures (session fixtures run per worker).

## 💡 Examples [#-examples]

**Install & run:**

```shellscript
python -m pip install pytest-xdist
pytest -n auto
pytest -n 4 --dist loadscope
```

**Unique resources per worker:**

```python
import os
import pytest

@pytest.fixture(scope="session")
def db_name(worker_id):
    if worker_id == "master":
        return "test_db"
    return f"test_db_{worker_id}"
```

**Loadfile for order-sensitive modules:**

```shellscript
pytest -n 4 --dist loadfile
```

**Detect xdist:**

```python
def test_only_parallel(worker_id):
    assert worker_id.startswith("gw") or worker_id == "master"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Shared temp paths / ports colliding across workers.
* Session-scoped DB fixtures assuming a single process.
* Flaky tests that only fail under `-n auto`.
* Coverage needing compatible `pytest-cov` settings with xdist.
* Using `--looponfail` in CI (dev-only workflow).

## 🔗 Related [#-related]

* [Install](/docs/pytest/install)
* [Fixtures](/docs/pytest/fixtures)
* [Coverage](/docs/pytest/coverage)
* [CLI](/docs/pytest/cli)
* [tmp\_path](/docs/pytest/tmp-path)
* [Plugins](/docs/pytest/plugins)


# Children (/docs/react/children)



# Children [#children]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`children` is the special prop for nested content between a component’s opening and closing tags. Prefer composition with `children` over prop-drilling UI fragments.

## 🔧 Core concepts [#-core-concepts]

* **Implicit prop** — JSX between tags becomes `props.children`.
* **Any type** — string, number, element, array, `null`/`undefined`/`false` (render nothing).
* **`Children` helpers** — `Children.map`, `toArray`, `count`, `only` (use sparingly; prefer explicit arrays).
* **Slots** — multiple named slots via props (`header`, `footer`) when one `children` is not enough.

## 💡 Examples [#-examples]

```jsx
function Card({ title, children }) {
  return (
    <section className="card">
      <h2>{title}</h2>
      <div className="card-body">{children}</div>
    </section>
  );
}

<Card title="Hello">
  <p>Nested content</p>
  <button type="button">Action</button>
</Card>
```

```tsx
import { Children, type ReactNode } from "react";

type ListProps = { children: ReactNode };

function List({ children }: ListProps) {
  const items = Children.toArray(children);
  return (
    <ul>
      {items.map((child, i) => (
        <li key={i}>{child}</li>
      ))}
    </ul>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don’t mutate `children`; treat as opaque.
* Avoid `Children.only` unless you truly require a single element.
* Keys belong on the elements you create, not on `children` itself.
* Conditional children: `\{ cond && <X /> \}` can leave `false` in the tree — usually fine, but prefer ternaries for clarity.

## 🔗 Related [#-related]

* [component.md](/docs/react/component) — function components
* [props.md](/docs/react/props) — passing data
* [jsx.md](/docs/react/jsx) — JSX nesting
* [render.md](/docs/react/render) — what gets rendered


# Component (/docs/react/component)



# Component [#component]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A component is a reusable UI unit. Prefer **function components** that return JSX. Class components are legacy for new code.

## 🔧 Core concepts [#-core-concepts]

* **Function component** — `(props) => JSX`; name starts with a capital letter.
* **Pure by default** — same props → same UI; side effects go in hooks.
* **Composition** — build UIs by nesting components, not inheritance.
* **Class (legacy)** — `extends React.Component` with `render()`; use only for old codebases.

## 💡 Examples [#-examples]

```tsx
type ButtonProps = {
  label: string;
  onPress: () => void;
};

export function Button({ label, onPress }: ButtonProps) {
  return (
    <button type="button" onClick={onPress}>
      {label}
    </button>
  );
}
```

```jsx
// Legacy class form — prefer functions + hooks
import { Component } from "react";

class Counter extends Component {
  state = { n: 0 };
  render() {
    return (
      <button onClick={() => this.setState({ n: this.state.n + 1 })}>
        {this.state.n}
      </button>
    );
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Lowercase names are treated as DOM tags (`div`), not components.
* Don’t create components inside other components during render (remounts every time).
* Keep components focused; extract when JSX or logic grows.

## 🔗 Related [#-related]

* [props.md](/docs/react/props) — inputs
* [hooks.md](/docs/react/hooks) — state & effects
* [children.md](/docs/react/children) — composition
* [constructor.md](/docs/react/constructor) — class legacy


# Concurrent (/docs/react/concurrent)



# Concurrent [#concurrent]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Concurrent React (18+) can interrupt, prioritize, and reuse work so urgent updates (typing, clicks) stay responsive while heavier UI catches up. You opt in via APIs like `useTransition`, `useDeferredValue`, and Suspense—not by flipping a single switch beyond `createRoot`.

## 🔧 Core concepts [#-core-concepts]

* **`createRoot`** — concurrent-capable root (vs legacy `ReactDOM.render`).
* **Urgent vs transition** — input updates vs deferred UI.
* **Interruptible render** — abandoned work may restart; render must be pure.
* **Suspense** — declarative loading boundaries.
* **Streaming / RSC** — frameworks extend the model (Next.js, etc.).

## 💡 Examples [#-examples]

```tsx
import { createRoot } from "react-dom/client";
import { useState, useTransition, Suspense } from "react";

createRoot(document.getElementById("root")!).render(<App />);

function Tabs() {
  const [tab, setTab] = useState("home");
  const [isPending, startTransition] = useTransition();

  return (
    <div>
      <button
        type="button"
        onClick={() => startTransition(() => setTab("photos"))}
      >
        Photos
      </button>
      {isPending ? <span>Loading tab…</span> : null}
      <Suspense fallback={<p>Loading…</p>}>
        {tab === "photos" ? <Photos /> : <Home />}
      </Suspense>
    </div>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Side effects during render—unsafe when renders restart.
* Mutating shared objects during render.
* Assuming every setState is concurrent—only marked updates are transitions.
* Legacy mode / older roots without concurrent features.

## 🔗 Related [#-related]

* [useTransition.md](/docs/react/usetransition) — startTransition
* [useDeferredValue.md](/docs/react/usedeferredvalue) — deferred values
* [suspense.md](/docs/react/suspense) — loading UI
* [strict\_mode.md](/docs/react/strict-mode) — purity checks
* [performance.md](/docs/react/performance) — responsiveness


# Conditional rendering (/docs/react/conditional-rendering)



# Conditional rendering [#conditional-rendering]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Render UI selectively with JS expressions inside JSX: ternary, `&&`, early returns, or extracting components. Prefer readable conditions; avoid patterns that accidentally render `0` or `NaN`.

## 🔧 Core concepts [#-core-concepts]

* **Early return** — `if (!data) return <Loading />`.
* **Ternary** — `cond ? <A /> : <B />`.
* **`&&`** — `cond && <A />` (watch falsy numbers).
* **Switch / maps** — for multi-branch UIs.
* **Null** — `return null` renders nothing.

## 💡 Examples [#-examples]

```tsx
export function Inbox({ items, loading, error }: Props) {
  if (loading) return <p>Loading…</p>;
  if (error) return <p role="alert">{error.message}</p>;
  if (items.length === 0) return <p>No messages</p>;
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
}
```

```tsx
function Badge({ count }: { count: number }) {
  // Bad: count && <span>{count}</span> renders "0"
  return count > 0 ? <span>{count}</span> : null;
}
```

```tsx
{user ? <Avatar user={user} /> : <LoginLink />}
{isAdmin && <AdminPanel />}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `count && <Badge />` when `count === 0` shows `0`.
* Nested ternaries that hurt readability—extract components.
* Hooks after conditional returns—break rules of hooks.
* Toggling with CSS-only when the subtree should unmount for state reset (or vice versa).

## 🔗 Related [#-related]

* [jsx.md](/docs/react/jsx) — expressions
* [keys\_lists.md](/docs/react/keys-lists) — empty lists
* [hooks.md](/docs/react/hooks) — hook order
* [suspense.md](/docs/react/suspense) — loading UI
* [component.md](/docs/react/component) — extract branches


# Constructor (/docs/react/constructor)



# Constructor [#constructor]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

In **class components**, `constructor` initializes state and binds methods. For new code, use &#x2A;*function components + `useState` / `useReducer`** instead — no constructor needed.

## 🔧 Core concepts [#-core-concepts]

* **`super(props)`** — required before using `this` in a class constructor.
* **Initial state** — `this.state = \{ ... \}` only in the constructor (or as a class field).
* **Binding** — `this.handler = this.handler.bind(this)` or class-field arrows.
* **Modern alternative** — `useState(initial)` / `useReducer` in function components.

## 💡 Examples [#-examples]

```jsx
// Legacy class constructor
import { Component } from "react";

class Form extends Component {
  constructor(props) {
    super(props);
    this.state = { value: props.initial ?? "" };
    this.handleChange = this.handleChange.bind(this);
  }

  handleChange(e) {
    this.setState({ value: e.target.value });
  }

  render() {
    return <input value={this.state.value} onChange={this.handleChange} />;
  }
}
```

```tsx
// Preferred: function + hooks
import { useState } from "react";

export function Form({ initial = "" }: { initial?: string }) {
  const [value, setValue] = useState(initial);
  return (
    <input value={value} onChange={(e) => setValue(e.target.value)} />
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Never call `setState` in the constructor; assign `this.state` directly.
* Don’t fetch data in the constructor — use `componentDidMount` (legacy) or `useEffect`.
* Copying props into state in the constructor often causes stale UI; derive or sync carefully.

## 🔗 Related [#-related]

* [component.md](/docs/react/component) — components overview
* [useState.md](/docs/react/usestate) — modern state
* [hooks.md](/docs/react/hooks) — hooks rules
* [render.md](/docs/react/render) — render lifecycle


# Context (/docs/react/context)



# Context [#context]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Context passes data through the tree without prop drilling. Create a context, wrap a subtree in `Provider`, consume with `useContext` or (legacy) `Context.Consumer`. Combine with custom hooks for a clean API.

## 🔧 Core concepts [#-core-concepts]

* **`createContext`** — typed default value.
* **Provider** — `value` prop is the broadcasted data.
* **Consumers** — re-render when `value` changes by `Object.is`.
* **Composition** — multiple contexts; split state vs dispatch.
* **Default** — only when no Provider ancestor exists.

## 💡 Examples [#-examples]

```tsx
import {
  createContext,
  useContext,
  useMemo,
  useState,
  type ReactNode,
} from "react";

type Auth = {
  user: { id: string; name: string } | null;
  login: (name: string) => void;
  logout: () => void;
};

const AuthContext = createContext<Auth | null>(null);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<Auth["user"]>(null);
  const value = useMemo<Auth>(
    () => ({
      user,
      login: (name) => setUser({ id: "1", name }),
      logout: () => setUser(null),
    }),
    [user],
  );
  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

export function useAuth() {
  const ctx = useContext(AuthContext);
  if (!ctx) throw new Error("useAuth requires AuthProvider");
  return ctx;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Unstable `value` object → widespread re-renders.
* Prop drilling avoidance taken too far—pass props for local parent/child.
* Optional context without null checks.
* Putting server cache in context instead of a dedicated library when updates are frequent.

## 🔗 Related [#-related]

* [useContext.md](/docs/react/usecontext) — hook API
* [useMemo.md](/docs/react/usememo) — stable values
* [custom\_hooks.md](/docs/react/custom-hooks) — `useAuth`
* [performance.md](/docs/react/performance) — re-renders
* [children.md](/docs/react/children) — composition


# Custom hooks (/docs/react/custom-hooks)



# Custom hooks [#custom-hooks]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Custom hooks are functions named `useXxx` that call other hooks to reuse stateful logic (not JSX). Extract repeated effect/state patterns; keep components focused on rendering.

## 🔧 Core concepts [#-core-concepts]

* **Naming** — must start with `use` so lint rules apply.
* **Composition** — call `useState`, `useEffect`, other custom hooks.
* **Return** — values, setters, or tuples/objects—be consistent.
* **No shared state** — each call gets independent state (unless you use context/store inside).
* **Rules of Hooks** — still top-level only.

## 💡 Examples [#-examples]

```tsx
import { useCallback, useEffect, useState } from "react";

export function useToggle(initial = false) {
  const [on, setOn] = useState(initial);
  const toggle = useCallback(() => setOn((v) => !v), []);
  const setTrue = useCallback(() => setOn(true), []);
  const setFalse = useCallback(() => setOn(false), []);
  return { on, toggle, setTrue, setFalse } as const;
}
```

```tsx
export function useMediaQuery(query: string) {
  const [matches, setMatches] = useState(() =>
    typeof window !== "undefined" ? window.matchMedia(query).matches : false,
  );

  useEffect(() => {
    const mql = window.matchMedia(query);
    const onChange = () => setMatches(mql.matches);
    onChange();
    mql.addEventListener("change", onChange);
    return () => mql.removeEventListener("change", onChange);
  }, [query]);

  return matches;
}
```

```tsx
function useFetch<T>(url: string) {
  const [data, setData] = useState<T | null>(null);
  const [error, setError] = useState<Error | null>(null);
  useEffect(() => {
    const ac = new AbortController();
    fetch(url, { signal: ac.signal })
      .then((r) => r.json())
      .then(setData)
      .catch((e) => {
        if (e.name !== "AbortError") setError(e);
      });
    return () => ac.abort();
  }, [url]);
  return { data, error };
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Returning new object literals every render without need—destructure or memoize if passed deep.
* Hiding too much: hooks that fetch + cache + toast + navigate become untestable.
* Conditional hook calls inside custom hooks.
* Forgetting cleanup (listeners, abort).

## 🔗 Related [#-related]

* [hooks.md](/docs/react/hooks) — overview
* [useEffect.md](/docs/react/useeffect) — effects
* [useContext.md](/docs/react/usecontext) — shared subscriptions
* [testing.md](/docs/react/testing) — testing hooks
* [performance.md](/docs/react/performance) — stable returns


# Error boundaries (/docs/react/error-boundaries)



# Error boundaries [#error-boundaries]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Error boundaries catch render/lifecycle errors in the child tree and show fallback UI instead of unmounting the whole app. They must be class components (or a library wrapper)—there is no `useErrorBoundary` built-in. They do **not** catch event handler, async, or SSR errors outside render.

## 🔧 Core concepts [#-core-concepts]

* **`getDerivedStateFromError`** — update state to show fallback.
* **`componentDidCatch`** — log to reporting service.
* **Granularity** — wrap widgets, not only the root.
* **Reset** — change `key` or provide a “try again” that clears error state.
* **vs Suspense** — Suspense = loading; boundary = failure.

## 💡 Examples [#-examples]

```tsx
import { Component, type ErrorInfo, type ReactNode } from "react";

type Props = { children: ReactNode; fallback?: ReactNode };
type State = { error: Error | null };

export class ErrorBoundary extends Component<Props, State> {
  state: State = { error: null };

  static getDerivedStateFromError(error: Error): State {
    return { error };
  }

  componentDidCatch(error: Error, info: ErrorInfo) {
    console.error("UI crash", error, info.componentStack);
  }

  render() {
    if (this.state.error) {
      return (
        this.props.fallback ?? (
          <div role="alert">
            <p>Something went wrong.</p>
            <button type="button" onClick={() => this.setState({ error: null })}>
              Try again
            </button>
          </div>
        )
      );
    }
    return this.props.children;
  }
}
```

```tsx
<ErrorBoundary>
  <Suspense fallback={<p>Loading…</p>}>
    <Profile />
  </Suspense>
</ErrorBoundary>
```

**Event handlers—catch yourself:**

```tsx
function save() {
  try {
    doSave();
  } catch (e) {
    setError(e);
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Expecting boundaries to catch `setTimeout` / `fetch` rejections automatically.
* One root boundary only—bad UX for partial failures.
* Not logging `componentDidCatch`.
* Infinite error loops if fallback throws.

## 🔗 Related [#-related]

* [suspense.md](/docs/react/suspense) — loading boundaries
* [component.md](/docs/react/component) — class vs function
* [testing.md](/docs/react/testing) — assert fallbacks
* [strict\_mode.md](/docs/react/strict-mode) — double render in dev
* [concurrent.md](/docs/react/concurrent) — render model


# Events (/docs/react/events)



# Events [#events]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

React uses a SyntheticEvent system: camelCase props (`onClick`, `onChange`) and functions as handlers. Behavior is consistent across browsers.

## 🔧 Core concepts [#-core-concepts]

* **Naming** — `onClick`, `onSubmit`, `onKeyDown` (not `onclick`).
* **Handler** — pass a function: `onClick=\{handleClick\}`, not `onClick=\{handleClick()\}`.
* **Event object** — `event.preventDefault()`, `event.stopPropagation()`, `event.target`.
* **Passing data** — wrap: `onClick=\{() => onSelect(id)\}` or `onClick=\{onSelect.bind(null, id)\}`.

## 💡 Examples [#-examples]

```tsx
export function SearchForm({ onSearch }: { onSearch: (q: string) => void }) {
  function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault();
    const data = new FormData(e.currentTarget);
    onSearch(String(data.get("q") ?? ""));
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="q" type="search" />
      <button type="submit">Search</button>
    </form>
  );
}
```

```jsx
function List({ items, onSelect }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>
          <button type="button" onClick={() => onSelect(item.id)}>
            {item.label}
          </button>
        </li>
      ))}
    </ul>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Calling the handler immediately (`onClick=\{fn()\}`) runs it during render.
* Don’t rely on the event after an `await` — React pools/reuses in older versions; read values first or use `event.persist()` only if needed on old React.
* Prefer `onChange` on inputs for controlled components, not only `onBlur`.

## 🔗 Related [#-related]

* [props.md](/docs/react/props) — callback props
* [jsx.md](/docs/react/jsx) — JSX attributes
* [useState.md](/docs/react/usestate) — controlled inputs
* [component.md](/docs/react/component) — handlers in components


# File structure (/docs/react/file-structure)



# File structure [#file-structure]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Organize by feature or route, keep components small, and colocate styles/tests. Exact layout depends on Vite, Next.js, or CRA — patterns below are common.

## 🔧 Core concepts [#-core-concepts]

* **Entry** — `main.tsx` / `index.tsx` mounts the root.
* **App shell** — `App.tsx` for providers, layout, routes.
* **Features** — `features/auth/`, `features/cart/` with local components.
* **Shared** — `components/`, `hooks/`, `lib/`, `types/`.
* **Pages/routes** — framework-specific (`pages/`, `app/`, `routes/`).

## 💡 Examples [#-examples]

```plaintext
src/
  main.tsx
  App.tsx
  components/
    Button.tsx
    Button.module.css
  features/
    todos/
      TodoList.tsx
      useTodos.ts
      api.ts
  hooks/
    useMediaQuery.ts
  lib/
    http.ts
  pages/
    HomePage.tsx
    TodoPage.tsx
```

```tsx
// main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Deep `../../../` imports — use path aliases (`@/`).
* Giant `components/` dumping ground — prefer feature folders.
* Mixing business logic into presentational files without clear boundaries.

## 🔗 Related [#-related]

* [main.md](/docs/react/main) — entry point
* [root.md](/docs/react/root) — root mount
* [pages.md](/docs/react/pages) — page components
* [import\_export.md](/docs/react/import-export) — modules


# Forms (/docs/react/forms)



# Forms [#forms]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

React forms are controlled (state drives inputs) or uncontrolled (refs / default values). Prefer controlled for validation and conditional UI; uncontrolled for simple or large native forms. Prevent default submit and handle async saves carefully.

## 🔧 Core concepts [#-core-concepts]

* **Controlled** — `value` + `onChange` bound to state.
* **Uncontrolled** — `defaultValue` + `ref` / `FormData`.
* **Submit** — `onSubmit` on `<form>`; `preventDefault()`.
* **Checkbox/radio** — `checked` / `selected`; groups share `name`.
* **Files** — uncontrolled `type="file"`; read via `FormData`.
* **a11y** — `label` + `useId`, error text with `aria-describedby`.

## 💡 Examples [#-examples]

**Controlled:**

```tsx
import { useState, FormEvent } from "react";

export function LoginForm({ onLogin }: { onLogin: (email: string) => void }) {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  function handleSubmit(e: FormEvent) {
    e.preventDefault();
    onLogin(email);
  }

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Email
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          required
        />
      </label>
      <label>
        Password
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          required
        />
      </label>
      <button type="submit">Sign in</button>
    </form>
  );
}
```

**FormData (uncontrolled):**

```tsx
function handleSubmit(e: FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const data = new FormData(e.currentTarget);
  console.log(data.get("email"));
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing `value` without `onChange` → read-only warning.
* Using `value=\{undefined\}` then string → uncontrolled→controlled switch.
* Mutating state in place for nested form objects.
* Blocking submit button without keyboard/`Enter` considerations.

## 🔗 Related [#-related]

* [useState.md](/docs/react/usestate) — field state
* [useId.md](/docs/react/useid) — label ids
* [useRef.md](/docs/react/useref) — uncontrolled refs
* [events.md](/docs/react/events) — handlers
* [testing.md](/docs/react/testing) — user-event


# forwardRef (/docs/react/forwardref)



# forwardRef [#forwardref]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`forwardRef` lets a parent pass a `ref` through to a child function component (usually a DOM node or imperative handle). In React 19, `ref` can be a regular prop on function components; `forwardRef` remains common in existing code and libraries.

## 🔧 Core concepts [#-core-concepts]

* **Classic** — `forwardRef((props, ref) => ...)`.
* **React 19** — `function Input(\{ ref, ...props \})` may work without forwardRef.
* **`useImperativeHandle`** — expose a custom instance API instead of the raw DOM node.
* **Typing** — `forwardRef<HTMLInputElement, Props>(...)`.

## 💡 Examples [#-examples]

```tsx
import { forwardRef, useImperativeHandle, useRef } from "react";

type Props = { label: string };

export const TextField = forwardRef<HTMLInputElement, Props>(function TextField(
  { label },
  ref,
) {
  return (
    <label>
      {label}
      <input ref={ref} />
    </label>
  );
});
```

**Imperative handle:**

```tsx
type Handle = { focus: () => void; clear: () => void };

export const FancyInput = forwardRef<Handle, object>(function FancyInput(_, ref) {
  const inputRef = useRef<HTMLInputElement>(null);
  useImperativeHandle(ref, () => ({
    focus: () => inputRef.current?.focus(),
    clear: () => {
      if (inputRef.current) inputRef.current.value = "";
    },
  }));
  return <input ref={inputRef} />;
});
```

**Usage:**

```tsx
const ref = useRef<HTMLInputElement>(null);
<TextField ref={ref} label="Email" />;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting to attach `ref` to a real host component.
* Exposing entire component internals via imperative handles—prefer props.
* Breaking memoization by wrapping inconsistently.
* Type mismatches between `ref` and DOM element.

## 🔗 Related [#-related]

* [useRef.md](/docs/react/useref) — refs
* [forms.md](/docs/react/forms) — focus management
* [component.md](/docs/react/component) — components
* [hooks.md](/docs/react/hooks) — useImperativeHandle
* [memo.md](/docs/react/memo) — composed components


# Fragments (/docs/react/fragments)



# Fragments [#fragments]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Fragments group children without adding an extra DOM node. Use `&lt;>...&lt;/>` or `<Fragment>` when a component must return multiple siblings. Keyed fragments need the long form.

## 🔧 Core concepts [#-core-concepts]

* **Short syntax** — `&lt;>...&lt;/>` (no props, no key).
* **Long form** — `<Fragment key=\{...\}>`.
* **No DOM** — doesn’t affect layout/CSS selectors as a wrapper.
* **Return** — components return one parent; fragment counts as one.

## 💡 Examples [#-examples]

```tsx
import { Fragment } from "react";

export function DefinitionList({
  items,
}: {
  items: { id: string; term: string; description: string }[];
}) {
  return (
    <dl>
      {items.map((item) => (
        <Fragment key={item.id}>
          <dt>{item.term}</dt>
          <dd>{item.description}</dd>
        </Fragment>
      ))}
    </dl>
  );
}
```

```tsx
function Columns() {
  return (
    <>
      <td>A</td>
      <td>B</td>
    </>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Trying to pass `key` to `&lt;>...&lt;/>`—use `Fragment`.
* Wrapping with `<div>` unnecessarily and breaking tables/flex.
* Assuming fragments create a styling target—they don’t.
* Returning arrays without keys when mapping.

## 🔗 Related [#-related]

* [keys\_lists.md](/docs/react/keys-lists) — keyed lists
* [jsx.md](/docs/react/jsx) — JSX shape
* [children.md](/docs/react/children) — child composition
* [component.md](/docs/react/component) — return types
* [conditional\_rendering.md](/docs/react/conditional-rendering) — multiple branches


# Getting Started with React (/docs/react/getting-started)



# Getting Started with React [#getting-started-with-react]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

React is a JavaScript library for building user interfaces from **components** — reusable pieces of UI that describe what should appear for a given state. You write components with JSX (HTML-like syntax in JS) and React updates the DOM efficiently.

## 🔧 Core concepts [#-core-concepts]

| Idea      | Meaning                                      |
| --------- | -------------------------------------------- |
| Component | Function that returns UI                     |
| JSX       | Syntax extension: `<Button />` in JS         |
| Props     | Inputs passed into a component               |
| State     | Data that can change over time               |
| Render    | Computing UI from props + state              |
| Hook      | `useState`, `useEffect`, … for state/effects |

Beginners usually start with **Vite + React** or Next.js, not CDN scripts alone.

## 💡 Examples [#-examples]

**Create a Vite React app:**

```shellscript
npm create vite@latest my-app -- --template react
cd my-app
npm install
npm run dev
```

**A tiny component:**

```jsx
function Hello() {
  return <h1>Hello, React</h1>;
}

export default function App() {
  return (
    <main>
      <Hello />
    </main>
  );
}
```

**Props:**

```jsx
function Greeting({ name }) {
  return <p>Hello, {name}!</p>;
}

// <Greeting name="Ada" />
```

**State with useState:**

```jsx
import { useState } from "react";

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button type="button" onClick={() => setCount(count + 1)}>
      Clicked {count}
    </button>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* JSX requires a build step (or a modern toolchain) — browsers don’t run raw JSX.
* Mutating state in place won’t re-render — use the setter (`setCount`).
* Component names must start with a **Capital** letter.
* Don’t forget to import React hooks from `"react"`.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/react/hello-world)
* [thinking\_in\_react.md](/docs/react/thinking-in-react)
* [conditional\_rendering.md](/docs/react/conditional-rendering)
* [keys\_lists.md](/docs/react/keys-lists)


# Glossary (/docs/react/glossary)



# Glossary [#glossary]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core React terms for components, hooks, rendering, and common UI patterns.

## 🔧 Core concepts [#-core-concepts]

| Term               | Definition                                                                            |
| ------------------ | ------------------------------------------------------------------------------------- |
| Children           | Nested content passed between a component’s opening and closing tags.                 |
| Component          | A function or class that returns UI described with JSX/elements.                      |
| Concurrent         | React’s ability to interrupt, prioritize, and resume rendering work.                  |
| Context            | A way to pass data through the tree without prop drilling.                            |
| Controlled input   | A form element whose value is driven by React state.                                  |
| Custom hook        | A function named `use*` that reuses stateful logic across components.                 |
| Effect             | Side-work scheduled with `useEffect` after paint (or layout effects).                 |
| Element            | A plain object describing what to render, usually created via JSX.                    |
| Error boundary     | A class component that catches render errors in its subtree.                          |
| Fiber              | React’s internal unit of work representing a component instance.                      |
| Fragment           | A wrapper (`&lt;>...&lt;/>` or `<Fragment>`) that groups children without a DOM node. |
| Hook               | A special function that lets function components use state and React features.        |
| Hydration          | Attaching event handlers to server-rendered HTML on the client.                       |
| JSX                | Syntax extension that looks like HTML and compiles to `React.createElement` calls.    |
| Key                | A stable identity string helping React match list items across updates.               |
| Memo               | `React.memo` or `useMemo` techniques that skip redundant work.                        |
| Portal             | Rendering children into a DOM node outside the parent hierarchy.                      |
| Props              | Inputs passed from parent to child; treated as read-only by the child.                |
| Reconciliation     | Diffing previous and next trees to decide minimal DOM updates.                        |
| Ref                | A mutable container (`useRef`/`createRef`) that persists across renders.              |
| Render             | Calling a component to produce elements for a given props/state.                      |
| State              | Data owned by a component that triggers re-render when updated.                       |
| Strict Mode        | A development wrapper that highlights unsafe patterns and double-invokes some APIs.   |
| Suspense           | A boundary that shows fallback UI while lazy or async children load.                  |
| Transition         | A lower-priority state update marked with `startTransition`/`useTransition`.          |
| Uncontrolled input | A form element that keeps its value in the DOM, often read via a ref.                 |
| Virtual DOM        | The in-memory element tree React diffs before touching the real DOM.                  |

## 💡 Examples [#-examples]

**State and effect:**

```tsx
function Counter() {
  const [n, setN] = useState(0);
  useEffect(() => {
    document.title = `Count ${n}`;
  }, [n]);
  return <button onClick={() => setN((x) => x + 1)}>{n}</button>;
}
```

**Context and children:**

```tsx
const Theme = createContext("light");
function App({ children }: { children: React.ReactNode }) {
  return <Theme.Provider value="dark">{children}</Theme.Provider>;
}
```

**Keys in lists:**

```tsx
{items.map((item) => (
  <li key={item.id}>{item.label}</li>
))}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **props** (from parent) with **state** (owned locally).
* Mixing **controlled** and **uncontrolled** inputs on the same field.
* Using array **index** as **key** when list order or identity can change.
* Treating **memo** as free performance — it only helps when props are stable.
* Equating **useEffect** with “run on mount only” — dependency arrays control that.

## 🔗 Related [#-related]

* [hooks](/docs/react/hooks)
* [useState](/docs/react/usestate)
* [useEffect](/docs/react/useeffect)
* [props](/docs/react/props)
* [context](/docs/react/context)
* [jsx](/docs/react/jsx)


# Hello World (/docs/react/hello-world)



# Hello World [#hello-world]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

React Hello World is a component that returns a simple element (often an `<h1>`). Once it appears in the browser via your app’s root render, your toolchain is working.

## 🔧 Core concepts [#-core-concepts]

| Piece          | Role                                           |
| -------------- | ---------------------------------------------- |
| Root           | `createRoot(...).render(<App />)` mounts React |
| `App`          | Top-level component                            |
| `return (...)` | JSX describing UI                              |
| Export         | Makes the component importable                 |

In Vite, `main.jsx` mounts `<App />` into `#root`.

## 💡 Examples [#-examples]

**Minimal App:**

```jsx
export default function App() {
  return <h1>Hello, World!</h1>;
}
```

**With a child component:**

```jsx
function Hello() {
  return <h1>Hello, World!</h1>;
}

export default function App() {
  return (
    <div>
      <Hello />
      <p>Welcome to React.</p>
    </div>
  );
}
```

**Mount (Vite-style `main.jsx`):**

```jsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import App from "./App.jsx";

createRoot(document.getElementById("root")).render(
  <StrictMode>
    <App />
  </StrictMode>
);
```

**Expression in JSX:**

```jsx
const name = "Ada";
export default function App() {
  return <h1>Hello, {name}!</h1>;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `getElementById("root")` must match an element in `index.html`.
* Returning two sibling elements needs a wrapper or fragment (`&lt;>...&lt;/>`).
* `class` in JSX is written `className`.
* Browser console errors are your friend — read the first red message carefully.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/react/getting-started)
* [thinking\_in\_react.md](/docs/react/thinking-in-react)
* [fragments.md](/docs/react/fragments)
* [strict\_mode.md](/docs/react/strict-mode)


# Hooks (/docs/react/hooks)



# Hooks [#hooks]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Hooks let function components use state, lifecycle, and shared logic. Call them only at the top level of React functions (components or custom hooks).

## 🔧 Core concepts [#-core-concepts]

* **Built-ins** — `useState`, `useEffect`, `useContext`, `useRef`, `useMemo`, `useCallback`, `useReducer`, `useId`, …
* **Rules** — top level only; only in React functions; same order every render.
* **Custom hooks** — `useXxx` functions that call other hooks; share stateful logic.
* **Classes** — no hooks; use lifecycle methods (legacy).

## 💡 Examples [#-examples]

```tsx
import { useState, useEffect } from "react";

export function useDocumentTitle(title: string) {
  useEffect(() => {
    document.title = title;
  }, [title]);
}

export function Counter() {
  const [count, setCount] = useState(0);
  useDocumentTitle(`Count: ${count}`);
  return (
    <button type="button" onClick={() => setCount((c) => c + 1)}>
      {count}
    </button>
  );
}
```

```jsx
function useToggle(initial = false) {
  const [on, setOn] = useState(initial);
  const toggle = () => setOn((v) => !v);
  return [on, toggle];
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Conditional / looped hook calls break React’s hook order.
* Missing dependency arrays cause stale closures or infinite loops.
* `useMemo` / `useCallback` are not free — use when measured or required for referential equality.

## 🔗 Related [#-related]

* [useState.md](/docs/react/usestate) — state
* [useEffect.md](/docs/react/useeffect) — effects
* [component.md](/docs/react/component) — function components
* [constructor.md](/docs/react/constructor) — class alternative (legacy)


# Import / Export (/docs/react/import-export)



# Import / Export [#import--export]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

React apps use ES modules: `import` / `export`. Prefer **named exports** for components and utilities; default exports are fine for route-level pages when the framework expects them.

## 🔧 Core concepts [#-core-concepts]

* **Named** — `export function Button` → `import \{ Button \} from "./Button"`.
* **Default** — `export default App` → `import App from "./App"`.
* **Re-export** — `export \{ Button \} from "./Button"` for barrel files.
* **Type-only** — `import type \{ Props \} from "./types"` (TypeScript).
* **CSS / assets** — `import "./styles.css"`, `import logo from "./logo.svg"`.

## 💡 Examples [#-examples]

```tsx
// Button.tsx
export type ButtonProps = { label: string };

export function Button({ label }: ButtonProps) {
  return <button type="button">{label}</button>;
}
```

```tsx
// App.tsx
import { Button } from "./components/Button";
import type { ButtonProps } from "./components/Button";
import "./App.css";

export function App() {
  const props: ButtonProps = { label: "Save" };
  return <Button {...props} />;
}
```

```js
// barrel: components/index.ts
export { Button } from "./Button";
export { Input } from "./Input";
```

## ⚠️ Pitfalls [#️-pitfalls]

* Circular imports between components — extract shared modules.
* Mixing default and named for the same symbol confuses refactors.
* Side-effect imports order can matter for CSS cascade.

## 🔗 Related [#-related]

* [file\_structure.md](/docs/react/file-structure) — where modules live
* [component.md](/docs/react/component) — exporting components
* [tsx.md](/docs/react/tsx) — TypeScript modules
* [main.md](/docs/react/main) — entry imports


# React (/docs/react)



# React [#react]

Components, hooks, patterns.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# JSX (/docs/react/jsx)



# JSX [#jsx]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

JSX is syntax sugar for `React.createElement` / the JSX transform. It looks like HTML in JavaScript but follows JavaScript rules for expressions and attributes.

## 🔧 Core concepts [#-core-concepts]

* **Expressions** — `\{value\}` inside tags; any JS expression is allowed.
* **Attributes** — camelCase (`className`, `htmlFor`, `onClick`); strings in quotes or `\{expr\}`.
* **One parent** — return a single root, fragment `&lt;>...&lt;/>`, or array.
* **Self-closing** — `<img />`, `<Component />` when no children.
* **Booleans** — `disabled=\{isOff\}`; omit or pass `true` for presence flags.

## 💡 Examples [#-examples]

```jsx
const name = "Ada";
const el = (
  <>
    <h1 className="title">Hello, {name}</h1>
    <img src="/avatar.png" alt="" />
    {items.length > 0 ? (
      <ul>
        {items.map((item) => (
          <li key={item.id}>{item.label}</li>
        ))}
      </ul>
    ) : (
      <p>Empty</p>
    )}
  </>
);
```

```tsx
type IconProps = { size?: number };

function Icon({ size = 16 }: IconProps) {
  return <svg width={size} height={size} aria-hidden />;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `class` → `className`; `for` → `htmlFor`.
* `style` takes an object: `style=\{\{ marginTop: 8 \}\}`, not a CSS string (unless using libraries).
* Comments: `\{/* comment */\}`, not `&lt;!-- -->`.
* `if` statements aren’t expressions — use ternaries or extract variables.

## 🔗 Related [#-related]

* [tsx.md](/docs/react/tsx) — typed JSX
* [tag.md](/docs/react/tag) — elements & tags
* [children.md](/docs/react/children) — nested content
* [component.md](/docs/react/component) — custom tags


# Keys & lists (/docs/react/keys-lists)



# Keys & lists [#keys--lists]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

When rendering lists, each sibling needs a stable `key` so React can match items across updates. Keys should identify the item (id), not its position. Correct keys preserve state and avoid buggy remounts.

## 🔧 Core concepts [#-core-concepts]

* **Purpose** — identity for reconciliation, not display.
* **Stable** — same item → same key across renders.
* **Unique among siblings** — not globally unique required.
* **Avoid index** — unless the list is static and never reorders.
* **Reset state** — changing `key` on a component remounts it.

## 💡 Examples [#-examples]

```tsx
type Todo = { id: string; text: string; done: boolean };

export function TodoList({ todos }: { todos: Todo[] }) {
  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id}>
          <TodoRow todo={todo} />
        </li>
      ))}
    </ul>
  );
}
```

**Remount to reset form:**

```tsx
<Editor key={selectedId} documentId={selectedId} />
```

**Fragments with keys:**

```tsx
{items.map((item) => (
  <Fragment key={item.id}>
    <dt>{item.term}</dt>
    <dd>{item.description}</dd>
  </Fragment>
))}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `key=\{index\}` with insert/reorder/delete → wrong state on inputs.
* Random keys (`Math.random()`) every render → remount thrash.
* Using array index after sorting/filtering.
* Putting key on the wrong element (must be on the outermost mapped element).

## 🔗 Related [#-related]

* [fragments.md](/docs/react/fragments) — keyed fragments
* [conditional\_rendering.md](/docs/react/conditional-rendering) — list empty states
* [jsx.md](/docs/react/jsx) — expressions
* [performance.md](/docs/react/performance) — list virtualization
* [memo.md](/docs/react/memo) — row memoization


# Layout (/docs/react/layout)



# Layout [#layout]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Layout in React is ordinary DOM + CSS (Flexbox, Grid, modules, Tailwind). Components compose shells: header, sidebar, main, footer — often via nested routes or layout wrappers.

## 🔧 Core concepts [#-core-concepts]

* **Shell components** — `AppLayout`, `AuthLayout` wrap page content with `children`.
* **CSS approach** — CSS Modules, Tailwind, styled-components, plain CSS — pick one stack.
* **Responsive** — media queries or container queries; avoid hard-coded pixel-only UIs.
* **Portals** — modals/tooltips via `createPortal` to escape overflow/stacking contexts.

## 💡 Examples [#-examples]

```tsx
import type { ReactNode } from "react";

export function AppLayout({ children }: { children: ReactNode }) {
  return (
    <div className="app">
      <header className="app-header">Brand</header>
      <div className="app-body">
        <aside className="app-nav">Nav</aside>
        <main className="app-main">{children}</main>
      </div>
    </div>
  );
}
```

```css
.app {
  min-height: 100dvh;
  display: flex;
  flex-direction: column;
}
.app-body {
  flex: 1;
  display: grid;
  grid-template-columns: 240px 1fr;
}
.app-main {
  padding: 1.5rem;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Nesting too many layout wrappers without clear ownership.
* Fixed heights that break on mobile keyboards / dynamic viewport.
* Forgetting `min-width: 0` on flex/grid children that overflow.

## 🔗 Related [#-related]

* [pages.md](/docs/react/pages) — page content inside layouts
* [children.md](/docs/react/children) — layout slots
* [root.md](/docs/react/root) — app root
* [file\_structure.md](/docs/react/file-structure) — where layouts live


# Main (/docs/react/main)



# Main [#main]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`main.tsx` / `main.jsx` (or `index.tsx`) is the **entry module**: it finds the DOM node and mounts the React tree with `createRoot`.

## 🔧 Core concepts [#-core-concepts]

* **`createRoot`** — React 18+ API from `react-dom/client`.
* **`StrictMode`** — double-invokes effects in dev to surface unsafe patterns.
* **Providers** — wrap `App` with router, query client, theme, auth.
* **Legacy** — `ReactDOM.render` is removed in React 19; migrate to `createRoot`.

## 💡 Examples [#-examples]

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import { App } from "./App";
import "./index.css";

const el = document.getElementById("root");
if (!el) throw new Error("Root element #root not found");

createRoot(el).render(
  <StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </StrictMode>,
);
```

```html
<!-- index.html -->
<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
</body>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mounting twice on the same node without `root.unmount()`.
* Missing `#root` in HTML → silent or thrown failure.
* Putting heavy logic in `main` instead of `App` / feature modules.

## 🔗 Related [#-related]

* [root.md](/docs/react/root) — root API details
* [file\_structure.md](/docs/react/file-structure) — project layout
* [pages.md](/docs/react/pages) — routed pages
* [import\_export.md](/docs/react/import-export) — entry imports


# memo (/docs/react/memo)



# memo [#memo]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`memo(Component)` wraps a function component so React skips re-rendering when props are shallowly equal (`Object.is` per prop). Use after measuring; unstable callback/object props defeat it unless memoized.

## 🔧 Core concepts [#-core-concepts]

* **Shallow compare** — default prop equality.
* **Custom compare** — `memo(Comp, (prev, next) => boolean)` (return true to skip).
* **Children** — `children` prop changes often; be careful.
* **Compiler** — React Compiler may auto-memoize; manual `memo` still fine.
* **Pair with** — `useCallback` / `useMemo` for stable props.

## 💡 Examples [#-examples]

```tsx
import { memo } from "react";

type Props = { name: string; active: boolean; onSelect: () => void };

export const UserRow = memo(function UserRow({ name, active, onSelect }: Props) {
  return (
    <button type="button" aria-pressed={active} onClick={onSelect}>
      {name}
    </button>
  );
});
```

**Custom equality:**

```tsx
const Chart = memo(
  function Chart({ data }: { data: number[] }) {
    return <canvas />;
  },
  (prev, next) =>
    prev.data.length === next.data.length &&
    prev.data.every((v, i) => v === next.data[i]),
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Memoizing everything—noise and complexity.
* Passing inline `onClick=\{() => ...\}` or `style=\{\{\}\}` → always re-render.
* Expecting `memo` to deep-compare objects.
* Skipping renders that must update from context—context still forces update when consumed.

## 🔗 Related [#-related]

* [useCallback.md](/docs/react/usecallback) — stable handlers
* [useMemo.md](/docs/react/usememo) — stable values
* [performance.md](/docs/react/performance) — profiling
* [component.md](/docs/react/component) — function components
* [keys\_lists.md](/docs/react/keys-lists) — list rows


# Pages (/docs/react/pages)



# Pages [#pages]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Pages are route-level screens: they compose features, fetch data, and sit inside layouts. In SPAs they map to router routes; in Next.js / Remix they are file-based routes.

## 🔧 Core concepts [#-core-concepts]

* **Thin pages** — orchestrate; push UI into feature components.
* **Data** — loaders, React Query, or `useEffect` + fetch (prefer dedicated data libs).
* **Params** — `useParams`, `useSearchParams` from the router.
* **Code splitting** — `lazy(() => import("./Page"))` + `Suspense`.

## 💡 Examples [#-examples]

```tsx
import { useParams } from "react-router-dom";
import { TodoList } from "../features/todos/TodoList";

export function TodoPage() {
  const { listId } = useParams<{ listId: string }>();
  if (!listId) return <p>Missing list</p>;
  return (
    <section>
      <h1>List {listId}</h1>
      <TodoList listId={listId} />
    </section>
  );
}
```

```tsx
import { lazy, Suspense } from "react";
import { Route, Routes } from "react-router-dom";

const TodoPage = lazy(() =>
  import("./pages/TodoPage").then((m) => ({ default: m.TodoPage })),
);

export function AppRoutes() {
  return (
    <Suspense fallback={<p>Loading…</p>}>
      <Routes>
        <Route path="/lists/:listId" element={<TodoPage />} />
      </Routes>
    </Suspense>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fat pages with all business logic — hard to test and reuse.
* Fetching the same data in every page without a cache layer.
* Forgetting loading and error UI for async pages.

## 🔗 Related [#-related]

* [layout.md](/docs/react/layout) — page shells
* [file\_structure.md](/docs/react/file-structure) — where pages live
* [hooks.md](/docs/react/hooks) — data hooks
* [main.md](/docs/react/main) — app entry


# Performance (/docs/react/performance)



# Performance [#performance]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Optimize after measuring (React DevTools Profiler, browser performance). Biggest wins: fewer unnecessary re-renders, smaller JS bundles, virtualized long lists, and concurrent features for responsiveness. Avoid premature `memo` everywhere.

## 🔧 Core concepts [#-core-concepts]

| Lever      | Technique                                    |
| ---------- | -------------------------------------------- |
| Re-renders | `memo`, stable props, split context          |
| Bundles    | `lazy` + `Suspense`, route splitting         |
| Lists      | windowing (`react-window` / FlashList on RN) |
| Urgency    | `useTransition` / `useDeferredValue`         |
| Images     | correct size, lazy load, modern formats      |
| State      | lift only as high as needed; colocate        |

Profile → find slow commits → fix the cause.

## 💡 Examples [#-examples]

```tsx
import { lazy, Suspense, memo, useCallback, useState } from "react";

const HeavyChart = lazy(() => import("./HeavyChart"));

const Row = memo(function Row({
  id,
  onSelect,
}: {
  id: string;
  onSelect: (id: string) => void;
}) {
  return (
    <button type="button" onClick={() => onSelect(id)}>
      {id}
    </button>
  );
});

export function Dashboard({ ids }: { ids: string[] }) {
  const [selected, setSelected] = useState<string | null>(null);
  const onSelect = useCallback((id: string) => setSelected(id), []);

  return (
    <>
      {ids.map((id) => (
        <Row key={id} id={id} onSelect={onSelect} />
      ))}
      <Suspense fallback={<p>Loading chart…</p>}>
        {selected ? <HeavyChart id={selected} /> : null}
      </Suspense>
    </>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Optimizing without a profile.
* Giant context values updating every keystroke.
* Anonymous components defined inside parents (`function Row` inside render).
* Derived state duplicated instead of computing during render.
* Huge lists without virtualization.

## 🔗 Related [#-related]

* [memo.md](/docs/react/memo) — skip renders
* [useMemo.md](/docs/react/usememo) / [useCallback.md](/docs/react/usecallback)
* [useTransition.md](/docs/react/usetransition) — responsiveness
* [suspense.md](/docs/react/suspense) — code split
* [keys\_lists.md](/docs/react/keys-lists) — list identity


# Portals (/docs/react/portals)



# Portals [#portals]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`createPortal(child, domNode)` renders children into a DOM node outside the parent hierarchy while preserving React context and event bubbling in the React tree. Use for modals, tooltips, and toasts that must escape `overflow: hidden` or stacking contexts.

## 🔧 Core concepts [#-core-concepts]

* **API** — `createPortal(reactNode, container, key?)`.
* **Events** — bubble through React parents, not necessarily DOM parents.
* **Context** — still sees the React tree Providers.
* **SSR** — ensure the target node exists or gate on client.
* **Cleanup** — unmount removes portal children; manage container lifetime.

## 💡 Examples [#-examples]

```tsx
import { useEffect, useState } from "react";
import { createPortal } from "react-dom";

export function Modal({
  open,
  onClose,
  children,
}: {
  open: boolean;
  onClose: () => void;
  children: React.ReactNode;
}) {
  if (!open) return null;
  return createPortal(
    <div
      role="dialog"
      aria-modal="true"
      style={{
        position: "fixed",
        inset: 0,
        background: "rgba(0,0,0,0.4)",
        display: "grid",
        placeItems: "center",
      }}
      onClick={onClose}
    >
      <div onClick={(e) => e.stopPropagation()}>{children}</div>
    </div>,
    document.body,
  );
}
```

**Dedicated mount node:**

```tsx
const el = document.getElementById("modal-root");
return el ? createPortal(content, el) : null;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting focus trap / `Escape` / `aria-modal` for dialogs.
* Portal target missing during SSR/hydration.
* Relying on DOM parent CSS (inheritance) that no longer applies.
* Stopping propagation incorrectly so overlay clicks don’t close.

## 🔗 Related [#-related]

* [jsx.md](/docs/react/jsx) — rendering
* [events.md](/docs/react/events) — bubbling
* [context.md](/docs/react/context) — context still works
* [useEffect.md](/docs/react/useeffect) — lock body scroll
* [fragments.md](/docs/react/fragments) — grouping without nodes


# Props (/docs/react/props)



# Props [#props]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Props are the inputs to a component — read-only data and callbacks from the parent. Type them with TypeScript; validate shapes at boundaries when needed.

## 🔧 Core concepts [#-core-concepts]

* **Immutable** — never mutate `props`; lift state or use local state instead.
* **Destructuring** — `function Button(\{ label, onClick \})`.
* **Defaults** — default parameters or `defaultProps` (prefer parameters).
* **Spread** — `<Button \{...rest\} />` for passthrough DOM props.
* **Children** — special prop for nested content (see children.md).

## 💡 Examples [#-examples]

```tsx
type AvatarProps = {
  name: string;
  size?: number;
  onClick?: () => void;
};

export function Avatar({ name, size = 40, onClick }: AvatarProps) {
  return (
    <button type="button" onClick={onClick} style={{ width: size, height: size }}>
      {name.slice(0, 1)}
    </button>
  );
}
```

```jsx
function UserCard({ user, ...rest }) {
  return (
    <article {...rest}>
      <Avatar name={user.name} />
      <p>{user.email}</p>
    </article>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutating props or nested objects from props.
* Passing new inline objects/functions when child memoization depends on referential equality — measure before optimizing.
* Prop drilling deep trees — use composition or context.

## 🔗 Related [#-related]

* [component.md](/docs/react/component) — receiving props
* [children.md](/docs/react/children) — children prop
* [events.md](/docs/react/events) — callback props
* [tsx.md](/docs/react/tsx) — typing props


# Render (/docs/react/render)



# Render [#render]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Rendering is React turning component output into the UI. Function components **return** JSX; React reconciles changes and updates the DOM. Class components use a `render()` method (legacy).

## 🔧 Core concepts [#-core-concepts]

* **Return value** — element, fragment, string/number, `null`/`false`/`undefined` (nothing).
* **Re-render** — state/props/context change schedules an update.
* **Reconciliation** — keys help match list items across updates.
* **Class `render()`** — pure method; no side effects (legacy).

## 💡 Examples [#-examples]

```tsx
export function Status({ ok }: { ok: boolean }) {
  if (!ok) return null;
  return <span className="ok">Ready</span>;
}
```

```jsx
function List({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.label}</li>
      ))}
    </ul>
  );
}
```

```jsx
// Legacy class
class Badge extends React.Component {
  render() {
    return <span>{this.props.label}</span>;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Side effects during render (subscriptions, fetches) — use `useEffect`.
* Unstable list keys (`index` when order changes) cause wrong state reuse.
* Returning `undefined` accidentally (missing `return`) shows nothing / warnings.

## 🔗 Related [#-related]

* [component.md](/docs/react/component) — what returns JSX
* [root.md](/docs/react/root) — initial mount
* [jsx.md](/docs/react/jsx) — JSX output
* [useState.md](/docs/react/usestate) — triggers re-render


# Root (/docs/react/root)



# Root [#root]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The **root** is the React 18+ mount point created with `createRoot(domNode)`. It owns the tree: `render`, `unmount`, and concurrent features.

## 🔧 Core concepts [#-core-concepts]

* **`createRoot(container)`** — returns a root object.
* **`root.render(<App />)`** — mount or update the tree.
* **`root.unmount()`** — tear down listeners and DOM React owns.
* **Hydration** — `hydrateRoot` for SSR; match server HTML.

## 💡 Examples [#-examples]

```tsx
import { createRoot } from "react-dom/client";
import { App } from "./App";

const container = document.getElementById("root")!;
const root = createRoot(container);
root.render(<App />);

// Later (e.g. microfrontend teardown):
// root.unmount();
```

```tsx
import { hydrateRoot } from "react-dom/client";
import { App } from "./App";

hydrateRoot(document.getElementById("root")!, <App />);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Calling `createRoot` twice on the same node without unmounting.
* Using deprecated `ReactDOM.render` on React 18+.
* Hydration mismatches (different server vs client markup) cause warnings and remounts.

## 🔗 Related [#-related]

* [main.md](/docs/react/main) — typical entry usage
* [render.md](/docs/react/render) — what gets rendered
* [file\_structure.md](/docs/react/file-structure) — project entry
* [layout.md](/docs/react/layout) — top-level UI


# Router (/docs/react/router)



# Router [#router]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Client-side routing maps URLs to components. In React apps, **React Router** (v6/v7) is the common SPA choice; Next.js / Remix use file-based routers. Core ideas: route config, nested layouts, loaders/actions (data routers), and links that don’t full-reload.

## 🔧 Core concepts [#-core-concepts]

| Concept                            | Role                           |
| ---------------------------------- | ------------------------------ |
| `BrowserRouter` / `RouterProvider` | History + route tree           |
| `Routes` / `Route`                 | Match path → element           |
| `Link` / `NavLink`                 | Declarative navigation         |
| `useNavigate` / `useParams`        | Imperative / params            |
| Nested routes                      | Layout + `<Outlet />`          |
| Loaders                            | Data before render (data APIs) |

Prefer path params and search params over ad-hoc global state for shareable URLs.

## 💡 Examples [#-examples]

```tsx
import {
  createBrowserRouter,
  RouterProvider,
  Link,
  Outlet,
  useParams,
} from "react-router-dom";

function RootLayout() {
  return (
    <div>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/posts/1">Post</Link>
      </nav>
      <Outlet />
    </div>
  );
}

function Post() {
  const { id } = useParams();
  return <h1>Post {id}</h1>;
}

const router = createBrowserRouter([
  {
    path: "/",
    element: <RootLayout />,
    children: [
      { index: true, element: <p>Home</p> },
      { path: "posts/:id", element: <Post /> },
    ],
  },
]);

export function App() {
  return <RouterProvider router={router} />;
}
```

**Navigate:**

```tsx
const navigate = useNavigate();
navigate("/login", { replace: true });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using `<a href>` for in-app routes → full reload.
* Forgetting nested `<Outlet />`.
* Matching order / missing splat routes for 404.
* Putting auth redirects only in UI without loader/guard protection.

## 🔗 Related [#-related]

* [suspense.md](/docs/react/suspense) — lazy routes
* [layout.md](/docs/react/layout) — nested layouts
* [pages.md](/docs/react/pages) — page components
* [error\_boundaries.md](/docs/react/error-boundaries) — route errors
* [performance.md](/docs/react/performance) — code splitting


# Strict Mode (/docs/react/strict-mode)



# Strict Mode [#strict-mode]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`<StrictMode>` enables extra development checks: double-invoking render/effects (React 18+), warning on deprecated APIs, and detecting unsafe lifecycles. It does not affect production builds. Prefer wrapping the app root during development.

## 🔧 Core concepts [#-core-concepts]

* **Dev-only** — no production behavior change.
* **Double effects** — mount → unmount → remount to surface missing cleanups.
* **Double render** — helps find impure renders.
* **Nested** — can wrap subsections.
* **Not a performance tool** — diagnostics only.

## 💡 Examples [#-examples]

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);
```

**Effect that survives Strict Mode:**

```tsx
useEffect(() => {
  const ac = new AbortController();
  fetch("/api", { signal: ac.signal }).then(/* ... */);
  return () => ac.abort(); // required — runs on simulated remount
}, []);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Thinking double-fetch in dev is a production bug—check cleanup first.
* Impure renders (Math.random in render, mutating props)—Strict Mode exposes them.
* Removing Strict Mode to “fix” bugs instead of fixing cleanups.
* Expecting warnings for all async race conditions—it won’t catch everything.

## 🔗 Related [#-related]

* [useEffect.md](/docs/react/useeffect) — cleanup
* [root.md](/docs/react/root) — createRoot
* [concurrent.md](/docs/react/concurrent) — concurrent features
* [testing.md](/docs/react/testing) — act / cleanup
* [hooks.md](/docs/react/hooks) — purity


# Suspense (/docs/react/suspense)



# Suspense [#suspense]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`<Suspense fallback=\{...\}>` shows fallback UI while children are loading (lazy components, React 19 resource reading patterns, frameworks with RSC/data). Pair with `lazy()` for code-splitting and error boundaries for failures.

## 🔧 Core concepts [#-core-concepts]

* **Boundary** — catches “suspend” from descendants; shows `fallback`.
* **`React.lazy`** — dynamic `import()` wrapped component.
* **Nested** — nearest boundary handles the suspend.
* **Transitions** — pending transitions can avoid hiding already-shown UI (concurrent).
* **Not for** — ordinary `useEffect` fetching unless integrated with a Suspense-aware data API.

## 💡 Examples [#-examples]

```tsx
import { lazy, Suspense } from "react";

const Editor = lazy(() => import("./Editor"));

export function Page() {
  return (
    <Suspense fallback={<p>Loading editor…</p>}>
      <Editor />
    </Suspense>
  );
}
```

**Nested boundaries:**

```tsx
<Suspense fallback={<PageSkeleton />}>
  <Header />
  <Suspense fallback={<FeedSkeleton />}>
    <Feed />
  </Suspense>
</Suspense>
```

**Named export lazy:**

```tsx
const Chart = lazy(() =>
  import("./Chart").then((m) => ({ default: m.Chart })),
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing error boundary—load failures are not Suspense.
* One giant boundary → whole page flashes fallback.
* Suspense for data without a compatible library/framework → won’t suspend.
* Forgetting a default export when using `lazy(() => import(...))`.

## 🔗 Related [#-related]

* [error\_boundaries.md](/docs/react/error-boundaries) — failures
* [concurrent.md](/docs/react/concurrent) — concurrent UI
* [useTransition.md](/docs/react/usetransition) — pending states
* [performance.md](/docs/react/performance) — code splitting
* [router.md](/docs/react/router) — route-level lazy


# Tag (/docs/react/tag)



# Tag [#tag]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

In JSX, **tags** are either host elements (`div`, `span`, `input`) or custom components (`<Button />`). Capitalization decides which.

## 🔧 Core concepts [#-core-concepts]

* **Host tags** — lowercase → DOM/SVG elements.
* **Component tags** — Uppercase → your function/class components.
* **Dynamic tags** — assign to a capitalized variable: `const Tag = as; return <Tag />`.
* **Fragments** — `&lt;>...&lt;/>` or `<Fragment>` with optional `key`.

## 💡 Examples [#-examples]

```tsx
type BoxProps = {
  as?: "div" | "section" | "article";
  children: React.ReactNode;
};

export function Box({ as: Tag = "div", children }: BoxProps) {
  return <Tag className="box">{children}</Tag>;
}
```

```jsx
const ok = true;
return ok ? <span>Yes</span> : <span>No</span>;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `<button>` vs `<Button>` — wrong case mounts the wrong thing.
* Variable component must be capitalized: `const Comp = map[type]` then `<Comp />`.
* Unknown HTML attributes may land on the DOM; filter props for wrappers.

## 🔗 Related [#-related]

* [jsx.md](/docs/react/jsx) — JSX syntax
* [component.md](/docs/react/component) — custom tags
* [tsx.md](/docs/react/tsx) — typed elements
* [children.md](/docs/react/children) — tag children


# Testing (/docs/react/testing)



# Testing [#testing]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Test React components with **React Testing Library** (RTL) + **Vitest/Jest**: assert what users see and do, not implementation details. Use `userEvent` for interactions; mock network at the boundary. Prefer integration-style tests over shallow enzyme-style tests.

## 🔧 Core concepts [#-core-concepts]

| Tool                    | Role                     |
| ----------------------- | ------------------------ |
| `render`                | Mount into jsdom/browser |
| `screen`                | Queries (`getByRole`, …) |
| `userEvent`             | Realistic interactions   |
| `waitFor` / `findBy*`   | Async UI                 |
| `vi.mock` / `jest.mock` | Module mocks             |
| MSW                     | HTTP mocking             |

Query priority: role → label → text → test id (last resort).

## 💡 Examples [#-examples]

```tsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Counter } from "./Counter";

test("increments count", async () => {
  const user = userEvent.setup();
  render(<Counter />);
  await user.click(screen.getByRole("button", { name: /increment/i }));
  expect(screen.getByText("1")).toBeInTheDocument();
});
```

**Async:**

```tsx
render(<UserProfile id="1" />);
expect(await screen.findByRole("heading", { name: /ada/i })).toBeVisible();
```

**Router wrapper:**

```tsx
import { MemoryRouter } from "react-router-dom";

render(
  <MemoryRouter initialEntries={["/posts/1"]}>
    <App />
  </MemoryRouter>,
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Testing class names / state variables instead of behavior.
* Not wrapping providers (router, theme, query client).
* Forgetting `await` on `userEvent` / `findBy`.
* Snapshot-only tests that churn on markup noise.
* Leaving timers/network open—use fake timers or MSW cleanup.

## 🔗 Related [#-related]

* [hooks.md](/docs/react/hooks) — test via components
* [custom\_hooks.md](/docs/react/custom-hooks) — `renderHook`
* [router.md](/docs/react/router) — MemoryRouter
* [forms.md](/docs/react/forms) — form interactions
* [error\_boundaries.md](/docs/react/error-boundaries) — error UI


# Thinking in React (/docs/react/thinking-in-react)



# Thinking in React [#thinking-in-react]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

“Thinking in React” is a design approach: break the UI into a component hierarchy, decide what is state vs props, and let data flow downward. Build static UI first, then add interactivity.

## 🔧 Core concepts [#-core-concepts]

| Step                | What you do                            |
| ------------------- | -------------------------------------- |
| 1. Mock / sketch    | Know the screens and pieces            |
| 2. Split components | One responsibility per component       |
| 3. Static version   | Render with hard-coded props/data      |
| 4. Find state       | What changes over time? Minimize it    |
| 5. Place state      | Own state in the closest common parent |
| 6. Data flow        | Props down; events up                  |

If two components need the same changing data, lift state to their parent.

## 💡 Examples [#-examples]

**Component split (static):**

```jsx
function SearchBar({ query }) {
  return <input value={query} readOnly />;
}

function ProductList({ products }) {
  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

function FilterableList({ products }) {
  return (
    <>
      <SearchBar query="" />
      <ProductList products={products} />
    </>
  );
}
```

**Add state in the parent:**

```jsx
import { useState } from "react";

function FilterableList({ products }) {
  const [query, setQuery] = useState("");
  const filtered = products.filter((p) =>
    p.name.toLowerCase().includes(query.toLowerCase())
  );

  return (
    <>
      <input
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search"
      />
      <ProductList products={filtered} />
    </>
  );
}
```

**Props down, events up:**

```jsx
function SearchBar({ query, onQueryChange }) {
  return (
    <input
      value={query}
      onChange={(e) => onQueryChange(e.target.value)}
    />
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Duplicating the same state in two places causes them to drift.
* Derivable values (filtered lists) usually should not be stored as separate state.
* Giant “god components” are hard to change — split earlier than you think.
* Don’t fetch in every tiny child — load data near the top or in a dedicated module.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/react/getting-started)
* [hello\_world.md](/docs/react/hello-world)
* [keys\_lists.md](/docs/react/keys-lists)
* [conditional\_rendering.md](/docs/react/conditional-rendering)


# TSX (/docs/react/tsx)



# TSX [#tsx]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`.tsx` is TypeScript + JSX. Type props, events, and refs for safer components. Use `react` types (`ReactNode`, `CSSProperties`, form events).

## 🔧 Core concepts [#-core-concepts]

* **Props types** — `type Props = \{ ... \}` or `interface`.
* **FC** — prefer explicit props + return; `React.FC` is optional and adds `children` quirks in older typings.
* **Events** — `React.ChangeEvent<HTMLInputElement>`, `React.MouseEvent`.
* **Refs** — `useRef<HTMLDivElement>(null)`.
* **Generics** — `function List<T>(\{ items \}: \{ items: T[] \})`.

## 💡 Examples [#-examples]

```tsx
import { useRef, useState, type FormEvent } from "react";

type FormProps = {
  onSave: (name: string) => void;
};

export function NameForm({ onSave }: FormProps) {
  const [name, setName] = useState("");
  const inputRef = useRef<HTMLInputElement>(null);

  function handleSubmit(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    onSave(name);
    inputRef.current?.focus();
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        ref={inputRef}
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <button type="submit">Save</button>
    </form>
  );
}
```

```tsx
type ListProps<T> = {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
};

export function List<T>({ items, renderItem }: ListProps<T>) {
  return <ul>{items.map((item, i) => <li key={i}>{renderItem(item)}</li>)}</ul>;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Typing `children` only when needed — don’t force it on every component.
* `as any` on props hides real bugs.
* Ensure `"jsx": "react-jsx"` (or compatible) in `tsconfig`.

## 🔗 Related [#-related]

* [jsx.md](/docs/react/jsx) — JSX without types
* [props.md](/docs/react/props) — prop shapes
* [component.md](/docs/react/component) — components
* [import\_export.md](/docs/react/import-export) — `import type`


# useCallback (/docs/react/usecallback)



# useCallback [#usecallback]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useCallback(fn, deps)` returns a memoized function identity until dependencies change. Useful when passing callbacks to memoized children, effect deps, or libraries that compare by reference.

## 🔧 Core concepts [#-core-concepts]

* **Identity** — same function reference across renders if deps unchanged.
* **Pair with `memo`** — child skips re-render if props are equal.
* **Effect deps** — stable callbacks avoid effect churn.
* **Not free** — only when measured or required by API contracts.

## 💡 Examples [#-examples]

```tsx
import { memo, useCallback, useState } from "react";

const Row = memo(function Row({
  id,
  onSelect,
}: {
  id: string;
  onSelect: (id: string) => void;
}) {
  return (
    <button type="button" onClick={() => onSelect(id)}>
      {id}
    </button>
  );
});

export function List({ ids }: { ids: string[] }) {
  const [selected, setSelected] = useState<string | null>(null);
  const onSelect = useCallback((id: string) => setSelected(id), []);

  return (
    <div>
      {ids.map((id) => (
        <Row key={id} id={id} onSelect={onSelect} />
      ))}
      <p>Selected: {selected}</p>
    </div>
  );
}
```

**Functional updates avoid deps:**

```tsx
const increment = useCallback(() => setCount((c) => c + 1), []);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Wrapping every function “just in case”.
* Omitting deps that the callback closes over → stale closures.
* Expecting `useCallback` alone to prevent re-renders—child must be `memo` (or equivalent).
* Putting unstable objects in deps.

## 🔗 Related [#-related]

* [useMemo.md](/docs/react/usememo) — value memoization
* [memo.md](/docs/react/memo) — pure components
* [useEffect.md](/docs/react/useeffect) — dependency arrays
* [performance.md](/docs/react/performance) — profiling
* [hooks.md](/docs/react/hooks) — rules


# useContext (/docs/react/usecontext)



# useContext [#usecontext]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useContext(MyContext)` reads the nearest `MyContext.Provider` value and re-renders when that value changes. Prefer context for cross-tree data (theme, auth, locale)—not for high-frequency updates that should stay local or use a store.

## 🔧 Core concepts [#-core-concepts]

* **Create** — `const Ctx = createContext(defaultValue)`.
* **Provide** — `<Ctx.Provider value=\{...\}>`.
* **Consume** — `const value = useContext(Ctx)`.
* **Default** — used only when no Provider is above.
* **Bail out** — same `Object.is` value skips re-render (React 19 / compiler may help further).

## 💡 Examples [#-examples]

```tsx
import { createContext, useContext, useState, type ReactNode } from "react";

type Theme = "light" | "dark";
const ThemeContext = createContext<Theme>("light");

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>("light");
  return (
    <ThemeContext.Provider value={theme}>
      <button type="button" onClick={() => setTheme((t) => (t === "light" ? "dark" : "light"))}>
        Toggle
      </button>
      {children}
    </ThemeContext.Provider>
  );
}

export function ThemedBox() {
  const theme = useContext(ThemeContext);
  return <div data-theme={theme}>Hello</div>;
}
```

**Split value + setter to limit re-renders:**

```tsx
const ThemeValueCtx = createContext<Theme>("light");
const ThemeSetCtx = createContext<(t: Theme) => void>(() => {});
```

## ⚠️ Pitfalls [#️-pitfalls]

* New object/array in `value=\{\{ theme, setTheme \}\}` every render → all consumers re-render; memoize or split contexts.
* Using context as a global Redux replacement for rapidly changing data.
* Reading context in a parent that doesn’t need it—push consumers down.
* Forgetting a Provider in tests/stories.

## 🔗 Related [#-related]

* [context.md](/docs/react/context) — Provider patterns
* [hooks.md](/docs/react/hooks) — rules of hooks
* [useMemo.md](/docs/react/usememo) — stabilize values
* [performance.md](/docs/react/performance) — re-render control
* [custom\_hooks.md](/docs/react/custom-hooks) — `useTheme()` wrappers


# useDeferredValue (/docs/react/usedeferredvalue)



# useDeferredValue [#usedeferredvalue]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useDeferredValue(value)` returns a deferred version of `value` that may “lag behind” during urgent updates. Keep showing the latest input while expensive children render with the deferred value.

## 🔧 Core concepts [#-core-concepts]

* **Lagging copy** — UI can show `value` immediately and `deferred` for heavy work.
* **vs useTransition** — defer a prop/value vs wrap a state update.
* **Concurrent** — React may interrupt rendering the deferred tree.
* **Pending UX** — compare `value !== deferred` to show a stale indicator.

## 💡 Examples [#-examples]

```tsx
import { useDeferredValue, useMemo, useState } from "react";

function SlowList({ query }: { query: string }) {
  const items = useMemo(() => {
    // expensive filter/render
    return Array.from({ length: 5000 }, (_, i) => `${query}-${i}`);
  }, [query]);
  return (
    <ul>
      {items.map((item) => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  );
}

export function SearchPage() {
  const [query, setQuery] = useState("");
  const deferredQuery = useDeferredValue(query);
  const isStale = query !== deferredQuery;

  return (
    <div>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <div style={{ opacity: isStale ? 0.6 : 1 }}>
        <SlowList query={deferredQuery} />
      </div>
    </div>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Deferring values that must stay in sync for correctness (validation, submit payload).
* Using as a substitute for debouncing network requests—still debounce fetches.
* Memoizing children incorrectly so deferred updates don’t help.
* Ignoring stale UI—users may click outdated rows; disable or mark pending.

## 🔗 Related [#-related]

* [useTransition.md](/docs/react/usetransition) — startTransition
* [concurrent.md](/docs/react/concurrent) — concurrent rendering
* [performance.md](/docs/react/performance) — optimization
* [memo.md](/docs/react/memo) — skip re-renders
* [hooks.md](/docs/react/hooks) — rules


# useEffect (/docs/react/useeffect)



# useEffect [#useeffect]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useEffect` runs **side effects** after paint: subscriptions, network calls, DOM sync, timers. Declare dependencies so effects re-run when values change; return a cleanup function.

## 🔧 Core concepts [#-core-concepts]

* **Signature** — `useEffect(setup, deps?)`.
* **Deps** — `[]` mount/unmount only; omit = every render (rare); list values used inside.
* **Cleanup** — return `() => \{ ... \}` to unsubscribe / clear timers.
* **Strict Mode** — React 18+ remounts once in dev to test cleanup.
* **Prefer** — event handlers or data libraries when an “effect” is really a user action.

## 💡 Examples [#-examples]

```tsx
import { useEffect, useState } from "react";

export function User({ id }: { id: string }) {
  const [user, setUser] = useState<{ name: string } | null>(null);

  useEffect(() => {
    const ctrl = new AbortController();
    fetch(`/api/users/${id}`, { signal: ctrl.signal })
      .then((r) => r.json())
      .then(setUser)
      .catch((err) => {
        if (err.name !== "AbortError") console.error(err);
      });
    return () => ctrl.abort();
  }, [id]);

  if (!user) return <p>Loading…</p>;
  return <p>{user.name}</p>;
}
```

```tsx
useEffect(() => {
  const onResize = () => setWidth(window.innerWidth);
  window.addEventListener("resize", onResize);
  return () => window.removeEventListener("resize", onResize);
}, []);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing deps → stale closures; exhaustive-deps lint is your friend.
* Setting state in effects without guards can loop.
* Don’t use effects to transform data for render — compute during render instead.
* Fetch races: abort or ignore outdated responses when `id` changes.

## 🔗 Related [#-related]

* [hooks.md](/docs/react/hooks) — hooks rules
* [useState.md](/docs/react/usestate) — state updates from effects
* [component.md](/docs/react/component) — function components
* [render.md](/docs/react/render) — keep render pure


# useId (/docs/react/useid)



# useId [#useid]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useId()` generates a unique, stable ID string per component instance—safe for SSR hydration. Use to link labels and inputs (`htmlFor` / `id`) or ARIA attributes. Do not use as a list `key`.

## 🔧 Core concepts [#-core-concepts]

* **Stable** — same ID across re-renders for that instance.
* **SSR-safe** — matches server and client trees when structure matches.
* **Prefix** — React may prefix (`:r1:`)—valid in HTML `id` / `htmlFor`.
* **Multiple** — call once and suffix (`$\{id\}-name`, `$\{id\}-email`) for related fields.

## 💡 Examples [#-examples]

```tsx
import { useId } from "react";

export function NameField() {
  const id = useId();
  return (
    <div>
      <label htmlFor={id}>Name</label>
      <input id={id} name="name" />
    </div>
  );
}
```

**Shared base for several controls:**

```tsx
function PasswordFields() {
  const id = useId();
  return (
    <>
      <label htmlFor={`${id}-pw`}>Password</label>
      <input id={`${id}-pw`} type="password" aria-describedby={`${id}-hint`} />
      <p id={`${id}-hint`}>At least 8 characters</p>
    </>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using `useId` as React `key`—keys must come from data identity.
* Generating IDs with `Math.random()` / incrementing counters → hydration mismatches.
* Calling different numbers of `useId` on server vs client.
* Assuming format of the string—treat as opaque.

## 🔗 Related [#-related]

* [forms.md](/docs/react/forms) — accessible forms
* [hooks.md](/docs/react/hooks) — rules
* [jsx.md](/docs/react/jsx) — attributes
* [strict\_mode.md](/docs/react/strict-mode) — double-invoke in dev
* [testing.md](/docs/react/testing) — queries by label


# useLayoutEffect (/docs/react/uselayouteffect)



# useLayoutEffect [#uselayouteffect]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useLayoutEffect` runs synchronously after DOM mutations but before the browser paints. Use for measuring layout (`getBoundingClientRect`) and applying DOM corrections that must not flicker. Prefer `useEffect` for most subscriptions and data loading.

## 🔧 Core concepts [#-core-concepts]

* **Timing** — render → DOM update → layout effects → paint → passive effects.
* **Same API** — `useLayoutEffect(setup, deps)` like `useEffect`.
* **SSR** — warns on server; gate with `typeof window` or use `useEffect`.
* **Blocking** — long work delays paint—keep short.

## 💡 Examples [#-examples]

```tsx
import { useLayoutEffect, useRef, useState } from "react";

export function Tooltip({ text }: { text: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const [height, setHeight] = useState(0);

  useLayoutEffect(() => {
    const node = ref.current;
    if (!node) return;
    setHeight(node.getBoundingClientRect().height);
  }, [text]);

  return (
    <div ref={ref} style={{ marginTop: height > 40 ? 8 : 0 }}>
      {text}
    </div>
  );
}
```

**Scroll restore without flash:**

```tsx
useLayoutEffect(() => {
  listRef.current?.scrollTo(0, savedScrollTop);
}, [items]);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using layout effects for data fetching—blocks paint; use `useEffect` / loaders.
* Infinite loops: layout effect sets state that changes layout deps every time.
* SSR mismatch / warnings—prefer `useEffect` unless measurement is required.
* Heavy computation in layout effect → jank.

## 🔗 Related [#-related]

* [useEffect.md](/docs/react/useeffect) — default effect
* [useRef.md](/docs/react/useref) — DOM refs
* [performance.md](/docs/react/performance) — paint timing
* [hooks.md](/docs/react/hooks) — rules
* [concurrent.md](/docs/react/concurrent) — rendering model


# useMemo (/docs/react/usememo)



# useMemo [#usememo]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useMemo(() => compute(a, b), [a, b])` caches a computed value until dependencies change. Use for expensive pure calculations or to keep referential equality for children/context—not as a default optimization.

## 🔧 Core concepts [#-core-concepts]

* **Signature** — `const memo = useMemo(factory, deps)`.
* **Deps** — recompute when any dep fails `Object.is`.
* **React 19 / Compiler** — compiler may memoize automatically; manual useMemo still valid for guarantees.
* **vs useCallback** — memoize value vs memoize function (`useCallback(fn, deps)` ≈ `useMemo(() => fn, deps)`).

## 💡 Examples [#-examples]

```tsx
import { useMemo, useState } from "react";

export function FilteredList({ items, query }: { items: string[]; query: string }) {
  const filtered = useMemo(() => {
    const q = query.trim().toLowerCase();
    return items.filter((item) => item.toLowerCase().includes(q));
  }, [items, query]);

  return (
    <ul>
      {filtered.map((item) => (
        <li key={item}>{item}</li>
      ))}
    </ul>
  );
}
```

**Stable context value:**

```tsx
const value = useMemo(() => ({ user, logout }), [user, logout]);
return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Memoizing cheap work—overhead can exceed savings.
* Missing deps → stale values; extra deps → useless recomputes.
* Mutating the memoized object/array in place.
* Using `useMemo` to “hide” side effects—factory must be pure.

## 🔗 Related [#-related]

* [useCallback.md](/docs/react/usecallback) — function identity
* [memo.md](/docs/react/memo) — skip child re-renders
* [performance.md](/docs/react/performance) — when to optimize
* [useContext.md](/docs/react/usecontext) — stable provider values
* [hooks.md](/docs/react/hooks) — rules


# useReducer (/docs/react/usereducer)



# useReducer [#usereducer]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useReducer(reducer, initialState)` manages state with a `(state, action) => nextState` function. Prefer when updates are complex, multi-field, or easier to test as pure transitions than scattered `setState` calls.

## 🔧 Core concepts [#-core-concepts]

* **Reducer** — pure; no side effects.
* **Dispatch** — stable identity; `dispatch(action)`.
* **Init** — `useReducer(reducer, initArg, init)` for lazy setup.
* **vs useState** — state for simple values; reducer for structured transitions.
* **Actions** — discriminated unions in TypeScript.

## 💡 Examples [#-examples]

```tsx
import { useReducer } from "react";

type State = { count: number; step: number };
type Action =
  | { type: "increment" }
  | { type: "decrement" }
  | { type: "setStep"; step: number }
  | { type: "reset" };

function reducer(state: State, action: Action): State {
  switch (action.type) {
    case "increment":
      return { ...state, count: state.count + state.step };
    case "decrement":
      return { ...state, count: state.count - state.step };
    case "setStep":
      return { ...state, step: action.step };
    case "reset":
      return { count: 0, step: 1 };
    default:
      return state;
  }
}

export function Counter() {
  const [state, dispatch] = useReducer(reducer, { count: 0, step: 1 });
  return (
    <div>
      <p>{state.count}</p>
      <button type="button" onClick={() => dispatch({ type: "increment" })}>
        +
      </button>
      <button type="button" onClick={() => dispatch({ type: "setStep", step: 5 })}>
        step 5
      </button>
    </div>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Side effects inside reducers (fetch, DOM)—put in effects or event handlers.
* Mutating `state` instead of returning a new object.
* Overusing for a single boolean toggle.
* Forgetting exhaustive `switch` handling in TS.

## 🔗 Related [#-related]

* [useState.md](/docs/react/usestate) — simpler state
* [hooks.md](/docs/react/hooks) — rules
* [context.md](/docs/react/context) — dispatch via context
* [testing.md](/docs/react/testing) — pure reducer tests
* [performance.md](/docs/react/performance) — update patterns


# useRef (/docs/react/useref)



# useRef [#useref]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useRef(initial)` returns a stable `\{ current \}` box that persists across renders without causing re-renders when mutated. Use for DOM nodes, timer IDs, previous values, and imperative handles—not for UI state.

## 🔧 Core concepts [#-core-concepts]

* **Mutable box** — `ref.current = x` does not trigger render.
* **DOM refs** — `ref=\{elRef\}` on host components; read after commit.
* **Same identity** — ref object is stable for the component lifetime.
* **vs state** — state → re-render; ref → silent store.
* **Callback refs** — function form when you need attach/detach logic.

## 💡 Examples [#-examples]

```tsx
import { useEffect, useRef } from "react";

export function TextField() {
  const inputRef = useRef<HTMLInputElement>(null);

  useEffect(() => {
    inputRef.current?.focus();
  }, []);

  return <input ref={inputRef} />;
}
```

**Previous value / interval:**

```tsx
function usePrevious<T>(value: T) {
  const ref = useRef<T>(undefined);
  useEffect(() => {
    ref.current = value;
  }, [value]);
  return ref.current;
}

function Ticker() {
  const idRef = useRef<number | null>(null);
  useEffect(() => {
    idRef.current = window.setInterval(() => {}, 1000);
    return () => {
      if (idRef.current != null) window.clearInterval(idRef.current);
    };
  }, []);
  return null;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Reading/writing `ref.current` during render for values that drive UI—use state.
* Assuming ref is set during first render of a child—refs populate after commit.
* Storing JSX in refs instead of state.
* Forgetting to clear timers/subscriptions stored on refs.

## 🔗 Related [#-related]

* [useEffect.md](/docs/react/useeffect) — sync after paint
* [forwardRef.md](/docs/react/forwardref) — expose refs to parents
* [useLayoutEffect.md](/docs/react/uselayouteffect) — measure DOM before paint
* [hooks.md](/docs/react/hooks) — hook rules
* [forms.md](/docs/react/forms) — uncontrolled inputs


# useState (/docs/react/usestate)



# useState [#usestate]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useState` adds local state to a function component. Calling the setter queues a re-render with the new value.

## 🔧 Core concepts [#-core-concepts]

* **Signature** — `const [state, setState] = useState(initial)`.
* **Lazy init** — `useState(() => expensive())` runs once.
* **Updater form** — `setState(prev => next)` when next depends on previous.
* **Objects/arrays** — replace immutably; don’t mutate then set the same reference.
* **Batching** — React batches updates in event handlers (and more in React 18+).

## 💡 Examples [#-examples]

```tsx
import { useState } from "react";

export function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button type="button" onClick={() => setCount((c) => c + 1)}>
      {count}
    </button>
  );
}
```

```tsx
type Todo = { id: string; text: string; done: boolean };

export function TodoDraft() {
  const [todos, setTodos] = useState<Todo[]>([]);

  function add(text: string) {
    setTodos((prev) => [
      ...prev,
      { id: crypto.randomUUID(), text, done: false },
    ]);
  }

  function toggle(id: string) {
    setTodos((prev) =>
      prev.map((t) => (t.id === id ? { ...t, done: !t.done } : t)),
    );
  }

  return null; // wire UI as needed
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `setState(obj.x++)` / mutating then `setState(obj)` — React may skip the update.
* Using state as the only source when you could derive: `const full = first + last`.
* Storing props in state without a sync strategy → stale UI.
* For complex transitions prefer `useReducer`.

## 🔗 Related [#-related]

* [hooks.md](/docs/react/hooks) — hooks overview
* [useEffect.md](/docs/react/useeffect) — syncing with external systems
* [events.md](/docs/react/events) — updating from handlers
* [props.md](/docs/react/props) — vs lifting state


# useTransition (/docs/react/usetransition)



# useTransition [#usetransition]

*React · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`useTransition` marks state updates as non-urgent so React can keep the UI responsive. Returns `[isPending, startTransition]`. Use for heavy re-renders (filtering large lists, tab switches) while keeping input snappy.

## 🔧 Core concepts [#-core-concepts]

* **Urgent vs transition** — typing stays urgent; list filter can be a transition.
* **`startTransition(fn)`** — wrap the `setState` that triggers expensive UI.
* **`isPending`** — true while the transition is in progress.
* **`useDeferredValue`** — alternative when you defer a value instead of an update.
* **Concurrent** — requires concurrent features (React 18+).

## 💡 Examples [#-examples]

```tsx
import { useState, useTransition } from "react";

export function Search({ items }: { items: string[] }) {
  const [query, setQuery] = useState("");
  const [list, setList] = useState(items);
  const [isPending, startTransition] = useTransition();

  function onChange(e: React.ChangeEvent<HTMLInputElement>) {
    const value = e.target.value;
    setQuery(value); // urgent: update input
    startTransition(() => {
      setList(items.filter((item) => item.includes(value)));
    });
  }

  return (
    <div>
      <input value={query} onChange={onChange} />
      {isPending ? <p>Updating…</p> : null}
      <ul>
        {list.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
    </div>
  );
}
```

**Navigation-style:**

```tsx
startTransition(() => setTab("photos"));
```

## ⚠️ Pitfalls [#️-pitfalls]

* Wrapping controlled input updates in `startTransition` → laggy typing.
* Side effects inside transitions that assume immediate commit.
* Expecting transitions to cancel fetches—pair with AbortController / effects carefully.
* Nested transitions without understanding pending boundaries.

## 🔗 Related [#-related]

* [useDeferredValue.md](/docs/react/usedeferredvalue) — defer a value
* [concurrent.md](/docs/react/concurrent) — concurrent model
* [suspense.md](/docs/react/suspense) — pending UI
* [performance.md](/docs/react/performance) — responsiveness
* [hooks.md](/docs/react/hooks) — rules


# ABC and Protocols (/docs/python/abc-protocols)



# ABC and Protocols [#abc-and-protocols]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Abstract base classes (`abc`) define explicit interfaces with optional `@abstractmethod`. `typing.Protocol` enables structural (duck) typing for static checkers without inheritance. Use ABCs when you need runtime checks; protocols when you want flexibility.

## 🔧 Core concepts [#-core-concepts]

| Tool                 | Role                                |
| -------------------- | ----------------------------------- |
| `ABC`                | Abstract base                       |
| `@abstractmethod`    | Must override                       |
| `isinstance` + ABC   | Runtime virtual subclassing         |
| `Protocol`           | Structural typing                   |
| `@runtime_checkable` | `isinstance` on protocols (limited) |
| `collections.abc`    | Ready-made `Iterable`, `Mapping`, … |

Register virtual subclasses with `ABC.register` when you cannot change the class hierarchy.

## 💡 Examples [#-examples]

**ABC:**

```python
from abc import ABC, abstractmethod

class Repository(ABC):
    @abstractmethod
    def get(self, key: str) -> str: ...

    def get_or_default(self, key: str, default: str = "") -> str:
        try:
            return self.get(key)
        except KeyError:
            return default

class MemoryRepo(Repository):
    def __init__(self) -> None:
        self._data: dict[str, str] = {}

    def get(self, key: str) -> str:
        return self._data[key]
```

**Protocol:**

```python
from typing import Protocol, runtime_checkable

@runtime_checkable
class Closable(Protocol):
    def close(self) -> None: ...

class Handle:
    def close(self) -> None:
        print("closed")

def shutdown(x: Closable) -> None:
    x.close()

assert isinstance(Handle(), Closable)
```

**collections.abc:**

```python
from collections.abc import Sequence

def third(xs: Sequence[str]) -> str:
    return xs[2]

print(third(("a", "b", "c")))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Instantiating a class with unimplemented abstract methods raises `TypeError`.
* `@runtime_checkable` only checks method **presence**, not signatures.
* Protocols with non-method members have more `isinstance` limitations.
* Prefer `collections.abc` types in annotations over concrete `list` when appropriate.
* Don't force ABC inheritance when a Protocol suffices for typing-only needs.

## 🔗 Related [#-related]

* [Typing hints](/docs/python/typing-hints)
* [Classes](/docs/python/classes)
* [Inheritance](/docs/python/inheritance)
* [Collections module](/docs/python/collections-module)
* [Functions](/docs/python/functions)
* [Magic methods](/docs/python/magic-methods)


# Argparse (/docs/python/argparse)



# Argparse [#argparse]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`argparse` builds CLI interfaces: options, flags, subcommands, and help text. Prefer it from the stdlib for scripts; consider `typer`/`click` for richer apps.

## 🔧 Core concepts [#-core-concepts]

| Piece            | Role                      |
| ---------------- | ------------------------- |
| `ArgumentParser` | Root parser               |
| `add_argument`   | Positional or optional    |
| `nargs`          | `?` `*` `+` or int        |
| `type=`          | Converter (`int`, `Path`) |
| `choices=`       | Allowed values            |
| `required=`      | For optionals             |
| Subparsers       | Subcommands               |
| `parse_args`     | Returns namespace         |

Flags start with `-`/`--`. Positionals do not. Auto `--help` is included.

## 💡 Examples [#-examples]

**Simple script:**

```python
import argparse
from pathlib import Path

def main() -> None:
    p = argparse.ArgumentParser(description="Resize images")
    p.add_argument("input", type=Path, help="input file")
    p.add_argument("-o", "--output", type=Path, required=True)
    p.add_argument("-v", "--verbose", action="store_true")
    p.add_argument("--quality", type=int, default=85, choices=range(1, 101))
    args = p.parse_args()
    if args.verbose:
        print("in", args.input, "out", args.output)

if __name__ == "__main__":
    main()
```

**Subcommands:**

```python
import argparse

parser = argparse.ArgumentParser(prog="tool")
sub = parser.add_subparsers(dest="cmd", required=True)

run = sub.add_parser("run", help="run job")
run.add_argument("--workers", type=int, default=1)

show = sub.add_parser("show", help="show status")
show.add_argument("job_id")

args = parser.parse_args()
print(args)
```

**Mutual exclusion:**

```python
import argparse

p = argparse.ArgumentParser()
g = p.add_mutually_exclusive_group()
g.add_argument("--json", action="store_true")
g.add_argument("--plain", action="store_true")
```

## ⚠️ Pitfalls [#️-pitfalls]

* `type=bool` is wrong for flags — use `action="store_true"`.
* `choices=range(...)` works but help text is huge — validate manually if needed.
* Forgetting `required=True` on subparsers (pre-3.7 patterns) allows empty cmd.
* Don't parse args at import time — gate with `main` / `if __name__`.
* Path args still need existence checks — `type=Path` only converts.

## 🔗 Related [#-related]

* [Examples: cli tool](/docs/python/examples/cli-tool)
* [Pathlib](/docs/python/pathlib)
* [Print / input](/docs/python/print-input)
* [Logging](/docs/python/logging)
* [Packaging](/docs/python/packaging)
* [Venv](/docs/python/venv)


# Async (/docs/python/async)



# Async [#async]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`async` / `await` run concurrent I/O with an event loop (`asyncio`). Prefer async for many waiting network/file ops; use threads/processes for CPU-bound work.

## 🔧 Core concepts [#-core-concepts]

| Piece                 | Role                              |
| --------------------- | --------------------------------- |
| `async def`           | Coroutine function                |
| `await`               | Suspend until awaitable completes |
| `asyncio.run(main())` | Entry point                       |
| `asyncio.gather`      | Run many coroutines               |
| `asyncio.create_task` | Schedule concurrently             |
| `asyncio.sleep`       | Non-blocking delay                |

## 💡 Examples [#-examples]

```python
import asyncio

async def fetch(n: int) -> int:
    await asyncio.sleep(0.05)
    return n * 2

async def main() -> None:
    results = await asyncio.gather(fetch(1), fetch(2), fetch(3))
    print(results)

asyncio.run(main())
```

```python
import asyncio

async def worker(name: str) -> None:
    print(name, "start")
    await asyncio.sleep(0.1)
    print(name, "done")

async def main() -> None:
    t1 = asyncio.create_task(worker("a"))
    t2 = asyncio.create_task(worker("b"))
    await t1
    await t2

asyncio.run(main())
```

## ⚠️ Pitfalls [#️-pitfalls]

* Never call blocking I/O inside coroutines without an executor.
* Forgetting `await` returns a coroutine object (often a warning).
* `asyncio.run` cannot nest inside a running loop.
* Mixing sync Django views with async requires care (ASGI).

## 🔗 Related [#-related]

* [concurrency](/docs/python/concurrency)
* [generators](/docs/python/generators)
* [context\_managers](/docs/python/context-managers)
* [Examples/server](/docs/python/examples/server)


# Boolean Logic (/docs/python/boolean-logic)



# Boolean Logic [#boolean-logic]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Boolean logic deals with `True` and `False`. You use it in `if` conditions, loops, and filters. Python’s operators are `and`, `or`, and `not` (words, not `&&` / `||`).

## 🔧 Core concepts [#-core-concepts]

| Piece      | Meaning                                |
| ---------- | -------------------------------------- |
| `bool`     | Type with values `True` / `False`      |
| Comparison | `==`, `!=`, `&lt;`, `>`, `&lt;=`, `>=` |
| `and`      | True only if both sides are true       |
| `or`       | True if at least one side is true      |
| `not`      | Flips truthiness                       |
| Chaining   | `10 &lt; x &lt; 20` works in Python    |

Comparisons return booleans. Many other values are *truthy* or *falsy* when used in conditions (see related note).

## 💡 Examples [#-examples]

**Comparisons:**

```python
age = 18
print(age >= 18)   # True
print(age == 21)   # False
print(age != 0)    # True
```

**and / or / not:**

```python
has_ticket = True
is_weekend = False

print(has_ticket and is_weekend)  # False
print(has_ticket or is_weekend)   # True
print(not is_weekend)             # True
```

**if with boolean expressions:**

```python
temp_c = 22
raining = False

if temp_c > 20 and not raining:
    print("Nice walk weather")
elif raining:
    print("Take an umbrella")
else:
    print("Maybe stay in")
```

**Short-circuit evaluation:**

```python
x = 0
# Right side is skipped because left is False
print(x != 0 and (10 / x > 1))  # False, no ZeroDivisionError

name = ""
label = name or "guest"
print(label)  # guest
```

## ⚠️ Pitfalls [#️-pitfalls]

* `and` / `or` return one of the *operands*, not always a strict `bool`.
* `==` vs `is`: use `==` for values; `is` for identity (`None` is the common exception).
* `1 &lt; x > 0` is valid chaining — read carefully.
* Do not write `if flag == True:` — prefer `if flag:`.

## 🔗 Related [#-related]

* [none\_and\_truthy.md](/docs/python/none-and-truthy)
* [variables.md](/docs/python/variables)
* [indentation.md](/docs/python/indentation)
* [truthiness.md](/docs/python/truthiness)


# Bytes and Bytearray (/docs/python/bytes-bytearray)



# Bytes and Bytearray [#bytes-and-bytearray]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`bytes` is an immutable sequence of ints 0–255; `bytearray` is mutable. Use for binary protocols, files, and encodings. Text is `str` — convert explicitly with `.encode()` / `.decode()`.

## 🔧 Core concepts [#-core-concepts]

| Type         | Mutability | Create                              |
| ------------ | ---------- | ----------------------------------- |
| `bytes`      | Immutable  | `b"hi"`, `bytes([65])`, `bytes(10)` |
| `bytearray`  | Mutable    | `bytearray(b"hi")`                  |
| `memoryview` | View       | Zero-copy slices                    |

Encoding: `s.encode("utf-8")` → `bytes`; `b.decode("utf-8")` → `str`. Hex/base helpers: `.hex()`, `bytes.fromhex`.

## 💡 Examples [#-examples]

**Encode / decode:**

```python
text = "café"
data = text.encode("utf-8")
print(data)                 # b'caf\xc3\xa9'
print(data.decode("utf-8"))
```

**bytearray mutation:**

```python
buf = bytearray(b"python")
buf[0] = ord("P")
buf.extend(b"!")
print(buf)                  # bytearray(b'Python!')
```

**Binary file + memoryview:**

```python
from pathlib import Path

path = Path("blob.bin")
path.write_bytes(b"\x00\x01\x02\x03")
raw = path.read_bytes()
view = memoryview(raw)
print(view[1:3].tobytes())  # b'\x01\x02'
```

**Struct packing:**

```python
import struct

packet = struct.pack(">I4s", 42, b"ping")
code, payload = struct.unpack(">I4s", packet)
print(code, payload)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Indexing returns `int`, not a 1-length bytes: `b"ab"[0] == 97`.
* Mixing `str` and `bytes` raises `TypeError`.
* Wrong encoding (e.g. `latin-1` vs `utf-8`) corrupts text — be explicit.
* `bytes(5)` is five zero bytes, not `b"5"`.
* Large concatenations in a loop — prefer `bytearray` or `b"".join`.

## 🔗 Related [#-related]

* [Strings](/docs/python/strings)
* [Files I/O](/docs/python/files-io)
* [Slicing](/docs/python/slicing)
* [Types](/docs/python/types)
* [Examples: encrypt](/docs/python/examples/encrypt)
* [Pathlib](/docs/python/pathlib)


# Classes (/docs/python/classes)



# Classes [#classes]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Classes define object types: attributes + methods. Prefer clear `__init__`, type hints, and small cohesive classes. For data-heavy records, consider [dataclasses](/docs/python/dataclasses) first.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                                   |
| --------------- | -------------------------------------- |
| `class Name:`   | Creates a type object                  |
| `__init__`      | Instance initializer                   |
| `self`          | Instance reference (conventional name) |
| Instance attr   | `self.x = ...`                         |
| Class attr      | Shared on the class body               |
| `@staticmethod` | No `self` / `cls`                      |
| `@classmethod`  | Receives `cls`                         |
| `@property`     | Managed attribute                      |

Methods are functions on the class; binding supplies `self` on instance access.

## 💡 Examples [#-examples]

**Basic class:**

```python
class User:
    species = "human"  # class attribute

    def __init__(self, name: str, age: int) -> None:
        self.name = name
        self.age = age

    def greet(self) -> str:
        return f"Hi, I'm {self.name}"

    @classmethod
    def from_dict(cls, data: dict[str, object]) -> "User":
        return cls(str(data["name"]), int(data["age"]))  # type: ignore[arg-type]

    @staticmethod
    def is_adult(age: int) -> bool:
        return age >= 18

u = User.from_dict({"name": "Ada", "age": 36})
print(u.greet(), User.is_adult(u.age))
```

**Property:**

```python
class Temperature:
    def __init__(self, celsius: float) -> None:
        self._celsius = celsius

    @property
    def celsius(self) -> float:
        return self._celsius

    @celsius.setter
    def celsius(self, value: float) -> None:
        if value < -273.15:
            raise ValueError("below absolute zero")
        self._celsius = value
```

**Slots (memory / attr lock):**

```python
class Point:
    __slots__ = ("x", "y")

    def __init__(self, x: float, y: float) -> None:
        self.x = x
        self.y = y
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutable class attributes are shared across instances — use instance attrs in `__init__`.
* Forgetting `self` in method signatures causes confusing `TypeError`s.
* `__init__` should not return a value (except `None`).
* String annotations / `from __future__ import annotations` affect runtime `typing.get_type_hints`.
* Prefer composition over deep inheritance trees.

## 🔗 Related [#-related]

* [Inheritance](/docs/python/inheritance)
* [Dataclasses](/docs/python/dataclasses)
* [Magic methods](/docs/python/magic-methods)
* [Properties / descriptors](/docs/python/properties-descriptors)
* [Enums](/docs/python/enums)
* [ABC / protocols](/docs/python/abc-protocols)


# Closures (/docs/python/closures)



# Closures [#closures]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A closure is a function that remembers variables from an enclosing scope after that scope has finished. Closures power decorators, callbacks, and lightweight factories without full classes.

## 🔧 Core concepts [#-core-concepts]

| Idea          | Detail                                              |
| ------------- | --------------------------------------------------- |
| Free variable | Name used but not defined in the inner function     |
| Cell          | Storage for closed-over values                      |
| `nonlocal`    | Rebind an enclosing (non-global) name               |
| `global`      | Rebind a module-level name                          |
| Late binding  | Looks up the name at call time, not definition time |

Inner functions are closures when they reference enclosing locals. Inspect with `fn.__closure__`.

## 💡 Examples [#-examples]

**Factory:**

```python
def make_multiplier(factor: int):
    def multiply(x: int) -> int:
        return x * factor
    return multiply

double = make_multiplier(2)
print(double(5))  # 10
```

**Stateful counter with nonlocal:**

```python
def counter(start: int = 0):
    value = start

    def inc(step: int = 1) -> int:
        nonlocal value
        value += step
        return value

    return inc

c = counter()
print(c(), c(), c(5))  # 1 2 7
```

**Late binding in loops:**

```python
funcs = []
for i in range(3):
    funcs.append(lambda: i)          # all see final i
print([f() for f in funcs])          # [2, 2, 2]

funcs = [lambda i=i: i for i in range(3)]
print([f() for f in funcs])          # [0, 1, 2]
```

**Decorator as closure:**

```python
def ensure_positive(fn):
    def wrapper(x: int) -> int:
        if x < 0:
            raise ValueError("x must be >= 0")
        return fn(x)
    return wrapper

@ensure_positive
def sqrt_int(x: int) -> int:
    return int(x**0.5)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Late binding: closures capture the variable, not the value at creation.
* Assignment in an inner function makes a name local unless `nonlocal`/`global`.
* Closures keep objects alive — can delay GC of large data.
* Prefer explicit objects when state has many fields or methods.
* Mutable closed-over containers can be mutated without `nonlocal`.

## 🔗 Related [#-related]

* [Functions](/docs/python/functions)
* [Decorators](/docs/python/decorators)
* [Scope / namespaces](/docs/python/scope-namespaces)
* [Lambda](/docs/python/lambda)
* [Classes](/docs/python/classes)
* [Walrus](/docs/python/walrus)


# Collections Module (/docs/python/collections-module)



# Collections Module [#collections-module]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`collections` provides specialized container types beyond built-in `list`/`dict`/`set`. Reach for them when counting, defaulting, dequeuing, or naming tuples.

## 🔧 Core concepts [#-core-concepts]

| Type                    | Use                                |
| ----------------------- | ---------------------------------- |
| `Counter`               | Multiset / tallies                 |
| `defaultdict`           | Dict with factory for missing keys |
| `deque`                 | Fast append/pop both ends          |
| `namedtuple`            | Lightweight immutable records      |
| `OrderedDict`           | Rarely needed (dict keeps order)   |
| `ChainMap`              | Layered mappings                   |
| `UserDict` / `UserList` | Wrap for subclassing               |

Also see `collections.abc` for abstract interfaces (`Iterable`, `Mapping`, …).

## 💡 Examples [#-examples]

**Counter:**

```python
from collections import Counter

counts = Counter("abracadabra")
print(counts.most_common(3))
print(counts["a"])
counts.update("aaa")
```

**defaultdict:**

```python
from collections import defaultdict

groups: defaultdict[str, list[int]] = defaultdict(list)
for n in [1, 2, 3, 4]:
    groups["even" if n % 2 == 0 else "odd"].append(n)
```

**deque as queue:**

```python
from collections import deque

q: deque[str] = deque(maxlen=3)
q.append("a")
q.append("b")
q.appendleft("z")
print(q.popleft())
```

**namedtuple / ChainMap:**

```python
from collections import ChainMap, namedtuple

Point = namedtuple("Point", ["x", "y"])
p = Point(1, 2)

defaults = {"color": "blue", "size": 10}
overrides = {"size": 12}
cfg = ChainMap(overrides, defaults)
print(cfg["color"], cfg["size"])
```

## ⚠️ Pitfalls [#️-pitfalls]

* `defaultdict` creates entries on `__getitem__` — use `.get` if you must not insert.
* `Counter` missing keys return `0`, not `KeyError`.
* `namedtuple` is immutable; for mutability use dataclass.
* `OrderedDict` equality historically cared about order — prefer plain `dict`.
* `deque` is not sliceable like a list.

## 🔗 Related [#-related]

* [Dictionaries](/docs/python/dictionaries)
* [Lists](/docs/python/lists)
* [Dataclasses](/docs/python/dataclasses)
* [Itertools](/docs/python/itertools)
* [ABC / protocols](/docs/python/abc-protocols)
* [Examples: list to dict](/docs/python/examples/list-to-dict)


# Comments (/docs/python/comments)



# Comments [#comments]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Comments are notes for humans. The interpreter ignores them. Use them to explain *why*, not to narrate obvious code. Python also has docstrings for documenting modules, classes, and functions.

## 🔧 Core concepts [#-core-concepts]

| Form           | Syntax                     | Use                                  |
| -------------- | -------------------------- | ------------------------------------ |
| Line comment   | `# ...`                    | Short notes on a line                |
| Inline comment | `code  # note`             | Clarify one statement                |
| Docstring      | `"""..."""` or `'''...'''` | Document APIs (not ignored by tools) |
| Shebang        | `#!/usr/bin/env python3`   | Unix script runner hint (first line) |

There is no dedicated multi-line comment syntax. Use multiple `#` lines, or a docstring at the top of a block when documenting.

## 💡 Examples [#-examples]

**Line and inline comments:**

```python
# Calculate weekly pay from hourly rate
rate = 20
hours = 37.5
pay = rate * hours  # overtime not included yet
print(pay)
```

**Docstring on a function:**

```python
def greet(name: str) -> str:
    """Return a friendly greeting for name."""
    return f"Hello, {name}!"


print(greet("Ada"))
print(greet.__doc__)
```

**Module header:**

```python
#!/usr/bin/env python3
"""tiny_demo.py — practice script for comments and print."""

# TODO: add command-line args later
print("ready")
```

**Temporarily disable code (prefer Git, not huge comment blocks):**

```python
# old_way = compute_v1(data)
result = compute_v2(data)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Commented-out code rots quickly — delete it and use version control.
* Docstrings are *strings*, not comments; they become `__doc__`.
* Nesting quotes wrong inside docstrings can break the string.
* Over-commenting (`i = i + 1  # add one`) adds noise.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/python/getting-started)
* [hello\_world.md](/docs/python/hello-world)
* [variables.md](/docs/python/variables)
* [indentation.md](/docs/python/indentation)


# Comprehensions (/docs/python/comprehensions)



# Comprehensions [#comprehensions]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Comprehensions build lists, sets, dicts, and generator expressions concisely. Prefer them over manual loops for simple map/filter transforms. Keep them readable — nest sparingly.

## 🔧 Core concepts [#-core-concepts]

| Form                         | Result                      |
| ---------------------------- | --------------------------- |
| `[expr for x in it if cond]` | `list`                      |
| `\{expr for x in it\}`       | `set`                       |
| `\{k: v for ...\}`           | `dict`                      |
| `(expr for x in it)`         | Generator (lazy)            |
| Nested                       | `for` clauses left-to-right |
| Walrus                       | `:=` inside filters (3.8+)  |

Scope: iteration variables leak in list/set/dict comps in 3.x? Actually in Python 3, comprehension iteration variables are isolated in their own scope (unlike 2.x).

## 💡 Examples [#-examples]

**List / set / dict:**

```python
nums = range(8)
squares = [n * n for n in nums if n % 2 == 0]
unique_lens = {len(w) for w in ["a", "bb", "ccc", "bb"]}
index = {c: i for i, c in enumerate("abc")}
```

**Nested:**

```python
matrix = [[1, 2], [3, 4]]
flat = [x for row in matrix for x in row]
pairs = [(i, j) for i in range(3) for j in range(3) if i != j]
```

**Generator expression:**

```python
total = sum(n * n for n in range(1_000_000))  # no giant list
lines = (line.strip() for line in open("f.txt", encoding="utf-8"))
# prefer pathlib + context manager in real code
```

**Walrus in comprehension:**

```python
def normalize(s: str) -> str:
    return s.strip().lower()

names = [" Ada ", "Bob", "  "]
clean = [n for name in names if (n := normalize(name))]
# ["ada", "bob"]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Over-nested comps are worse than a plain loop.
* Dict comps: later keys overwrite earlier ones silently.
* Side effects inside comps hurt readability — avoid prints/mutations.
* Generator expressions are single-pass — materialize with `list()` if reused.
* Huge list comps can exhaust memory; use generators.

## 🔗 Related [#-related]

* [Lists](/docs/python/lists)
* [Dictionaries](/docs/python/dictionaries)
* [Sets](/docs/python/sets)
* [Generators](/docs/python/generators)
* [Loops](/docs/python/loops)
* [Walrus](/docs/python/walrus)


# Concurrency (/docs/python/concurrency)



# Concurrency [#concurrency]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Python offers threads, processes, and asyncio for concurrent work. Choose based on the bottleneck: **I/O-bound** → threads or asyncio; **CPU-bound** → multiprocessing (GIL limits CPU threads). See [async.md](/docs/python/async) for `async`/`await` detail.

## 🔧 Core concepts [#-core-concepts]

| Model           | Best for                                | Module                                   |
| --------------- | --------------------------------------- | ---------------------------------------- |
| Threading       | I/O, shared memory                      | `threading`, `concurrent.futures`        |
| Multiprocessing | CPU parallelism                         | `multiprocessing`, `ProcessPoolExecutor` |
| Asyncio         | Many sockets / timers                   | `asyncio`                                |
| GIL             | One bytecode thread at a time (CPython) | —                                        |

`concurrent.futures` unifies thread/process pools behind `Executor.map` / `submit`.

## 💡 Examples [#-examples]

**ThreadPoolExecutor (I/O):**

```python
from concurrent.futures import ThreadPoolExecutor, as_completed
from urllib.request import urlopen

urls = ["https://example.com", "https://httpbin.org/get"]

def fetch(url: str) -> int:
    with urlopen(url, timeout=10) as resp:
        return resp.status

with ThreadPoolExecutor(max_workers=8) as pool:
    futures = {pool.submit(fetch, u): u for u in urls}
    for fut in as_completed(futures):
        print(futures[fut], fut.result())
```

**ProcessPoolExecutor (CPU):**

```python
from concurrent.futures import ProcessPoolExecutor

def crunch(n: int) -> int:
    return sum(i * i for i in range(n))

if __name__ == "__main__":
    with ProcessPoolExecutor() as pool:
        print(list(pool.map(crunch, [10**6, 10**6])))
```

**asyncio overview:**

```python
import asyncio

async def sleeper(name: str, delay: float) -> str:
    await asyncio.sleep(delay)
    return name

async def main() -> None:
    results = await asyncio.gather(sleeper("a", 0.1), sleeper("b", 0.2))
    print(results)

asyncio.run(main())
```

## ⚠️ Pitfalls [#️-pitfalls]

* CPU-bound work in threads won't scale on CPython due to the GIL.
* Share state only with locks/queues — races are subtle.
* On Windows, process entry must be under `if __name__ == "__main__"`.
* Mixing blocking I/O inside asyncio stalls the event loop — use `to_thread`.
* Deadlocks: never lock in inconsistent orders across threads.

## 🔗 Related [#-related]

* [Async / await](/docs/python/async)
* [Context managers](/docs/python/context-managers)
* [Logging](/docs/python/logging)
* [Examples: server](/docs/python/examples/server)
* [Examples: retry backoff](/docs/python/examples/retry-backoff)
* [Testing with pytest](/docs/python/testing-pytest)


# Conditionals (/docs/python/conditionals)



# Conditionals [#conditionals]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Branch with `if` / `elif` / `else` and structural `match` / `case` (3.10+). Prefer clear boolean expressions and pattern matching for nested dict/tag shapes over deep `if` ladders.

## 🔧 Core concepts [#-core-concepts]

| Form                   | Use                         |
| ---------------------- | --------------------------- |
| `if` / `elif` / `else` | Boolean branches            |
| Ternary                | `a if cond else b`          |
| `match` / `case`       | Structural pattern matching |
| Guards                 | `case x if pred:`           |
| OR patterns            | `case 1 \| 2:`              |
| Capture                | `case \{"id": int(uid)\}:`  |
| Wildcard               | `case _:`                   |

Truthiness rules apply in `if` — see [truthiness](/docs/python/truthiness). `match` compares structure and can bind names.

## 💡 Examples [#-examples]

**Classic if:**

```python
def grade(score: int) -> str:
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "F"

label = "pass" if grade(85) != "F" else "fail"
```

**Match literals and guards:**

```python
def handle(code: int) -> str:
    match code:
        case 200 | 201:
            return "ok"
        case 404:
            return "missing"
        case n if 500 <= n < 600:
            return "server"
        case _:
            return "other"
```

**Match mapping / sequence:**

```python
def route(event: dict[str, object]) -> str:
    match event:
        case {"type": "user", "id": int(uid)} if uid > 0:
            return f"user:{uid}"
        case {"type": "ping"}:
            return "pong"
        case {"items": [first, *rest]}:
            return f"first={first}, n={len(rest)+1}"
        case _:
            return "unknown"
```

**Match class patterns:**

```python
from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

def quadrant(p: Point) -> str:
    match p:
        case Point(x=0, y=0):
            return "origin"
        case Point(x=x, y=y) if x > 0 and y > 0:
            return "I"
        case Point():
            return "elsewhere"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `case x:` captures everything — put specific patterns first.
* `match` subject is evaluated once; patterns do not fall through like C `switch`.
* Avoid chained ternaries — hard to read.
* `==` vs `is`: use `is` for `None` / singletons.
* Empty patterns and overlapping captures can surprise — test edge cases.

## 🔗 Related [#-related]

* [Truthiness](/docs/python/truthiness)
* [Operators](/docs/python/operators)
* [Enums](/docs/python/enums)
* [Dataclasses](/docs/python/dataclasses)
* [Dictionaries](/docs/python/dictionaries)
* [Walrus](/docs/python/walrus)


# Context Managers (/docs/python/context-managers)



# Context Managers [#context-managers]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Context managers guarantee setup/teardown via `with`. They close files, release locks, and restore state even when exceptions occur. Implement with `__enter__`/`__exit__` or `@contextlib.contextmanager`.

## 🔧 Core concepts [#-core-concepts]

| API                             | Role                                   |
| ------------------------------- | -------------------------------------- |
| `with cm as x:`                 | Enter, bind result, exit on leave      |
| Multiple                        | `with a, b:`                           |
| Parenthesized                   | Multi-line `with` (3.10+)              |
| `__enter__`                     | Setup; return bound value              |
| `__exit__`                      | Cleanup; return truthy to suppress exc |
| `contextlib.contextmanager`     | Generator-based CM                     |
| `ExitStack`                     | Dynamic stack of contexts              |
| `AsyncExitStack` / `async with` | Async variants                         |

`__exit__(exc_type, exc, tb)` — return `True` to suppress the exception (rare).

## 💡 Examples [#-examples]

**Built-in file and lock:**

```python
from pathlib import Path
from threading import Lock

lock = Lock()
path = Path("out.txt")

with lock, path.open("w", encoding="utf-8") as f:
    f.write("hello\n")
```

**Generator context manager:**

```python
from contextlib import contextmanager
from collections.abc import Iterator

@contextmanager
def temp_attr(obj: object, name: str, value: object) -> Iterator[None]:
    old = getattr(obj, name)
    setattr(obj, name, value)
    try:
        yield
    finally:
        setattr(obj, name, old)

class C:
    mode = "prod"

with temp_attr(C, "mode", "test"):
    assert C.mode == "test"
```

**Class-based:**

```python
class suppress_os:
    def __enter__(self) -> "suppress_os":
        return self

    def __exit__(self, exc_type, exc, tb) -> bool:
        return exc_type is not None and issubclass(exc_type, OSError)
```

**ExitStack:**

```python
from contextlib import ExitStack
from pathlib import Path

paths = [Path("a.txt"), Path("b.txt")]
with ExitStack() as stack:
    files = [stack.enter_context(p.open("w", encoding="utf-8")) for p in paths]
    for f in files:
        f.write("x\n")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Returning `True` from `__exit__` swallows exceptions — usually wrong.
* Yielding inside `@contextmanager` after errors needs careful `try/finally`.
* Nested `with` order: enter left-to-right, exit right-to-left.
* Don't open resources without `with` unless you manage close yourself.
* Async code needs `async with` and async context managers.

## 🔗 Related [#-related]

* [Exceptions](/docs/python/exceptions)
* [Files I/O](/docs/python/files-io)
* [Pathlib](/docs/python/pathlib)
* [Magic methods](/docs/python/magic-methods)
* [Concurrency](/docs/python/concurrency)
* [Async / await](/docs/python/async)


# Copy and Deepcopy (/docs/python/copy-deepcopy)



# Copy and Deepcopy [#copy-and-deepcopy]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Assignment binds names to objects; it does not copy. Use slicing/`list()`/`copy.copy` for shallow copies and `copy.deepcopy` for nested structures. Know when shared references are intentional.

## 🔧 Core concepts [#-core-concepts]

| Operation                   | Effect                                               |
| --------------------------- | ---------------------------------------------------- |
| `b = a`                     | Same object                                          |
| `a.copy()` / `copy.copy(a)` | Shallow copy                                         |
| `a[:]` (list)               | Shallow copy                                         |
| `copy.deepcopy(a)`          | Recursive copy                                       |
| Immutable                   | Often no need to copy (`str`, `tuple` of immutables) |

Shallow: new container, same nested objects. Deep: nested containers cloned (with cycle handling).

## 💡 Examples [#-examples]

**Alias vs shallow:**

```python
import copy

a = [[1], [2]]
alias = a
shallow = copy.copy(a)      # or a[:] / list(a)
alias[0].append(9)
print(a, shallow)           # both see [1, 9] in first row
```

**Deepcopy:**

```python
import copy

a = [[1], [2]]
deep = copy.deepcopy(a)
a[0].append(9)
print(a)     # [[1, 9], [2]]
print(deep)  # [[1], [2]]
```

**Dict / custom:**

```python
import copy

cfg = {"db": {"host": "localhost"}, "debug": True}
cfg2 = {**cfg}                 # shallow
cfg3 = copy.deepcopy(cfg)

class Node:
    def __init__(self, value: int) -> None:
        self.value = value
        self.child: Node | None = None

n = Node(1)
n.child = Node(2)
m = copy.deepcopy(n)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `list * n` / `[[0]*3]*3` creates shared inner rows — classic bug.
* Deepcopy can be slow and fail on locks, sockets, modules, or some C objects.
* Dataclass `replace` is shallow for nested mutables.
* Copying is not serialization — for disk/network use JSON/pickle carefully.
* `__copy__` / `__deepcopy__` can customize behavior on your classes.

## 🔗 Related [#-related]

* [Lists](/docs/python/lists)
* [Dictionaries](/docs/python/dictionaries)
* [Dataclasses](/docs/python/dataclasses)
* [Slicing](/docs/python/slicing)
* [Types](/docs/python/types)
* [Scope / namespaces](/docs/python/scope-namespaces)


# Csv (/docs/python/csv)



# Csv [#csv]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The stdlib `csv` module reads and writes delimited text. Use `DictReader`/`DictWriter` when rows have named columns; plain `reader`/`writer` for positional fields. Prefer `newline=""` when opening files on Windows.

## 🔧 Core concepts [#-core-concepts]

| API                             | Role                            |
| ------------------------------- | ------------------------------- |
| `csv.reader(f)`                 | Iterate rows as lists           |
| `csv.DictReader(f)`             | Rows as `dict` (header → value) |
| `csv.writer(f)`                 | Write list rows                 |
| `csv.DictWriter(f, fieldnames)` | Write dict rows                 |
| `writerow` / `writerows`        | One / many rows                 |
| `writeheader()`                 | Emit header for DictWriter      |
| `dialect` / `delimiter`         | CSV flavor (excel, `;`, etc.)   |
| `csv.QUOTE_MINIMAL`             | Quoting strategy                |

For large analytics, use [Pandas](/docs/python/pandas) `read_csv` instead.

## 💡 Examples [#-examples]

**DictReader:**

```python
import csv
from pathlib import Path

with Path("people.csv").open(newline="", encoding="utf-8") as f:
    for row in csv.DictReader(f):
        print(row["name"], row["age"])
```

**reader (lists):**

```python
import csv

with open("data.csv", newline="", encoding="utf-8") as f:
    rows = list(csv.reader(f))
header, *body = rows
print(header, body[:2])
```

**DictWriter:**

```python
import csv
from pathlib import Path

fields = ["name", "age"]
rows = [{"name": "Ada", "age": 36}, {"name": "Lin", "age": 41}]

with Path("out.csv").open("w", newline="", encoding="utf-8") as f:
    w = csv.DictWriter(f, fieldnames=fields)
    w.writeheader()
    w.writerows(rows)
```

**Custom delimiter:**

```python
import csv

with open("eu.csv", newline="", encoding="utf-8") as f:
    for row in csv.reader(f, delimiter=";"):
        print(row)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Always open with `newline=""` so the csv module owns line endings.
* Pass `encoding="utf-8"` (or the real encoding) — never rely on locale default.
* `DictWriter` needs `fieldnames`; missing keys become empty cells unless `extrasaction="raise"`.
* Excel may expect BOM / `;` — test with the consumer.
* Nested commas need quoting; let `csv` handle it — don’t hand-split lines.

## 🔗 Related [#-related]

* [Pandas](/docs/python/pandas)
* [Files I/O](/docs/python/files-io)
* [Pathlib](/docs/python/pathlib)
* [Json](/docs/python/json)


# Dataclasses (/docs/python/dataclasses)



# Dataclasses [#dataclasses]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`dataclasses.dataclass` auto-generates `__init__`, `__repr__`, `__eq__`, and optionally ordering/hash/slots for classes that mainly store data. Prefer dataclasses over hand-written boilerplate for records and DTOs.

## 🔧 Core concepts [#-core-concepts]

| Option               | Effect                                    |
| -------------------- | ----------------------------------------- |
| `@dataclass`         | Generate methods from annotated fields    |
| `frozen=True`        | Immutable instances (approx.)             |
| `slots=True`         | `__slots__` (3.10+) — less memory         |
| `order=True`         | `&lt;`, `&lt;=`, … from field order       |
| `kw_only=True`       | Keyword-only fields (3.10+)               |
| `field(...)`         | Defaults, factories, exclude from compare |
| `asdict` / `astuple` | Convert to built-ins                      |

Fields need type annotations. Default values must follow non-default fields (or use `kw_only`).

## 💡 Examples [#-examples]

**Basic and factory defaults:**

```python
from dataclasses import dataclass, field

@dataclass
class Config:
    host: str
    port: int = 8000
    tags: list[str] = field(default_factory=list)

cfg = Config("localhost", tags=["dev"])
```

**Frozen + slots:**

```python
from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class Point:
    x: float
    y: float

p = Point(1.0, 2.0)
# p.x = 3  # FrozenInstanceError
```

**Post-init validation:**

```python
from dataclasses import dataclass

@dataclass
class User:
    name: str
    age: int

    def __post_init__(self) -> None:
        if self.age < 0:
            raise ValueError("age must be >= 0")
```

**Replace and asdict:**

```python
from dataclasses import asdict, replace

u = User("Ada", 36)
u2 = replace(u, age=37)
print(asdict(u2))  # {"name": "Ada", "age": 37}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutable defaults need `field(default_factory=...)`, not `= []`.
* `frozen=True` is shallow — nested mutables can still change.
* `asdict` deep-copies nested dataclasses into dicts — can be expensive.
* Inheritance: dataclass parents/children need care with field ordering.
* For complex validation / ORM models, consider Pydantic or attrs.

## 🔗 Related [#-related]

* [Classes](/docs/python/classes)
* [Enums](/docs/python/enums)
* [Typing hints](/docs/python/typing-hints)
* [Copy / deepcopy](/docs/python/copy-deepcopy)
* [Examples: dataclass pipeline](/docs/python/examples/dataclass-pipeline)
* [Tuples](/docs/python/tuples)


# Datetime (/docs/python/datetime)



# Datetime [#datetime]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`datetime` handles dates, times, timedeltas, and timezones. Prefer **aware** datetimes (`tzinfo` set) over naive ones. Use `zoneinfo` (3.9+) for IANA timezones.

## 🔧 Core concepts [#-core-concepts]

| Type                          | Role          |
| ----------------------------- | ------------- |
| `date`                        | Calendar date |
| `time`                        | Time of day   |
| `datetime`                    | Date + time   |
| `timedelta`                   | Duration      |
| `timezone.utc`                | Fixed UTC     |
| `zoneinfo.ZoneInfo`           | IANA TZ       |
| `isoformat` / `fromisoformat` | ISO-8601      |

Arithmetic: `datetime ± timedelta`. Comparing naive vs aware raises `TypeError`.

## 💡 Examples [#-examples]

**UTC now and ISO:**

```python
from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)
later = now + timedelta(hours=2)
print(now.isoformat())
print(datetime.fromisoformat("2024-07-10T12:00:00+00:00"))
```

**ZoneInfo:**

```python
from datetime import datetime
from zoneinfo import ZoneInfo

ny = ZoneInfo("America/New_York")
local = datetime(2024, 7, 10, 9, 0, tzinfo=ny)
utc = local.astimezone(ZoneInfo("UTC"))
print(local, utc)
```

**Parsing common formats:**

```python
from datetime import datetime

dt = datetime.strptime("10/07/2024 14:30", "%d/%m/%Y %H:%M")
print(dt.strftime("%Y-%m-%d"))
```

**Date math:**

```python
from datetime import date, timedelta

start = date(2024, 7, 10)
print(start + timedelta(days=7))
print((date.today() - start).days)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Naive `datetime.now()` is ambiguous — prefer `datetime.now(timezone.utc)`.
* `utcnow()` is deprecated in 3.12 — use `now(timezone.utc)`.
* DST transitions: local arithmetic can skip/repeat hours — convert via UTC.
* `timestamp()` on naive assumes local time — be explicit.
* Don't store local times without offset in databases when possible.

## 🔗 Related [#-related]

* [JSON](/docs/python/json)
* [Logging](/docs/python/logging)
* [Types](/docs/python/types)
* [F-strings](/docs/python/f-string)
* [Examples: retry backoff](/docs/python/examples/retry-backoff)
* [Argparse](/docs/python/argparse)


# Decorators (/docs/python/decorators)



# Decorators [#decorators]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A decorator is a callable that wraps another callable to add behavior (logging, timing, caching, auth). Syntax `@decorator` above `def`/`class` is sugar for `f = decorator(f)`. Preserve metadata with `functools.wraps`.

## 🔧 Core concepts [#-core-concepts]

| Piece                 | Role                                    |
| --------------------- | --------------------------------------- |
| `@dec`                | `f = dec(f)`                            |
| `@dec(args)`          | `f = dec(args)(f)` — factory            |
| `functools.wraps`     | Copy `__name__`, `__doc__`, annotations |
| `functools.lru_cache` | Memoization                             |
| `functools.cache`     | Unbounded cache (3.9+)                  |
| Class decorators      | Transform / register classes            |
| Stacked               | Applied bottom-up                       |

Decorators work on methods too; be careful with `self` and descriptors.

## 💡 Examples [#-examples]

**Simple wrapper:**

```python
import functools
import time
from collections.abc import Callable
from typing import TypeVar

F = TypeVar("F", bound=Callable[..., object])

def timed(fn: F) -> F:
    @functools.wraps(fn)
    def wrapper(*args: object, **kwargs: object) -> object:
        start = time.perf_counter()
        try:
            return fn(*args, **kwargs)
        finally:
            print(f"{fn.__name__}: {time.perf_counter() - start:.4f}s")
    return wrapper  # type: ignore[return-value]

@timed
def work(n: int) -> int:
    return sum(range(n))
```

**Decorator with arguments:**

```python
def repeat(times: int):
    def deco(fn: Callable[..., object]) -> Callable[..., object]:
        @functools.wraps(fn)
        def wrapper(*args: object, **kwargs: object) -> object:
            result = None
            for _ in range(times):
                result = fn(*args, **kwargs)
            return result
        return wrapper
    return deco

@repeat(3)
def ping() -> str:
    print("ping")
    return "ok"
```

**Built-ins:**

```python
from functools import cache, lru_cache

@cache
def fib(n: int) -> int:
    return n if n < 2 else fib(n - 1) + fib(n - 2)

@lru_cache(maxsize=128)
def load(key: str) -> str:
    return key.upper()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `@wraps` breaks introspection, tests, and OpenAPI tools.
* Order of stacked decorators matters (`@a` then `@b` → `a(b(f))`).
* Caching mutable/unhashable args fails with `lru_cache`.
* Decorating instance methods: wrapper still receives `self` as first arg.
* Class decorators replace the class object — return the class (or a new one).

## 🔗 Related [#-related]

* [Functions](/docs/python/functions)
* [Closures](/docs/python/closures)
* [Classes](/docs/python/classes)
* [Properties / descriptors](/docs/python/properties-descriptors)
* [Typing hints](/docs/python/typing-hints)
* [Logging](/docs/python/logging)


# Dictionaries (/docs/python/dictionaries)



# Dictionaries [#dictionaries]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A `dict` maps hashable keys to values. Insertion order is preserved (3.7+). Use for lookups, configs, JSON-like data, and counting. Prefer `dict` / `collections.Counter` / `defaultdict` over ad-hoc nested structures when possible.

## 🔧 Core concepts [#-core-concepts]

**Create / access / mutate**

| Operation  | Example                                                                      |
| ---------- | ---------------------------------------------------------------------------- |
| Create     | `\{"a": 1\}`, `dict(a=1)`, `dict([("a", 1)])`, `dict.fromkeys(keys, v=None)` |
| Get        | `d["a"]` (KeyError), `d.get("a", default)`                                   |
| Set        | `d["a"] = 1`, `d.setdefault("a", 0)`                                         |
| Delete     | `del d["a"]`, `d.pop("a", default)`, `d.popitem()` (LIFO 3.7+)               |
| Clear      | `d.clear()`                                                                  |
| Membership | `k in d`, `k not in d` (keys only)                                           |

**Instance methods**

| Method                           | Notes                                            |
| -------------------------------- | ------------------------------------------------ |
| `get(k[, default])`              | Return value or default (`None`)                 |
| `setdefault(k[, default])`       | Get or insert default; return value              |
| `update([other], **kw)`          | Merge mappings/pairs in place                    |
| `pop(k[, default])`              | Remove key; return value (or default / KeyError) |
| `popitem()`                      | Remove and return `(k, v)` last inserted         |
| `clear()`                        | Remove all items                                 |
| `copy()`                         | Shallow copy                                     |
| `fromkeys(iterable, value=None)` | Classmethod: new dict with shared default        |

**Merge operators (3.9+)**

| Op             | Notes                           |
| -------------- | ------------------------------- |
| `a \| b`       | New dict; `b` wins on conflicts |
| `a \|= b`      | In-place update like `update`   |
| `\{**a, **b\}` | Unpack merge (literal)          |

**Views — `keys` / `values` / `items`**

| View                  | Notes                                                    |
| --------------------- | -------------------------------------------------------- |
| `d.keys()`            | Dynamic set-like view of keys                            |
| `d.values()`          | Dynamic view of values                                   |
| `d.items()`           | Dynamic set-like view of `(k, v)`                        |
| Set ops on keys/items | `&`, `\|`, `-`, `^` with other views/sets                |
| Live views            | Reflect dict changes; do not mutate dict while iterating |
| Materialize           | `list(d)`, `list(d.items())` for a stable snapshot       |

**Comprehension / related helpers**

| Pattern                      | Notes                                            |
| ---------------------------- | ------------------------------------------------ |
| `\{k: v for k, v in pairs\}` | Dict comprehension                               |
| `collections.Counter`        | Multiset / counts                                |
| `collections.defaultdict`    | Auto-create missing values                       |
| `collections.OrderedDict`    | Reorder helpers; plain `dict` keeps insert order |

Keys must be hashable (`str`, `int`, `tuple` of hashables—not `list`/`dict`).

## 💡 Examples [#-examples]

**Safe access and merge:**

```python
user = {"id": 1, "name": "Ada"}
role = {"role": "admin"}

print(user.get("email", "n/a"))
merged = user | role  # {"id": 1, "name": "Ada", "role": "admin"}
```

**Counting and grouping:**

```python
from collections import Counter, defaultdict

words = ["a", "b", "a", "c", "b", "a"]
print(Counter(words))  # Counter({'a': 3, 'b': 2, 'c': 1})

by_len: dict[int, list[str]] = defaultdict(list)
for w in words:
    by_len[len(w)].append(w)
```

**Dict comprehension / invert:**

```python
scores = {"alice": 10, "bob": 7}
passed = {k: v for k, v in scores.items() if v >= 8}
# invert (values must be unique/hashable)
inv = {v: k for k, v in scores.items()}
```

**Pattern matching (3.10+):**

```python
payload = {"type": "user", "id": 42}

match payload:
    case {"type": "user", "id": int(uid)}:
        print("user", uid)
    case _:
        print("unknown")
```

## ⚠️ Pitfalls [#️-pitfalls]

* `d[key]` raises `KeyError` if missing—use `.get` or `in`.
* Mutating a dict while iterating its views is unsafe; iterate over `list(d)` or copy.
* Nested dicts share references—`copy()` is shallow; use `copy.deepcopy` when needed.
* Using unhashable types as keys raises `TypeError`.
* `dict` equality ignores order; do not rely on order for identity checks.

## 🔗 Related [#-related]

* [Types](/docs/python/types)
* [Loops](/docs/python/loops)
* [\*args and \*\*kwargs](/docs/python/kwags)
* [Strings](/docs/python/strings)
* [Examples: list to dict](/docs/python/examples/list-to-dict)
* [Examples: merge lists](/docs/python/examples/merge-lists)


# Docstrings (/docs/python/docstrings)



# Docstrings [#docstrings]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Docstrings are string literals as the first statement in a module, class, function, or method. Tools (`help()`, Sphinx, IDEs) read them via `__doc__`. Prefer clear one-liners for simple APIs; use structured styles (Google, NumPy, reST) for public libraries.

## 🔧 Core concepts [#-core-concepts]

| Rule       | Detail                                                      |
| ---------- | ----------------------------------------------------------- |
| Placement  | First statement inside the body                             |
| Style      | Triple quotes `"""..."""` (PEP 257)                         |
| One-liner  | Imperative mood: `"""Return the user's display name."""`    |
| Multi-line | Summary line, blank line, then details                      |
| Attributes | Document on the class or via Attributes section             |
| Type hints | Prefer annotations; docstring describes behavior, not types |

Common sections: `Args`, `Returns`, `Raises`, `Yields`, `Examples`, `Note`.

## 💡 Examples [#-examples]

**Google style:**

```python
def divide(a: float, b: float) -> float:
    """Divide ``a`` by ``b``.

    Args:
        a: Numerator.
        b: Denominator; must be non-zero.

    Returns:
        The quotient ``a / b``.

    Raises:
        ZeroDivisionError: If ``b`` is 0.
    """
    return a / b
```

**Module and class:**

```python
"""User authentication helpers.

This module wraps password hashing and session tokens.
"""

class Session:
    """In-memory session store for a single process."""

    def get(self, key: str) -> str | None:
        """Return the value for ``key``, or ``None`` if missing."""
        ...
```

**Access at runtime:**

```python
def greet(name: str) -> str:
    """Return a greeting for ``name``."""
    return f"Hello, {name}"

print(greet.__doc__)
help(greet)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Comments (`#`) are not docstrings and are not exposed via `help()`.
* Putting code between the signature and the docstring breaks `__doc__`.
* Do not duplicate type information already in annotations.
* Keep examples in docstrings executable when using doctest; stale examples mislead.
* Private helpers can use short one-liners; over-documenting noise hurts readability.

## 🔗 Related [#-related]

* [Types](/docs/python/types)
* [F-strings](/docs/python/f-string)
* [Import / export](/docs/python/import-export)
* [\*args and \*\*kwargs](/docs/python/kwags)
* [Strings](/docs/python/strings)


# Dotenv (/docs/python/dotenv)



# Dotenv [#dotenv]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`python-dotenv` loads a `.env` file into `os.environ` so local secrets stay out of source. Install: `pip install python-dotenv`. Call `load_dotenv()` early (app entrypoint), then read with `os.getenv`.

## 🔧 Core concepts [#-core-concepts]

| API                 | Role                                             |
| ------------------- | ------------------------------------------------ |
| `load_dotenv()`     | Load `.env` from cwd / parents into `os.environ` |
| `load_dotenv(path)` | Explicit file path                               |
| `override=False`    | Default: don’t clobber existing env              |
| `find_dotenv()`     | Locate nearest `.env`                            |
| `os.getenv("KEY")`  | Read after load                                  |
| `os.environ["KEY"]` | Read/set in process                              |

Typical `.env` lines: `KEY=value` (no quotes needed for simple values). Never commit real secrets — keep `.env` in `.gitignore`.

## 💡 Examples [#-examples]

**Basic load:**

```python
import os
from dotenv import load_dotenv

load_dotenv()  # reads .env
db_url = os.getenv("DATABASE_URL")
debug = os.getenv("DEBUG", "0") == "1"
print(bool(db_url), debug)
```

**Explicit path:**

```python
from pathlib import Path
from dotenv import load_dotenv
import os

env_path = Path(__file__).resolve().parent / ".env"
load_dotenv(env_path)
print(os.environ.get("API_KEY", ""))
```

**Override existing vars:**

```python
from dotenv import load_dotenv
import os

os.environ["APP_ENV"] = "prod"
load_dotenv(override=True)  # .env wins
print(os.getenv("APP_ENV"))
```

**Fail fast if required:**

```python
import os
from dotenv import load_dotenv

load_dotenv()
token = os.getenv("SECRET_TOKEN")
if not token:
    raise SystemExit("SECRET_TOKEN is required")
```

## ⚠️ Pitfalls [#️-pitfalls]

* `load_dotenv` does not raise if `.env` is missing — check return value or required keys.
* Default `override=False`: shell/CI env wins over `.env`.
* Values are strings; parse bools carefully (`"false"` is truthy in Python).
* Don’t commit `.env`; ship `.env.example` with dummy keys.
* Calling `load_dotenv` late (after code already read env) is a common bug.

## 🔗 Related [#-related]

* [Os](/docs/python/os)
* [Venv](/docs/python/venv)
* [Pip](/docs/python/pip)
* [Argparse](/docs/python/argparse)


# Enums (/docs/python/enums)



# Enums [#enums]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`enum.Enum` defines a set of named symbolic values. Use enums instead of magic strings/ints for status codes, modes, and options. Python 3.11+ adds `StrEnum`, improved `Flag`, and more.

## 🔧 Core concepts [#-core-concepts]

| Type               | Use                                |
| ------------------ | ---------------------------------- |
| `Enum`             | Classic named values               |
| `IntEnum`          | Comparable to `int`                |
| `StrEnum`          | `str` mixin (3.11+)                |
| `Flag` / `IntFlag` | Bitwise combinations               |
| `auto()`           | Auto-assign values                 |
| `enum.unique`      | Decorator: forbid duplicate values |

Members are singletons: `Color.RED is Color.RED`. Access by name (`Color["RED"]`) or value (`Color(1)`).

## 💡 Examples [#-examples]

**Basic Enum:**

```python
from enum import Enum, auto

class Status(Enum):
    PENDING = auto()
    RUNNING = auto()
    DONE = auto()

s = Status.RUNNING
print(s.name, s.value)
print(Status["DONE"])
```

**StrEnum (3.11+):**

```python
from enum import StrEnum

class Role(StrEnum):
    ADMIN = "admin"
    USER = "user"

def greet(role: Role) -> str:
    return f"hello {role}"  # role is a str

assert Role.ADMIN == "admin"
```

**Flags:**

```python
from enum import Flag, auto

class Perm(Flag):
    READ = auto()
    WRITE = auto()
    EXEC = auto()

rw = Perm.READ | Perm.WRITE
print(Perm.READ in rw)
print(bool(rw & Perm.EXEC))
```

**Match (3.10+):**

```python
match Status.DONE:
    case Status.PENDING | Status.RUNNING:
        print("busy")
    case Status.DONE:
        print("finished")
    case _:
        print("unknown")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Comparing `Enum` to raw ints fails unless you use `IntEnum`.
* Functional API `Enum("Color", "RED GREEN")` is less readable for large enums.
* Pickling / JSON: serialize `.value` or `.name` explicitly.
* Do not mutate `.value` on members.
* `auto()` values depend on declaration order — stable only if you don't reorder carelessly.

## 🔗 Related [#-related]

* [Classes](/docs/python/classes)
* [Dataclasses](/docs/python/dataclasses)
* [Conditionals](/docs/python/conditionals)
* [Typing hints](/docs/python/typing-hints)
* [JSON](/docs/python/json)
* [Exceptions](/docs/python/exceptions)


# Exceptions (/docs/python/exceptions)



# Exceptions [#exceptions]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Exceptions signal error conditions. Use `try` / `except` / `else` / `finally`, raise with `raise`, and chain with `raise ... from`. Prefer built-in types or small custom hierarchies over bare `except:`.

## 🔧 Core concepts [#-core-concepts]

| Construct         | Role                     |
| ----------------- | ------------------------ |
| `try`             | Guarded block            |
| `except Exc as e` | Handle specific type(s)  |
| `except* `        | Exception groups (3.11+) |
| `else`            | Runs if no exception     |
| `finally`         | Always runs (cleanup)    |
| `raise`           | Raise / re-raise         |
| `raise X from e`  | Explicit chaining        |
| `ExceptionGroup`  | Multiple errors (3.11+)  |

Catch narrow types first. `BaseException` includes `KeyboardInterrupt` / `SystemExit` — usually do not catch those.

## 💡 Examples [#-examples]

**Try / except / else / finally:**

```python
def load(path: str) -> str:
    try:
        with open(path, encoding="utf-8") as f:
            data = f.read()
    except FileNotFoundError:
        return ""
    except OSError as e:
        raise RuntimeError(f"read failed: {path}") from e
    else:
        return data.strip()
    finally:
        pass  # close handled by `with`
```

**Custom exception:**

```python
class AppError(Exception):
    """Base app error."""

class NotFoundError(AppError):
    def __init__(self, entity: str, key: object) -> None:
        super().__init__(f"{entity} not found: {key!r}")
        self.entity = entity
        self.key = key

raise NotFoundError("user", 42)
```

**Exception groups (3.11+):**

```python
def run_all() -> None:
    errors: list[Exception] = []
    for i in (0, 1):
        try:
            if i == 0:
                raise ValueError("bad")
            raise TypeError("wrong")
        except Exception as e:
            errors.append(e)
    if errors:
        raise ExceptionGroup("batch failed", errors)

try:
    run_all()
except* ValueError as eg:
    print("values", eg.exceptions)
except* TypeError as eg:
    print("types", eg.exceptions)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Bare `except:` or `except Exception` can hide bugs — be specific.
* Catching and ignoring without logging loses diagnostics.
* `finally` with `return` can swallow exceptions — avoid returning there.
* Use `raise ... from e` (or `from None`) intentionally for traceback clarity.
* Validating with exceptions in hot loops can be slower than checks.

## 🔗 Related [#-related]

* [Context managers](/docs/python/context-managers)
* [Classes](/docs/python/classes)
* [Logging](/docs/python/logging)
* [Files I/O](/docs/python/files-io)
* [Testing with pytest](/docs/python/testing-pytest)
* [Conditionals](/docs/python/conditionals)


# F-strings (/docs/python/f-string)



# F-strings [#f-strings]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Formatted string literals (`f"..."` / `f'...'`) embed expressions inside `\{\}`. They are the preferred way to build strings in modern Python (3.6+). Use them for logging messages, paths, and readable interpolation—avoid for SQL/HTML without escaping.

## 🔧 Core concepts [#-core-concepts]

| Feature       | Syntax                                   |
| ------------- | ---------------------------------------- |
| Basic         | `f"Hello, \{name\}"`                     |
| Expression    | `f"\{x + 1\}"`, `f"\{obj.attr\}"`        |
| Format spec   | `f"\{value:.2f\}"`, `f"\{n:04d\}"`       |
| Debug (3.8+)  | `f"\{x=\}"` → `x=42`                     |
| Conversion    | `!s` str, `!r` repr, `!a` ascii          |
| Nested quotes | Prefer different quote styles or escapes |
| Multiline     | `f"""..."""`                             |

Format mini-language: alignment (`&lt;^>`), width, precision, types (`d`, `f`, `x`, `%`).

## 💡 Examples [#-examples]

**Formatting numbers and dates:**

```python
from datetime import datetime

price = 19.5
n = 42
now = datetime(2026, 7, 10, 13, 30)

print(f"${price:.2f}")       # $19.50
print(f"{n:04d}")            # 0042
print(f"{now:%Y-%m-%d %H:%M}")
```

**Debug and repr:**

```python
user = "Ada"
print(f"{user=}")            # user='Ada'
print(f"{user!r}")           # 'Ada'
```

**Alignment and tables:**

```python
rows = [("id", "name"), (1, "Ada"), (2, "Bob")]
for a, b in rows:
    print(f"{a!s:>4} | {b:<10}")
```

**Walrus in f-string (careful):**

```python
data = [1, 2, 3]
print(f"{(n := len(data))} items")  # 3 items
```

## ⚠️ Pitfalls [#️-pitfalls]

* Backslashes inside `\{\}` expressions are limited; compute outside the braces if needed.
* Nested f-strings and complex expressions hurt readability—extract variables.
* Never build SQL/shell commands with raw f-strings; use parameterized APIs.
* Mixing `str.format` / `%` / f-strings inconsistently makes style noisy.
* Lazy logging: prefer `logger.info("x=%s", x)` over `f"..."` if the message may be skipped (minor; clarity often wins).

## 🔗 Related [#-related]

* [Strings](/docs/python/strings)
* [Types](/docs/python/types)
* [Docstrings](/docs/python/docstrings)
* [Dictionaries](/docs/python/dictionaries)
* [Loops](/docs/python/loops)


# Files I/O (/docs/python/files-io)



# Files I/O [#files-io]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

File I/O uses `open()` / `Path.open()` with modes for text or binary. Always use a context manager. Prefer `pathlib` helpers for simple whole-file reads/writes; use streaming for large files.

## 🔧 Core concepts [#-core-concepts]

| Mode                  | Meaning                               |
| --------------------- | ------------------------------------- |
| `"r"` / `"w"` / `"a"` | Read / write truncate / append (text) |
| `"rb"` / `"wb"`       | Binary                                |
| `"x"`                 | Exclusive create                      |
| `"r+"`                | Read + write                          |
| `encoding=`           | Text mode charset (use `utf-8`)       |
| `newline=`            | Universal newlines control            |
| `buffered`            | Default buffering; `flush` / `fsync`  |

Text mode yields `str`; binary yields `bytes`. Line iteration is memory-friendly.

## 💡 Examples [#-examples]

**Text read/write:**

```python
from pathlib import Path

path = Path("log.txt")
with path.open("w", encoding="utf-8") as f:
    f.write("hello\n")
    f.writelines(["line2\n", "line3\n"])

with path.open("r", encoding="utf-8") as f:
    for line in f:
        print(line.rstrip())
```

**Binary and buffered copy:**

```python
from pathlib import Path

src, dst = Path("in.bin"), Path("out.bin")
with src.open("rb") as r, dst.open("wb") as w:
    while chunk := r.read(1024 * 64):
        w.write(chunk)
```

**CSV-ish streaming:**

```python
from pathlib import Path

def count_rows(path: Path) -> int:
    with path.open(encoding="utf-8") as f:
        return sum(1 for _ in f)

print(count_rows(Path("data.csv")))
```

**Temporary files:**

```python
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as td:
    p = Path(td) / "x.txt"
    p.write_text("scratch", encoding="utf-8")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `with` leaks file handles.
* Writing text without `encoding` uses locale-dependent defaults.
* `"w"` truncates immediately on open — easy data loss.
* Mixing str/bytes in the wrong mode raises `TypeError`.
* On Windows, text mode translates newlines — use binary for exact bytes.

## 🔗 Related [#-related]

* [Pathlib](/docs/python/pathlib)
* [Context managers](/docs/python/context-managers)
* [Bytes / bytearray](/docs/python/bytes-bytearray)
* [JSON](/docs/python/json)
* [Examples: manage files](/docs/python/examples/manage-files)
* [Walrus](/docs/python/walrus)


# Functions (/docs/python/functions)



# Functions [#functions]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Functions are first-class callables defined with `def`. They encapsulate behavior, take parameters, and optionally return a value (`None` if omitted). Prefer small, typed functions with clear names over deep nesting.

## 🔧 Core concepts [#-core-concepts]

| Topic                | Notes                                                      |
| -------------------- | ---------------------------------------------------------- |
| Definition           | `def name(params) -> ReturnType:`                          |
| Positional / keyword | `f(1, b=2)`                                                |
| Defaults             | Evaluated once at definition time                          |
| `*args` / `**kwargs` | Variable positional / keyword                              |
| Keyword-only         | After `*` : `def f(a, *, b)`                               |
| Positional-only      | Before `/` (3.8+): `def f(a, /, b)`                        |
| Annotations          | Hints for tools; not enforced at runtime                   |
| Docstrings           | First statement; see [docstrings](/docs/python/docstrings) |

Callables include functions, methods, lambdas, and objects with `__call__`.

## 💡 Examples [#-examples]

**Typed function with keyword-only args:**

```python
def greet(name: str, /, *, shout: bool = False) -> str:
    msg = f"Hello, {name}"
    return msg.upper() if shout else msg

print(greet("Ada"))
print(greet("Ada", shout=True))
```

**Defaults and mutable trap fix:**

```python
def append_item(item: str, bucket: list[str] | None = None) -> list[str]:
    if bucket is None:
        bucket = []
    bucket.append(item)
    return bucket
```

**Early return and multiple values:**

```python
def parse_int(text: str) -> int | None:
    if not text.strip():
        return None
    try:
        return int(text)
    except ValueError:
        return None

code, label = (200, "ok")  # tuple return pattern
```

**Higher-order:**

```python
from collections.abc import Callable

def twice(fn: Callable[[int], int], x: int) -> int:
    return fn(fn(x))

print(twice(lambda n: n + 1, 3))  # 5
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutable default arguments (`def f(xs=[])`) share one list across calls.
* Forgetting `return` yields `None` — easy bug in conditionals.
* Annotations are not runtime checks unless you add a validator.
* Closures capture variables by name — see [closures](/docs/python/closures).
* Excessive `*args/**kwargs` hides the real API; prefer explicit params.

## 🔗 Related [#-related]

* [\*args and \*\*kwargs](/docs/python/kwags)
* [Lambda](/docs/python/lambda)
* [Decorators](/docs/python/decorators)
* [Closures](/docs/python/closures)
* [Typing hints](/docs/python/typing-hints)
* [Scope / namespaces](/docs/python/scope-namespaces)


# Functools (/docs/python/functools)



# Functools [#functools]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`functools` provides higher-order helpers: freeze arguments with `partial`, memoize with `lru_cache`, fold with `reduce`, and preserve metadata with `wraps` when writing decorators.

## 🔧 Core concepts [#-core-concepts]

| API                            | Role                                    |
| ------------------------------ | --------------------------------------- |
| `partial(fn, *a, **kw)`        | Pre-fill args → new callable            |
| `lru_cache(maxsize=128)`       | Memoize pure functions                  |
| `cache`                        | Unbounded memoize (3.9+)                |
| `reduce(fn, iterable[, init])` | Fold sequence to one value              |
| `wraps(fn)`                    | Copy `__name__`/`__doc__` onto wrappers |
| `singledispatch`               | Function overloading by type            |
| `total_ordering`               | Fill rich comparisons from a few        |

## 💡 Examples [#-examples]

**partial:**

```python
from functools import partial

def power(base, exp):
    return base**exp

square = partial(power, exp=2)
cube = partial(power, exp=3)
print(square(5), cube(3))  # 25 27
```

**lru\_cache:**

```python
from functools import lru_cache

@lru_cache(maxsize=256)
def fib(n: int) -> int:
    if n < 2:
        return n
    return fib(n - 1) + fib(n - 2)

print(fib(30), fib.cache_info())
fib.cache_clear()
```

**reduce:**

```python
from functools import reduce
import operator

nums = [1, 2, 3, 4]
print(reduce(operator.mul, nums, 1))  # 24
print(reduce(lambda a, b: a + b, nums))  # 10
```

**wraps for decorators:**

```python
from functools import wraps

def trace(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        print("call", fn.__name__)
        return fn(*args, **kwargs)
    return wrapper

@trace
def greet(name):
    """Say hi."""
    return f"hi {name}"

print(greet.__name__, greet.__doc__)  # greet, Say hi.
```

## ⚠️ Pitfalls [#️-pitfalls]

* Cache only pure functions: same args → same result; no hidden I/O/mutation.
* Args to `@lru_cache` must be hashable (no lists/dicts).
* Unbounded `@cache` can grow forever — prefer `lru_cache(maxsize=...)`.
* Without `@wraps`, stack traces and docs point at `wrapper`.
* Prefer comprehensions / explicit loops over `reduce` when clarity matters.

## 🔗 Related [#-related]

* [Decorators](/docs/python/decorators)
* [Lambda](/docs/python/lambda)
* [Functions](/docs/python/functions)
* [Closures](/docs/python/closures)
* [Itertools](/docs/python/itertools)


# Generators (/docs/python/generators)



# Generators [#generators]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Generators produce values lazily with `yield`. They pause and resume, saving memory for large or infinite streams. Generator functions return generator iterators; generator expressions use `(...)`.

## 🔧 Core concepts [#-core-concepts]

| Concept            | Detail                           |
| ------------------ | -------------------------------- |
| `yield`            | Produce a value; suspend frame   |
| `yield from`       | Delegate to a sub-iterator       |
| `return`           | Sets `StopIteration.value`       |
| `.send` / `.throw` | Advanced coroutine-style control |
| Gen exp            | `(x for x in it)`                |
| Exhaustion         | One-shot; recreate to reuse      |

Generators implement the iterator protocol (`__iter__`, `__next__`).

## 💡 Examples [#-examples]

**Basic generator:**

```python
from collections.abc import Iterator

def countdown(n: int) -> Iterator[int]:
    while n > 0:
        yield n
        n -= 1

print(list(countdown(3)))  # [3, 2, 1]
```

**yield from and piping:**

```python
def chain_iters(*iters: Iterator[int]) -> Iterator[int]:
    for it in iters:
        yield from it

print(list(chain_iters(iter([1, 2]), iter([3]))))
```

**Infinite stream (take n):**

```python
from collections.abc import Iterator
from itertools import islice

def naturals() -> Iterator[int]:
    n = 0
    while True:
        yield n
        n += 1

print(list(islice(naturals(), 5)))  # [0, 1, 2, 3, 4]
```

**Generator expression:**

```python
paths = ("a.txt", "b.txt", "c.txt")
sizes = (len(p) for p in paths)
print(sum(sizes))
# sizes is exhausted — sum(sizes) again is 0
```

## ⚠️ Pitfalls [#️-pitfalls]

* Generators are single-use; convert to `list` if you need multiple passes.
* Mixing heavy side effects with `yield` makes control flow hard to follow.
* Forgetting to iterate means the body never runs (lazy).
* `return` inside a generator does not return to the caller as a normal value.
* Prefer async generators (`async def` + `yield`) for async streams — see [async](/docs/python/async).

## 🔗 Related [#-related]

* [Iterators](/docs/python/iterators)
* [Comprehensions](/docs/python/comprehensions)
* [Itertools](/docs/python/itertools)
* [Loops](/docs/python/loops)
* [Async / await](/docs/python/async)
* [Context managers](/docs/python/context-managers)


# Getting Started with Python (/docs/python/getting-started)



# Getting Started with Python [#getting-started-with-python]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Python is a readable, general-purpose language used for scripting, web backends, data work, and automation. You write `.py` files (or use the interactive REPL) and run them with the `python` (or `python3`) interpreter.

## 🔧 Core concepts [#-core-concepts]

| Idea        | Meaning                                        |
| ----------- | ---------------------------------------------- |
| Interpreter | Runs your code line by line                    |
| REPL        | Interactive prompt (`>>>`) for trying snippets |
| Script      | A `.py` file you run from the terminal         |
| Module      | A reusable `.py` file you can `import`         |
| Package     | A folder of modules (often with `__init__.py`) |

**Install check:** open a terminal and run `python --version` (or `python3 --version`). Use a virtual environment (`venv`) so project packages stay isolated.

**Typical first workflow:**

1. Install Python 3 from [python.org](https://www.python.org/) (or your OS package manager).
2. Create a folder for practice files.
3. Write `hello.py`, then run `python hello.py`.

## 💡 Examples [#-examples]

**Check the version:**

```shellscript
python --version
# Python 3.12.x
```

**Start the REPL:**

```shellscript
python
```

```python
>>> 2 + 2
4
>>> print("hi")
hi
>>> exit()
```

**Create and run a script:**

```python
# hello.py
print("Hello from a file!")
```

```shellscript
python hello.py
```

**Create a virtual environment (recommended):**

```shellscript
python -m venv .venv
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate
pip install requests
```

## ⚠️ Pitfalls [#️-pitfalls]

* On some systems `python` is missing and you must use `python3`.
* Mixing system Python and project packages without `venv` causes version conflicts.
* Indentation is syntax in Python — tabs vs spaces can break files.
* Saving as `.txt` or wrong encoding can confuse beginners; use UTF-8 `.py` files.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/python/hello-world)
* [variables.md](/docs/python/variables)
* [comments.md](/docs/python/comments)
* [indentation.md](/docs/python/indentation)
* [venv.md](/docs/python/venv) · [pip.md](/docs/python/pip)


# Glob (/docs/python/glob-module)



# Glob [#glob]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `glob` module expands Unix-style filename patterns into matching paths. Use `glob.glob` for a list, `glob.iglob` for a lazy iterator. For OO APIs, prefer `pathlib.Path.glob` / `.rglob`.

## 🔧 Core concepts [#-core-concepts]

| API                        | Role                              |
| -------------------------- | --------------------------------- |
| `glob.glob(pattern)`       | List of matching path strings     |
| `glob.iglob(pattern)`      | Iterator (memory-friendly)        |
| `*`                        | Any chars in one segment          |
| `?`                        | Single char                       |
| `**`                       | Recursive dirs (`recursive=True`) |
| `[abc]` / `[0-9]`          | Character class                   |
| `glob.escape(s)`           | Escape literal `*?[` in names     |
| `Path.glob` / `Path.rglob` | pathlib equivalents               |

Patterns are relative to the current working directory unless absolute.

## 💡 Examples [#-examples]

**Basic glob:**

```python
import glob

py_files = glob.glob("src/*.py")
print(sorted(py_files))
```

\*\*Recursive &#x2A;*:**

```python
import glob

for path in glob.iglob("**/*.md", recursive=True):
    print(path)
```

**Character classes and escape:**

```python
import glob

# match report1.csv … report9.csv
print(glob.glob("report[1-9].csv"))

needle = "file[1].txt"
print(glob.glob(glob.escape(needle)))  # literal brackets
```

**pathlib alternative:**

```python
from pathlib import Path

root = Path("src")
for p in sorted(root.rglob("*.py")):
    if p.is_file():
        print(p.relative_to(root))
```

## ⚠️ Pitfalls [#️-pitfalls]

* `**` only recurses when `recursive=True` (stdlib `glob`).
* Results are unordered — sort if you need stable output.
* Hidden files (`.` prefix) may be skipped depending on pattern/platform.
* Huge trees: prefer `iglob` / pathlib over building giant lists.
* Patterns follow cwd — anchor with absolute paths when scripts `chdir`.

## 🔗 Related [#-related]

* [Pathlib](/docs/python/pathlib)
* [Files I/O](/docs/python/files-io)
* [Os](/docs/python/os)
* [Shutil](/docs/python/shutil)
* [Regex](/docs/python/regex)


# Glossary (/docs/python/glossary)



# Glossary [#glossary]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core Python terms covering types, syntax, OOP, packaging, and runtime concepts you meet daily.

## 🔧 Core concepts [#-core-concepts]

| Term                | Definition                                                                             |
| ------------------- | -------------------------------------------------------------------------------------- |
| Annotation          | Optional type hint attached to a variable, parameter, or return value.                 |
| Argument            | A value passed into a function when it is called.                                      |
| Bytecode            | Intermediate instructions CPython compiles source into before the interpreter runs it. |
| Class               | A blueprint that defines attributes and methods for creating objects.                  |
| Closure             | A nested function that remembers variables from its enclosing scope.                   |
| Comprehension       | Compact syntax that builds a list, set, or dict from an iterable expression.           |
| Context manager     | An object usable with `with` that sets up and tears down a resource.                   |
| Coroutine           | An `async def` function that can pause and resume with `await`.                        |
| Decorator           | A callable that wraps another function or class to modify behavior.                    |
| Descriptor          | An object defining `__get__`/`__set__`/`__delete__` that customizes attribute access.  |
| Dict                | A mutable mapping of unique hashable keys to values.                                   |
| Dunder              | A “double underscore” special method or attribute such as `__init__`.                  |
| Exception           | An error object raised to interrupt normal control flow.                               |
| Generator           | A function using `yield` that produces values lazily as an iterator.                   |
| GIL                 | Global Interpreter Lock that allows only one CPython bytecode thread at a time.        |
| Immutable           | A value that cannot change after creation, such as `str`, `tuple`, or `frozenset`.     |
| Import              | The mechanism that loads a module or package into the current namespace.               |
| Iterator            | An object with `__next__` that yields items until `StopIteration`.                     |
| Lambda              | A small anonymous function expressed as `lambda args: expression`.                     |
| List                | An ordered, mutable sequence of elements.                                              |
| Method              | A function defined on a class and bound to an instance when accessed.                  |
| Module              | A single `.py` file that can be imported as a namespace.                               |
| Mutable             | An object whose contents can change in place, such as `list` or `dict`.                |
| Namespace           | A mapping from names to objects, such as locals, globals, or a module dict.            |
| Package             | A directory of modules, typically with `__init__.py`, importable as a unit.            |
| Parameter           | A named slot in a function definition that receives an argument.                       |
| Property            | A managed attribute exposed via getter/setter methods using `@property`.               |
| Set                 | An unordered collection of unique hashable elements.                                   |
| Slice               | A range of indices written as `start:stop:step` used to extract subsequences.          |
| Statement           | A complete instruction that performs an action, such as assignment or `return`.        |
| Tuple               | An ordered, immutable sequence often used for fixed groupings.                         |
| Virtual environment | An isolated Python install directory for project-specific packages.                    |
| Walrus operator     | The `:=` operator that assigns a value inside an expression.                           |

## 💡 Examples [#-examples]

**Comprehension and slice:**

```python
nums = [1, 2, 3, 4, 5]
evens = [n for n in nums if n % 2 == 0]
print(nums[1:4])  # [2, 3, 4]
```

**Decorator and context manager:**

```python
from functools import wraps
from pathlib import Path

def once(fn):
    @wraps(fn)
    def wrapper(*args, **kwargs):
        return fn(*args, **kwargs)
    return wrapper

with Path("notes.txt").open() as f:
    text = f.read()
```

**Walrus operator:**

```python
while (line := input(">> ")) != "quit":
    print(line.upper())
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **parameter** (definition) with **argument** (call-site value).
* Mixing **list** (mutable) with **tuple** (immutable) when APIs expect one or the other.
* Treating **iterator** and **iterable** as the same — an iterable can be re-looped; many iterators cannot.
* Assuming **annotation** enforces types at runtime — they are hints unless a checker or validator runs.
* Equating **module** and **package** — a package is a collection of modules.

## 🔗 Related [#-related]

* [lists](/docs/python/lists)
* [dictionaries](/docs/python/dictionaries)
* [decorators](/docs/python/decorators)
* [generators](/docs/python/generators)
* [exceptions](/docs/python/exceptions)
* [venv](/docs/python/venv)


# Hashlib (/docs/python/hashlib)



# Hashlib [#hashlib]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`hashlib` computes cryptographic digests (SHA-256, SHA-512, BLAKE2, …). Use it for integrity checks and content addressing — not for password storage (use `hashlib.scrypt` / dedicated libs with salt).

## 🔧 Core concepts [#-core-concepts]

| API                                | Role                                     |
| ---------------------------------- | ---------------------------------------- |
| `hashlib.sha256(data)`             | SHA-256 hasher (or empty then `.update`) |
| `h.update(chunk)`                  | Feed more bytes                          |
| `h.digest()`                       | Raw bytes                                |
| `h.hexdigest()`                    | Hex string                               |
| `hashlib.file_digest(f, "sha256")` | Hash open file (3.11+)                   |
| `hashlib.algorithms_guaranteed`    | Always-available algos                   |
| `hashlib.blake2b` / `sha3_256`     | Other strong hashes                      |

Always hash **bytes**, not `str` — encode text first.

## 💡 Examples [#-examples]

**String / bytes:**

```python
import hashlib

msg = b"hello"
print(hashlib.sha256(msg).hexdigest())

h = hashlib.sha256()
h.update(b"hel")
h.update(b"lo")
print(h.hexdigest())  # same as above
```

**File hashing (streaming):**

```python
import hashlib
from pathlib import Path

def sha256_file(path: Path, chunk=1024 * 1024) -> str:
    h = hashlib.sha256()
    with path.open("rb") as f:
        while True:
            block = f.read(chunk)
            if not block:
                break
            h.update(block)
    return h.hexdigest()

print(sha256_file(Path("archive.zip")))
```

**Python 3.11+ file\_digest:**

```python
import hashlib
from pathlib import Path

with Path("archive.zip").open("rb") as f:
    digest = hashlib.file_digest(f, "sha256")
print(digest.hexdigest())
```

**Compare digests safely:**

```python
import hashlib
import hmac

expected = "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
actual = hashlib.sha256(b"hello").hexdigest()
print(hmac.compare_digest(expected, actual))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don’t use MD5/SHA-1 for security — fine for non-crypto checksums only.
* Don’t hash passwords with plain SHA-256; use salted KDFs (`scrypt`, Argon2).
* Reading whole files into memory is wasteful — stream with `.update`.
* Hex vs bytes: APIs often expect hex strings; keep types consistent.
* Use `hmac.compare_digest` to avoid timing leaks when verifying.

## 🔗 Related [#-related]

* [Files I/O](/docs/python/files-io)
* [Pathlib](/docs/python/pathlib)
* [Bytes / bytearray](/docs/python/bytes-bytearray)
* [Tempfile](/docs/python/tempfile)


# Hello World (/docs/python/hello-world)



# Hello World [#hello-world]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A “Hello World” program is the smallest useful program: it prints a message so you know the language toolchain works. In Python that is usually one `print` call.

## 🔧 Core concepts [#-core-concepts]

| Piece        | Role                                              |
| ------------ | ------------------------------------------------- |
| `print(...)` | Sends text to standard output (the terminal)      |
| String       | Text in quotes: `"Hello"` or `'Hello'`            |
| Script entry | Top-level code runs when you execute the file     |
| `__name__`   | Equals `"__main__"` when the file is run directly |

You can run code in the REPL or save it in a `.py` file. Files are better for anything you want to keep.

## 💡 Examples [#-examples]

**One-liner in the REPL:**

```python
print("Hello, World!")
```

**Minimal script (`hello.py`):**

```python
print("Hello, World!")
```

```shellscript
python hello.py
```

**With a main guard (good habit):**

```python
def main():
    print("Hello, World!")


if __name__ == "__main__":
    main()
```

**Slightly richer greeting:**

```python
name = "Ada"
print(f"Hello, {name}!")
print("Welcome to Python.")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting quotes: `print(Hello)` looks for a variable named `Hello`.
* Using smart/curly quotes from a word processor — use straight `"` or `'`.
* Expecting `print` to return a value; it returns `None`.
* On Windows, double-clicking a `.py` may flash a window and close; run from a terminal instead.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/python/getting-started)
* [variables.md](/docs/python/variables)
* [input\_output\_basics.md](/docs/python/input-output-basics)
* [print\_input.md](/docs/python/print-input)


# Import and export (/docs/python/import-export)



# Import and export [#import-and-export]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Python modules are `.py` files (or packages with `__init__.py`). `import` loads and binds names; there is no separate `export` keyword—public API is whatever you define and optionally list in `__all__`. Prefer absolute imports; use relative imports inside packages.

## 🔧 Core concepts [#-core-concepts]

| Form                         | Meaning                               |
| ---------------------------- | ------------------------------------- |
| `import math`                | Bind module name                      |
| `from math import sqrt`      | Bind selected names                   |
| `from math import sqrt as s` | Alias                                 |
| `from pkg import module`     | Submodule                             |
| `from . import sibling`      | Relative (package only)               |
| `from .sibling import x`     | Relative name                         |
| `__all__`                    | Names exported by `from pkg import *` |
| Entry point                  | `if __name__ == "__main__":`          |

Search path: current package, `PYTHONPATH`, site-packages. Circular imports usually mean you should restructure or lazy-import inside functions.

## 💡 Examples [#-examples]

**Package layout:**

```plaintext
mypkg/
  __init__.py
  utils.py
  api.py
```

```python
# mypkg/__init__.py
from .api import Client

__all__ = ["Client"]
```

```python
# mypkg/api.py
from .utils import normalize

class Client:
    def get(self, key: str) -> str:
        return normalize(key)
```

```python
# app.py
from mypkg import Client
# or: from mypkg.api import Client
```

**Selective import and alias:**

```python
import json
from pathlib import Path
from collections import defaultdict as dd

data = json.loads(Path("data.json").read_text(encoding="utf-8"))
```

**Script vs library:**

```python
# tools/cli.py
def main() -> None:
    print("run")

if __name__ == "__main__":
    main()
```

**Lazy import (avoid cycles / heavy deps):**

```python
def dump(obj: object) -> str:
    import json  # local import
    return json.dumps(obj)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `from module import *` pollutes namespaces; avoid outside REPL/`__init__` re-exports.
* Shadowing stdlib names (`json.py`, `random.py`) breaks imports.
* Relative imports fail when a file is run as a script (`python pkg/mod.py`); use `-m`.
* Mutating `sys.path` in app code is fragile—fix packaging instead.
* Side effects at import time (DB connect, network) make testing and startup painful.

## 🔗 Related [#-related]

* [Types](/docs/python/types)
* [Docstrings](/docs/python/docstrings)
* [Async / await](/docs/python/async)
* [\*args and \*\*kwargs](/docs/python/kwags)
* [Examples: manage files](/docs/python/examples/manage-files)


# Indentation (/docs/python/indentation)



# Indentation [#indentation]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Python uses indentation (leading spaces) to define code blocks instead of braces `\{\}`. Consistent indentation is required syntax. The community standard is **4 spaces** per level (PEP 8).

## 🔧 Core concepts [#-core-concepts]

| Idea   | Meaning                                                                  |
| ------ | ------------------------------------------------------------------------ |
| Block  | Indented suite under `if`, `for`, `while`, `def`, `class`, `with`, `try` |
| Indent | Move right to enter a block                                              |
| Dedent | Move left to leave a block                                               |
| Colon  | Headers end with `:` then an indented body                               |
| Suite  | One or more indented statements (or `pass`)                              |

Empty blocks need `pass`. Mixing tabs and spaces in one file causes `TabError` or confusing bugs.

## 💡 Examples [#-examples]

**if / else blocks:**

```python
score = 85

if score >= 90:
    print("A")
elif score >= 80:
    print("B")
else:
    print("keep practicing")
```

**Nested indentation:**

```python
for n in range(1, 4):
    print(f"n={n}")
    if n % 2 == 0:
        print("  even")
    else:
        print("  odd")
print("done")  # back at top level
```

**Functions and `pass`:**

```python
def todo_later():
    pass  # placeholder body


def add(a, b):
    total = a + b
    return total
```

**Wrong vs right (conceptually):**

```python
# Wrong — body not indented (IndentationError)
# if True:
# print("hi")

# Right
if True:
    print("hi")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing tabs and spaces — configure the editor to insert spaces.
* Copy-pasting from the web can bring inconsistent indent widths.
* Only indent when a block is required; random indent is a syntax error.
* `IndentationError` / `TabError` messages point near the problem line — check the line *above* too.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/python/getting-started)
* [comments.md](/docs/python/comments)
* [boolean\_logic.md](/docs/python/boolean-logic)
* [conditionals](/docs/python/conditionals) (if present in your notes set)


# Python (/docs/python)



# Python [#python]

Language core, stdlib, tooling, examples.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Inheritance (/docs/python/inheritance)



# Inheritance [#inheritance]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Inheritance reuses and specializes behavior via subclasses. Python uses C3 MRO for multiple inheritance. Prefer shallow hierarchies, explicit `super()`, and protocols/ABCs for shared interfaces.

## 🔧 Core concepts [#-core-concepts]

| Topic                       | Notes                              |
| --------------------------- | ---------------------------------- |
| Subclass                    | `class Child(Parent):`             |
| Override                    | Redefine method in child           |
| `super()`                   | Cooperative call to next MRO class |
| MRO                         | `Class.__mro__`, `Class.mro()`     |
| `isinstance` / `issubclass` | Runtime type checks                |
| Multiple inheritance        | `class C(A, B):` — order matters   |
| Mixin                       | Small reusable behavior class      |

`super()` without args works inside methods (3.x); binds using the defining class and instance.

## 💡 Examples [#-examples]

**Single inheritance + super:**

```python
class Animal:
    def __init__(self, name: str) -> None:
        self.name = name

    def speak(self) -> str:
        return "..."

class Dog(Animal):
    def __init__(self, name: str, breed: str) -> None:
        super().__init__(name)
        self.breed = breed

    def speak(self) -> str:
        return "woof"
```

**Mixin:**

```python
class JsonMixin:
    def to_json(self) -> str:
        import json
        return json.dumps(self.__dict__)

class Point(JsonMixin):
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y

print(Point(1, 2).to_json())
```

**MRO peek:**

```python
class A:
    def ping(self) -> str:
        return "A"

class B(A):
    def ping(self) -> str:
        return "B>" + super().ping()

class C(A):
    def ping(self) -> str:
        return "C>" + super().ping()

class D(B, C):
    def ping(self) -> str:
        return "D>" + super().ping()

print(D().ping())       # D>B>C>A
print(D.__mro__)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Diamond problems: always use `super()` consistently in cooperative hierarchies.
* Parent `__init__` not called → missing attributes; call `super().__init__`.
* Overusing inheritance for code reuse — prefer composition / mixins carefully.
* Changing base method signatures breaks Liskov expectations for callers.
* `isinstance` checks can fight duck typing; prefer protocols when flexible.

## 🔗 Related [#-related]

* [Classes](/docs/python/classes)
* [ABC / protocols](/docs/python/abc-protocols)
* [Magic methods](/docs/python/magic-methods)
* [Dataclasses](/docs/python/dataclasses)
* [Exceptions](/docs/python/exceptions)
* [Typing hints](/docs/python/typing-hints)


# Input and Output Basics (/docs/python/input-output-basics)



# Input and Output Basics [#input-and-output-basics]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Programs talk to the outside world through **output** (showing results) and **input** (reading data). Beginners usually start with `print` for output and `input` for reading a line of text from the keyboard.

## 🔧 Core concepts [#-core-concepts]

| Tool             | Direction | Notes                                                 |
| ---------------- | --------- | ----------------------------------------------------- |
| `print(*values)` | Out       | Converts values to strings; default ends with newline |
| `input(prompt)`  | In        | Always returns a `str` (even for numbers you type)    |
| f-strings        | Out       | `f"Hello \{name\}"` embeds expressions                |
| `sep` / `end`    | Out       | Control separators and line endings                   |
| Casting          | In        | Use `int(...)`, `float(...)` after reading text       |

Standard streams: **stdout** (normal output), **stderr** (errors), **stdin** (input).

## 💡 Examples [#-examples]

**Basic print and input:**

```python
name = input("What is your name? ")
print("Hello,", name)
print(f"Welcome, {name}!")
```

**Convert typed text to numbers:**

```python
raw = input("Enter a whole number: ")
n = int(raw)
print(n, "squared is", n * n)
```

**print options:**

```python
print("a", "b", "c", sep="-")
print("Loading", end="...")
print(" done")
```

**Safe parse with a try/except:**

```python
raw = input("Price: ").strip()
try:
    price = float(raw)
except ValueError:
    print("Please enter a number like 9.99")
else:
    print(f"You entered {price:.2f}")
```

## ⚠️ Pitfalls [#️-pitfalls]

* `input` returns strings: `"5" + "1"` is `"51"`, not `6`.
* `int("3.14")` fails — use `float` first or validate.
* EOF in redirected input can raise `EOFError`.
* For real apps, prefer `logging` over scattered `print` debugging.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/python/hello-world)
* [variables.md](/docs/python/variables)
* [print\_input.md](/docs/python/print-input)
* [none\_and\_truthy.md](/docs/python/none-and-truthy)


# Iterators (/docs/python/iterators)



# Iterators [#iterators]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

An iterable can produce an iterator via `iter(obj)`. An iterator yields values with `next(it)` until `StopIteration`. For-loops, comprehensions, and unpacking all consume iterators.

## 🔧 Core concepts [#-core-concepts]

| Protocol            | Methods                                 |
| ------------------- | --------------------------------------- |
| Iterable            | `__iter__` → iterator                   |
| Iterator            | `__iter__` (returns self) + `__next__`  |
| `iter(x)`           | Get iterator                            |
| `next(it, default)` | Next value or default                   |
| Sequence            | `__len__` + `__getitem__` also iterable |

Many built-ins are iterable: `list`, `dict`, `range`, files, generators. Custom classes can implement the protocols or use generators.

## 💡 Examples [#-examples]

**Manual iteration:**

```python
it = iter([10, 20, 30])
print(next(it))
print(next(it))
print(next(it, None))
print(next(it, None))  # None — exhausted
```

**Custom iterator:**

```python
from collections.abc import Iterator

class CountDown:
    def __init__(self, start: int) -> None:
        self.current = start

    def __iter__(self) -> Iterator[int]:
        return self

    def __next__(self) -> int:
        if self.current <= 0:
            raise StopIteration
        self.current -= 1
        return self.current + 1

print(list(CountDown(3)))  # [3, 2, 1]
```

**Iterable (fresh iterator each time):**

```python
class Repeat:
    def __init__(self, value: str, times: int) -> None:
        self.value = value
        self.times = times

    def __iter__(self):
        for _ in range(self.times):
            yield self.value

r = Repeat("x", 3)
print(list(r), list(r))  # both work
```

**tee / consume carefully:**

```python
from itertools import tee

a, b = tee(range(3), 2)
print(list(a), list(b))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Iterators are exhausted after one pass; iterables like `list` can re-iterate.
* Calling `iter` on an iterator returns itself — no rewind.
* Mutating a collection while iterating is unsafe.
* `StopIteration` inside generators becomes runtime errors in some contexts (PEP 479).
* Infinite iterators need explicit stopping (`islice`, `break`).

## 🔗 Related [#-related]

* [Generators](/docs/python/generators)
* [Loops](/docs/python/loops)
* [Itertools](/docs/python/itertools)
* [Magic methods](/docs/python/magic-methods)
* [Comprehensions](/docs/python/comprehensions)
* [Zip / enumerate / map / filter](/docs/python/zip-enumerate-map-filter)


# Itertools (/docs/python/itertools)



# Itertools [#itertools]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`itertools` offers fast, memory-efficient building blocks for iterators: infinite streams, combinatorics, and chaining. Compose small tools instead of materializing huge lists.

## 🔧 Core concepts [#-core-concepts]

| Function                                | Role                   |
| --------------------------------------- | ---------------------- |
| `count` `cycle` `repeat`                | Infinite / repeated    |
| `chain` `chain.from_iterable`           | Concatenate            |
| `islice`                                | Slice an iterator      |
| `tee`                                   | Split into n iterators |
| `groupby`                               | Group consecutive keys |
| `accumulate`                            | Running totals         |
| `product` `permutations` `combinations` | Combinatorics          |
| `zip_longest`                           | Zip with fill          |
| `batched`                               | Chunks (3.12+)         |

All return iterators — consume with `for`, `list`, `next`, or `islice`.

## 💡 Examples [#-examples]

**islice and count:**

```python
from itertools import count, islice

print(list(islice(count(10, 2), 5)))  # [10, 12, 14, 16, 18]
```

**chain and groupby:**

```python
from itertools import chain, groupby

print(list(chain([1, 2], (3, 4))))

rows = [("a", 1), ("a", 2), ("b", 3)]
for key, group in groupby(rows, key=lambda r: r[0]):
    print(key, list(group))
```

**Combinatorics:**

```python
from itertools import combinations, product

print(list(combinations("ABC", 2)))
print(list(product([0, 1], repeat=2)))
```

**batched (3.12+) / chunk recipe:**

```python
from itertools import batched, islice
from collections.abc import Iterator

print(list(batched(range(10), 3)))

def chunked(it: Iterator[int], n: int) -> Iterator[list[int]]:
    while True:
        block = list(islice(it, n))
        if not block:
            return
        yield block
```

## ⚠️ Pitfalls [#️-pitfalls]

* `groupby` requires **sorted** (or already consecutive) keys.
* `tee` can buffer a lot if iterators diverge — prefer re-iterating sources.
* Infinite iterators need a stop condition.
* Combinatorial functions explode in size — bound inputs.
* Exhausting one `tee` branch while another lags costs memory.

## 🔗 Related [#-related]

* [Iterators](/docs/python/iterators)
* [Generators](/docs/python/generators)
* [Loops](/docs/python/loops)
* [Comprehensions](/docs/python/comprehensions)
* [Collections module](/docs/python/collections-module)
* [Zip / enumerate / map / filter](/docs/python/zip-enumerate-map-filter)


# JSON (/docs/python/json)



# JSON [#json]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `json` module serializes Python objects to JSON text/bytes and back. Use for APIs, configs, and storage. Prefer `json.loads`/`dumps` for strings and `load`/`dump` for files.

## 🔧 Core concepts [#-core-concepts]

| Function          | Role                                            |
| ----------------- | ----------------------------------------------- |
| `loads` / `dumps` | str ↔ object                                    |
| `load` / `dump`   | file ↔ object                                   |
| Types             | `dict` `list` `str` `int` `float` `bool` `None` |
| `indent`          | Pretty-print                                    |
| `ensure_ascii`    | Escape non-ASCII when True                      |
| `default=`        | Hook for non-JSON types                         |
| `object_hook=`    | Custom dict → object                            |

JSON objects become `dict` with `str` keys. Duplicate keys: last wins on parse.

## 💡 Examples [#-examples]

**Round-trip:**

```python
import json

data = {"name": "Ada", "ok": True, "n": None, "tags": ["py"]}
text = json.dumps(data, indent=2, ensure_ascii=False)
print(text)
obj = json.loads(text)
```

**Files with pathlib:**

```python
import json
from pathlib import Path

path = Path("config.json")
path.write_text(json.dumps({"port": 8000}, indent=2), encoding="utf-8")
cfg = json.loads(path.read_text(encoding="utf-8"))
```

**Custom types:**

```python
import json
from datetime import datetime, timezone

def default(o: object) -> object:
    if isinstance(o, datetime):
        return o.isoformat()
    raise TypeError(f"not JSON serializable: {type(o)}")

payload = {"ts": datetime.now(timezone.utc)}
print(json.dumps(payload, default=default))
```

**Typed parse helper:**

```python
import json
from typing import Any

def load_object(text: str) -> dict[str, Any]:
    data = json.loads(text)
    if not isinstance(data, dict):
        raise TypeError("expected JSON object")
    return data
```

## ⚠️ Pitfalls [#️-pitfalls]

* `tuple` becomes JSON array → comes back as `list`.
* Keys must be strings; non-str keys are coerced in `dumps` (surprising).
* `NaN`/`Infinity` are allowed by default but invalid in strict JSON — use `allow_nan=False`.
* Huge `loads` into memory — stream with `ijson` or line-delimited JSON for big data.
* Never `json.loads` untrusted data into `pickle`-like execution — JSON is data-only (safe) but still validate schema.

## 🔗 Related [#-related]

* [Dictionaries](/docs/python/dictionaries)
* [Files I/O](/docs/python/files-io)
* [Dataclasses](/docs/python/dataclasses)
* [Datetime](/docs/python/datetime)
* [Typing hints](/docs/python/typing-hints)
* [Examples: http requests](/docs/python/examples/http-requests)


# *args and **kwargs (/docs/python/kwags)



# \*args and \*\*kwargs [#args-and-kwargs]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`*args` collects extra positional arguments into a tuple; `**kwargs` collects extra keyword arguments into a dict. Use them for wrappers, decorators, forward-compatible APIs, and when calling through to another function. Prefer explicit parameters when the API is stable and small.

## 🔧 Core concepts [#-core-concepts]

| Syntax       | Role                                      |
| ------------ | ----------------------------------------- |
| `*args`      | Extra positional → `tuple`                |
| `**kwargs`   | Extra keywords → `dict`                   |
| `*` in def   | Keyword-only parameters after `*`         |
| `/` in def   | Positional-only before `/` (3.8+)         |
| Call unpack  | `f(*list)`, `f(**dict)`                   |
| Order in def | params, `*args`, keyword-only, `**kwargs` |

Names `args`/`kwargs` are convention only; `*rest` / `**options` are fine.

## 💡 Examples [#-examples]

**Collect and forward:**

```python
def logged(fn):
    def wrapper(*args, **kwargs):
        print(f"call {fn.__name__}")
        return fn(*args, **kwargs)
    return wrapper

@logged
def add(a: int, b: int) -> int:
    return a + b

add(1, 2)
```

**Mix with explicit params:**

```python
def connect(host: str, port: int = 5432, /, *, timeout: float = 5.0, **opts):
    print(host, port, timeout, opts)

connect("localhost", 5432, timeout=2.0, ssl=True)
```

**Unpacking into calls:**

```python
def greet(name: str, excited: bool = False) -> str:
    return f"Hi {name}{'!' if excited else '.'}"

args = ("Ada",)
kwargs = {"excited": True}
print(greet(*args, **kwargs))
```

**Merge kwargs safely:**

```python
def create_user(name: str, **kwargs):
    defaults = {"active": True, "role": "user"}
    data = {**defaults, **kwargs, "name": name}
    return data
```

## ⚠️ Pitfalls [#️-pitfalls]

* Overusing `**kwargs` hides required fields and breaks autocomplete/type checkers—annotate with `TypedDict` or explicit params when possible.
* Duplicate keywords: `f(1, a=1, **\{"a": 2\})` raises `TypeError`.
* Mutating the received `kwargs` dict can surprise callers if you store it; copy when retaining.
* `*args` typing is limited; prefer `*args: int` (homogeneous) or redesign.
* Forgetting to forward `*args, **kwargs` in wrappers drops arguments silently until call time.

## 🔗 Related [#-related]

* [Types](/docs/python/types)
* [Dictionaries](/docs/python/dictionaries)
* [Docstrings](/docs/python/docstrings)
* [Import / export](/docs/python/import-export)
* [Loops](/docs/python/loops)


# Lambda (/docs/python/lambda)



# Lambda [#lambda]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A `lambda` creates a small anonymous function from a single expression. Use for short callbacks (`sort` keys, `map`/`filter`) when a full `def` would be noise. Prefer named `def` for anything non-trivial or multi-statement.

## 🔧 Core concepts [#-core-concepts]

| Form                | Meaning                                   |
| ------------------- | ----------------------------------------- |
| `lambda args: expr` | Returns `expr`; no statements             |
| Parameters          | Same rules as `def` (defaults, `*`, `**`) |
| Scope               | Closure over enclosing names (LEGB)       |
| Type                | Ordinary function object                  |

Lambdas cannot contain `return`, assignments (except walrus in 3.8+ inside expr), or multiple statements. Annotations on lambdas are awkward — prefer `def`.

## 💡 Examples [#-examples]

**Sort and group keys:**

```python
rows = [("ada", 3), ("bob", 1), ("cy", 2)]
rows.sort(key=lambda pair: pair[1])
# [("bob", 1), ("cy", 2), ("ada", 3)]
```

**With map / filter (often better as comprehension):**

```python
nums = [1, 2, 3, 4]
doubled = list(map(lambda n: n * 2, nums))
evens = list(filter(lambda n: n % 2 == 0, nums))
# Prefer: [n * 2 for n in nums], [n for n in nums if n % 2 == 0]
```

**Callable default / partial-like:**

```python
ops = {
    "add": lambda a, b: a + b,
    "mul": lambda a, b: a * b,
}
print(ops["add"](2, 3))
```

**Capture loop variable correctly:**

```python
# Wrong: all lambdas see final i
bad = [lambda: i for i in range(3)]
# Right: default-arg bind
good = [lambda i=i: i for i in range(3)]
print([f() for f in good])  # [0, 1, 2]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Do not stuff complex logic into lambdas — readability collapses.
* Late binding in closures: loop variables need default-arg capture.
* `lambda` has no good docstring / name in stack traces (`<lambda>`).
* Prefer comprehensions over `map`/`filter` + lambda in most Python code.
* Cannot assign annotations cleanly; use `def` for public APIs.

## 🔗 Related [#-related]

* [Functions](/docs/python/functions)
* [Closures](/docs/python/closures)
* [Decorators](/docs/python/decorators)
* [Zip / enumerate / map / filter](/docs/python/zip-enumerate-map-filter)
* [Comprehensions](/docs/python/comprehensions)
* [Walrus](/docs/python/walrus)


# Lists (/docs/python/lists)



# Lists [#lists]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A `list` is an ordered, mutable sequence. Use for collections that grow, shrink, or change in place. Prefer list methods and comprehensions over manual index loops. Heterogeneous types are allowed; typed code usually keeps one element type.

## 🔧 Core concepts [#-core-concepts]

**Create / access**

| Operation     | Example                                   |
| ------------- | ----------------------------------------- |
| Create        | `[1, 2]`, `list(iterable)`, `[]`          |
| Index / slice | `xs[0]`, `xs[-1]`, `xs[1:3]`, `xs[i:j:k]` |
| Assign slice  | `xs[1:3] = [9, 8]`; can change length     |
| Unpack        | `a, *mid, z = xs`                         |

**Instance methods**

| Method                             | Mutates? | Notes                                        |
| ---------------------------------- | -------- | -------------------------------------------- |
| `append(x)`                        | yes      | Add one at end — O(1) amort.                 |
| `extend(it)`                       | yes      | Add all from iterable; `xs += it`            |
| `insert(i, x)`                     | yes      | Insert before index `i` — O(n)               |
| `pop([i])`                         | yes      | Remove/return at `i` (default last)          |
| `remove(x)`                        | yes      | Remove first `== x`; `ValueError` if missing |
| `clear()`                          | yes      | Remove all                                   |
| `index(x[, start[, stop]])`        | no       | First index; `ValueError` if missing         |
| `count(x)`                         | no       | Occurrences of `x`                           |
| `sort(*, key=None, reverse=False)` | yes      | In-place; returns `None`                     |
| `reverse()`                        | yes      | In-place reverse                             |
| `copy()`                           | no       | Shallow copy (`xs[:]` / `list(xs)`)          |

**Builtins that operate on lists / sequences**

| Builtin                                          | Notes                               |
| ------------------------------------------------ | ----------------------------------- |
| `len(xs)`                                        | Length                              |
| `x in xs` / `x not in xs`                        | Membership — O(n)                   |
| `min` / `max` / `sum`                            | Over elements; `sum` needs numbers  |
| `sorted(xs, *, key=…, reverse=…)`                | New sorted list                     |
| `reversed(xs)`                                   | Reverse iterator                    |
| `enumerate(xs, start=0)`                         | `(i, x)` pairs                      |
| `zip(*seqs)`                                     | Parallel tuples (stops at shortest) |
| `all` / `any`                                    | Truth of all / any elements         |
| `map(fn, xs)` / `filter(fn, xs)`                 | Lazy; wrap with `list(...)`         |
| `slice` assignment / `del xs[i]` / `del xs[a:b]` | Delete or replace ranges            |

Lists are dynamic arrays; append/pop at the end is amortized O(1). Insert/delete at the front is O(n).

## 💡 Examples [#-examples]

**Build and mutate:**

```python
nums: list[int] = [3, 1, 4]
nums.append(1)
nums.extend([5, 9])
nums.insert(0, 0)
last = nums.pop()          # 9
nums.remove(1)             # removes first 1
print(nums)                # [0, 3, 4, 1, 5]
```

**Sort with key:**

```python
people = [{"name": "bob", "age": 30}, {"name": "ada", "age": 25}]
people.sort(key=lambda p: p["age"])
names = sorted(people, key=lambda p: p["name"])
```

**Comprehension and unpacking:**

```python
squares = [n * n for n in range(6) if n % 2 == 0]
a, *mid, z = [10, 20, 30, 40]
# a=10, mid=[20, 30], z=40
```

**Stack / queue patterns:**

```python
stack: list[str] = []
stack.append("a")
stack.pop()                # LIFO

from collections import deque
q: deque[str] = deque()
q.append("a")
q.popleft()                # FIFO — prefer deque over list.pop(0)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `xs + ys` creates a new list; `xs.extend(ys)` mutates in place.
* `xs *= n` and `[[] ] * n` share references for mutable elements.
* `list.sort` returns `None` — use `sorted` when you need a new list.
* Shallow copy does not deep-copy nested lists — see [copy / deepcopy](/docs/python/copy-deepcopy).
* Prefer `deque` for frequent left pops; lists are poor queues.

## 🔗 Related [#-related]

* [Tuples](/docs/python/tuples)
* [Sets](/docs/python/sets)
* [Slicing](/docs/python/slicing)
* [Comprehensions](/docs/python/comprehensions)
* [Unpacking](/docs/python/unpacking)
* [Examples: merge lists](/docs/python/examples/merge-lists)


# Logging (/docs/python/logging)



# Logging [#logging]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `logging` module is the standard way to record program events. Prefer it over `print` for libraries and services. Configure once at the app entrypoint; modules use `logging.getLogger(__name__)`.

## 🔧 Core concepts [#-core-concepts]

| Piece       | Role                                        |
| ----------- | ------------------------------------------- |
| Logger      | Named channel (`getLogger`)                 |
| Level       | `DEBUG` `INFO` `WARNING` `ERROR` `CRITICAL` |
| Handler     | Destination (stderr, file, syslog)          |
| Formatter   | Message layout                              |
| Filter      | Extra include/exclude rules                 |
| Propagation | Child → parent loggers                      |

Root logger defaults to `WARNING`. Libraries should not call `basicConfig`; apps should.

## 💡 Examples [#-examples]

**Module logger:**

```python
import logging

log = logging.getLogger(__name__)

def work(n: int) -> int:
    log.debug("start n=%s", n)
    if n < 0:
        log.error("invalid n=%s", n)
        raise ValueError(n)
    log.info("ok")
    return n * 2
```

**basicConfig for scripts:**

```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
)
logging.getLogger(__name__).info("boot")
```

**File + stderr handlers:**

```python
import logging
from pathlib import Path

def setup(log_path: Path) -> None:
    root = logging.getLogger()
    root.setLevel(logging.DEBUG)
    fmt = logging.Formatter("%(levelname)s %(message)s")

    sh = logging.StreamHandler()
    sh.setLevel(logging.INFO)
    sh.setFormatter(fmt)

    fh = logging.FileHandler(log_path, encoding="utf-8")
    fh.setLevel(logging.DEBUG)
    fh.setFormatter(fmt)

    root.handlers.clear()
    root.addHandler(sh)
    root.addHandler(fh)
```

**exception helper:**

```python
import logging

log = logging.getLogger("app")
try:
    1 / 0
except ZeroDivisionError:
    log.exception("divide failed")  # includes traceback
```

## ⚠️ Pitfalls [#️-pitfalls]

* Eager f-strings in log calls allocate even if level is filtered — use `%s` lazy args.
* Multiple `basicConfig` calls are no-ops if handlers already exist.
* Catching exceptions without `log.exception` loses stack traces.
* Don't log secrets (tokens, passwords).
* Avoid configuring logging inside importable libraries.

## 🔗 Related [#-related]

* [Exceptions](/docs/python/exceptions)
* [Argparse](/docs/python/argparse)
* [Examples: cli tool](/docs/python/examples/cli-tool)
* [Concurrency](/docs/python/concurrency)
* [Pathlib](/docs/python/pathlib)
* [Testing with pytest](/docs/python/testing-pytest)


# Loops (/docs/python/loops)



# Loops [#loops]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Python iterates with `for` over any iterable and `while` for condition-driven loops. Prefer `for` + comprehensions over index arithmetic. Control flow: `break`, `continue`, `else` on loops (runs if no `break`), and `enumerate` / `zip` for paired iteration.

## 🔧 Core concepts [#-core-concepts]

| Construct                   | Use                                            |
| --------------------------- | ---------------------------------------------- |
| `for x in iterable`         | Iterate values                                 |
| `for i, x in enumerate(xs)` | Index + value                                  |
| `for a, b in zip(xs, ys)`   | Parallel iterables                             |
| `while cond`                | Condition loop                                 |
| `break` / `continue`        | Exit / next iteration                          |
| `for`/`while` `else`        | Runs if loop did not `break`                   |
| Comprehensions              | `[...]`, `\{...\}`, `(... for ...)` generators |

`range(stop)`, `range(start, stop[, step])` for integer sequences.

## 💡 Examples [#-examples]

**Enumerate, zip, unpacking:**

```python
names = ["Ada", "Bob"]
scores = [10, 7]

for i, name in enumerate(names, start=1):
    print(i, name)

for name, score in zip(names, scores, strict=True):  # 3.10+
    print(f"{name}: {score}")
```

**Loop else (search):**

```python
needle = 4
for n in [1, 2, 3]:
    if n == needle:
        print("found")
        break
else:
    print("not found")
```

**Comprehensions and generators:**

```python
squares = [n * n for n in range(5) if n % 2 == 0]
gen = (n * n for n in range(1_000_000))  # lazy
total = sum(gen)
```

**While with sentinel:**

```python
from collections.abc import Iterator

def read_chunks() -> Iterator[str]:
    yield "a"
    yield "b"

it = iter(read_chunks())
while True:
    try:
        chunk = next(it)
    except StopIteration:
        break
    print(chunk)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Do not mutate a list you are iterating; iterate a copy or build a new list.
* `for i in range(len(xs))` is usually worse than `for x in xs` / `enumerate`.
* Infinite `while True` needs a clear exit; prefer iterators when possible.
* `zip` truncates to the shortest iterable unless `strict=True`.
* Creating huge lists with comprehensions can exhaust memory—use generators.

## 🔗 Related [#-related]

* [Dictionaries](/docs/python/dictionaries)
* [Types](/docs/python/types)
* [Strings](/docs/python/strings)
* [\*args and \*\*kwargs](/docs/python/kwags)
* [Async / await](/docs/python/async)
* [Examples: merge lists](/docs/python/examples/merge-lists)


# Magic Methods (/docs/python/magic-methods)



# Magic Methods [#magic-methods]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Magic (dunder) methods customize object behavior for operators, iteration, context managers, formatting, and more. Implement only what you need; keep them consistent (`__eq__` with `__hash__`, rich comparisons together).

## 🔧 Core concepts [#-core-concepts]

| Category   | Methods                                                 |
| ---------- | ------------------------------------------------------- |
| Lifecycle  | `__init__`, `__new__`, `__del__`                        |
| Repr / str | `__repr__`, `__str__`, `__format__`                     |
| Compare    | `__eq__`, `__lt__`, `__le__`, …                         |
| Hash       | `__hash__` (immutable value types)                      |
| Container  | `__len__`, `__getitem__`, `__setitem__`, `__contains__` |
| Numeric    | `__add__`, `__radd__`, `__iadd__`, …                    |
| Call       | `__call__`                                              |
| Context    | `__enter__`, `__exit__`                                 |
| Iter       | `__iter__`, `__next__`, `__aiter__`                     |

Returning `NotImplemented` from binary ops lets Python try the reflected method.

## 💡 Examples [#-examples]

**Value object:**

```python
from __future__ import annotations

class Money:
    def __init__(self, cents: int) -> None:
        self.cents = cents

    def __repr__(self) -> str:
        return f"Money({self.cents})"

    def __str__(self) -> str:
        return f"${self.cents / 100:.2f}"

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Money):
            return NotImplemented
        return self.cents == other.cents

    def __hash__(self) -> int:
        return hash(self.cents)

    def __add__(self, other: Money) -> Money:
        if not isinstance(other, Money):
            return NotImplemented
        return Money(self.cents + other.cents)
```

**Container protocol:**

```python
class Bag:
    def __init__(self, items: list[str] | None = None) -> None:
        self._items = list(items or [])

    def __len__(self) -> int:
        return len(self._items)

    def __getitem__(self, index: int) -> str:
        return self._items[index]

    def __contains__(self, item: object) -> bool:
        return item in self._items

    def __iter__(self):
        return iter(self._items)
```

**Callable instance:**

```python
class Adder:
    def __init__(self, n: int) -> None:
        self.n = n

    def __call__(self, x: int) -> int:
        return x + self.n

add5 = Adder(5)
print(add5(10))  # 15
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutable objects should set `__hash__ = None` if they define `__eq__`.
* `__repr__` should be unambiguous; `__str__` can be user-friendly.
* Forgetting `__radd__` breaks `sum()` starting from `0` for custom types.
* `__del__` is not a destructor guarantee — avoid critical logic there.
* Inconsistent `__eq__` / ordering methods confuse sorts and sets.

## 🔗 Related [#-related]

* [Classes](/docs/python/classes)
* [Context managers](/docs/python/context-managers)
* [Iterators](/docs/python/iterators)
* [Operators](/docs/python/operators)
* [Dataclasses](/docs/python/dataclasses)
* [Properties / descriptors](/docs/python/properties-descriptors)


# None and Truthiness (/docs/python/none-and-truthy)



# None and Truthiness [#none-and-truthiness]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`None` means “no value” (Python’s null). **Truthiness** means how values behave in `if` / `while` without an explicit comparison: some values count as false, everything else as true.

## 🔧 Core concepts [#-core-concepts]

| Idea          | Detail                                                      |
| ------------- | ----------------------------------------------------------- |
| `None`        | Singleton object; type is `NoneType`                        |
| Test for None | Use `x is None` / `x is not None`                           |
| Falsy values  | `None`, `False`, `0`, `0.0`, `""`, `[]`, `\{\}`, `set()`, … |
| Truthy values | Non-empty containers, non-zero numbers, most objects        |
| `bool(x)`     | Explicit conversion to `True`/`False`                       |

Functions that “return nothing” actually return `None`.

## 💡 Examples [#-examples]

**None as a missing value:**

```python
user = None

if user is None:
    print("Please log in")
else:
    print(user)
```

**Default then assign:**

```python
def find_user(user_id):
    # pretend lookup failed
    return None


result = find_user(42)
name = result if result is not None else "anonymous"
print(name)
```

**Truthiness in conditions:**

```python
items = []
text = ""
count = 0

if not items:
    print("list is empty")
if not text:
    print("no text")
if count:
    print("never runs for 0")
```

**Truthy gotchas with numbers and containers:**

```python
print(bool(0), bool(1), bool(-1))      # False True True
print(bool(""), bool("0"))             # False True
print(bool([]), bool([0]))             # False True
print(bool(None))                      # False
```

## ⚠️ Pitfalls [#️-pitfalls]

* `if x == None` works but style guides prefer `if x is None`.
* Empty containers are falsy — that is often useful, sometimes surprising.
* The string `"False"` and the number `0` inside a list `[0]` are truthy as containers/strings.
* Returning `None` accidentally from a function that should return data is a common bug.

## 🔗 Related [#-related]

* [boolean\_logic.md](/docs/python/boolean-logic)
* [variables.md](/docs/python/variables)
* [truthiness.md](/docs/python/truthiness)
* [input\_output\_basics.md](/docs/python/input-output-basics)


# Operators (/docs/python/operators)



# Operators [#operators]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Python operators cover arithmetic, comparison, boolean logic, bitwise ops, membership, identity, and assignment variants. Precedence matters; use parentheses for clarity. Many operators map to magic methods.

## 🔧 Core concepts [#-core-concepts]

| Group        | Operators                    |
| ------------ | ---------------------------- |
| Arithmetic   | `+ - * / // % **`            |
| Comparison   | `== != &lt; &lt;= > >=`      |
| Boolean      | `and or not` (short-circuit) |
| Identity     | `is`, `is not`               |
| Membership   | `in`, `not in`               |
| Bitwise      | `& \| ^ ~ &lt;&lt; >>`       |
| Assign       | `=`, `+=`, `:=` (walrus)     |
| Merge (3.9+) | `d1 \| d2` for dicts         |
| Matrix       | `@` (e.g. NumPy)             |

`/` always float division; `//` floor division. `and`/`or` return operands, not strict bools.

## 💡 Examples [#-examples]

**Arithmetic and div:**

```python
print(7 / 2)    # 3.5
print(7 // 2)   # 3
print(7 % 2)    # 1
print(2 ** 10)  # 1024
print(-7 // 2)  # -4 (floors toward -inf)
```

**Boolean and chaining:**

```python
x = 5
print(1 < x < 10)          # True — chained comparisons
print("" or "default")     # "default"
print("hi" and "there")    # "there"
```

**Identity vs equality:**

```python
a = [1, 2]
b = [1, 2]
print(a == b)   # True — equal values
print(a is b)   # False — different objects
print(a is not None)
```

**Dict merge and augmented assign:**

```python
left = {"a": 1}
right = {"b": 2}
merged = left | right          # {"a": 1, "b": 2}
left |= {"a": 9}               # left -> {"a": 9}

n = 3
n *= 2                         # 6
```

## ⚠️ Pitfalls [#️-pitfalls]

* `is` is not for value equality (except `None`, `True`, `False`, enums).
* Mutable `+=` may mutate in place (`list`) or rebind (`tuple`).
* `and`/`or` return last evaluated operand — type may not be `bool`.
* Bitwise `&` / `|` on ints ≠ boolean `and` / `or`.
* Mixed `==` across types is usually `False` (no coercion like JS).

## 🔗 Related [#-related]

* [Magic methods](/docs/python/magic-methods)
* [Truthiness](/docs/python/truthiness)
* [Walrus](/docs/python/walrus)
* [Conditionals](/docs/python/conditionals)
* [Slicing](/docs/python/slicing)
* [Unpacking](/docs/python/unpacking)


# OS (/docs/python/os)



# OS [#os]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `os` module talks to the operating system: env vars, process info, and basic path helpers. Prefer `pathlib` for path work; keep `os` for env, cwd, and platform details.

## 🔧 Core concepts [#-core-concepts]

| API                                    | Role                                 |
| -------------------------------------- | ------------------------------------ |
| `os.environ`                           | Mapping of environment variables     |
| `os.getenv(k, default)`                | Safe read (returns `None` / default) |
| `os.environ["KEY"]`                    | Read/set; `KeyError` if missing      |
| `os.getcwd()` / `os.chdir(path)`       | Working directory                    |
| `os.name` / `os.sep`                   | Platform hints                       |
| `os.listdir(path)`                     | Directory entries (names only)       |
| `os.makedirs(path, exist_ok=True)`     | Create dirs                          |
| `os.remove` / `os.rename`              | File ops                             |
| `os.path.join` / `exists` / `splitext` | String path helpers                  |
| `pathlib.Path`                         | Preferred OO paths                   |

**`os.path` vs `pathlib`:** `os.path` returns strings; `Path` objects support `/`, `.read_text()`, `.glob()`, and clearer APIs. Use `pathlib` for new code; `os.path` still appears in older APIs.

## 💡 Examples [#-examples]

**Environment variables:**

```python
import os

home = os.getenv("HOME") or os.getenv("USERPROFILE")
os.environ["APP_ENV"] = "dev"
print(os.environ.get("APP_ENV", "prod"))
# del os.environ["APP_ENV"]  # unset
```

**Cwd and listing:**

```python
import os
from pathlib import Path

print(os.getcwd())
for name in os.listdir("."):
    print(name, Path(name).is_file())
```

**`os.path` vs `pathlib`:**

```python
import os
from pathlib import Path

s = os.path.join("data", "a.csv")
print(os.path.exists(s), os.path.splitext(s))

p = Path("data") / "a.csv"
print(p.exists(), p.suffix, p.read_text(encoding="utf-8") if p.exists() else "")
```

**Create dirs (os vs pathlib):**

```python
import os
from pathlib import Path

os.makedirs("out/logs", exist_ok=True)
Path("out/cache").mkdir(parents=True, exist_ok=True)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `os.environ["MISSING"]` raises `KeyError` — prefer `getenv` / `.get`.
* Env values are always strings; cast (`int(os.getenv("PORT", "8000"))`).
* `chdir` is process-global and surprises libraries — avoid in libraries.
* Mixing `str` and `Path` is fine at the boundary; stick to one style inside a module.
* `listdir` does not recurse; use `Path.rglob` or `os.walk` for trees.

## 🔗 Related [#-related]

* [Pathlib](/docs/python/pathlib)
* [Files I/O](/docs/python/files-io)
* [Dotenv](/docs/python/dotenv)
* [Shutil](/docs/python/shutil)
* [Sys](/docs/python/sys)
* [Venv](/docs/python/venv)


# Packaging (/docs/python/packaging)



# Packaging [#packaging]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Packaging turns your code into an installable distribution (wheel/sdist) with metadata. Modern projects use `pyproject.toml` (PEP 517/518/621) with backends like `setuptools`, `hatchling`, or `flit`.

## 🔧 Core concepts [#-core-concepts]

| Piece            | Role                            |
| ---------------- | ------------------------------- |
| `pyproject.toml` | Build + project metadata        |
| Build backend    | setuptools / hatchling / …      |
| Wheel            | Built install artifact (`.whl`) |
| sdist            | Source distribution             |
| Entry points     | Console scripts                 |
| Extras           | Optional deps (`dev`, `docs`)   |
| Version          | Static or dynamic               |

Layout: `src/mypkg/` (recommended) or flat `mypkg/`.

## 💡 Examples [#-examples]

**Minimal pyproject (setuptools):**

```toml
[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "awesome-tool"
version = "0.1.0"
description = "Demo package"
readme = "README.md"
requires-python = ">=3.10"
dependencies = ["requests>=2.31"]

[project.optional-dependencies]
dev = ["pytest>=8"]

[project.scripts]
awesome-tool = "awesome_tool.cli:main"

[tool.setuptools.packages.find]
where = ["src"]
```

**Build and install:**

```shellscript
python -m pip install build
python -m build
python -m pip install dist/awesome_tool-0.1.0-py3-none-any.whl
# or editable
python -m pip install -e ".[dev]"
```

**Console script stub:**

```python
# src/awesome_tool/cli.py
def main() -> None:
    print("hello from awesome-tool")

if __name__ == "__main__":
    main()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `packages.find` / package data → empty installs.
* Pinning too tightly in libraries frustrates consumers.
* Shipping tests/secrets inside wheels by accident — check includes.
* Multiple tools writing metadata (`setup.cfg` + poetry) — pick one source of truth.
* Entry point module path typos fail only after install.

## 🔗 Related [#-related]

* [Pip](/docs/python/pip)
* [Venv](/docs/python/venv)
* [Argparse](/docs/python/argparse)
* [Import / export](/docs/python/import-export)
* [Examples: cli tool](/docs/python/examples/cli-tool)
* [Testing with pytest](/docs/python/testing-pytest)


# Pandas (/docs/python/pandas)



# Pandas [#pandas]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Pandas is the go-to tabular data library. Install with `pip install pandas`. Core types: `Series` (1D labeled) and `DataFrame` (2D table). Typical flow: `read_csv` → filter/transform → `groupby` / `merge` → `to_csv`.

## 🔧 Core concepts [#-core-concepts]

| API                                     | Role                    |
| --------------------------------------- | ----------------------- |
| `pd.Series(data)`                       | 1D labeled array        |
| `pd.DataFrame(data)`                    | Table (columns + index) |
| `pd.read_csv(path)`                     | Load CSV                |
| `df[mask]` / `.loc` / `.iloc`           | Filter / select         |
| `df.groupby(col)`                       | Split-apply-combine     |
| `pd.merge(left, right, on=...)`         | Join tables             |
| `df.to_csv(path, index=False)`          | Export                  |
| `df.head()` / `.info()` / `.describe()` | Inspect                 |

## 💡 Examples [#-examples]

**Read and filter:**

```python
import pandas as pd

df = pd.read_csv("sales.csv")
active = df[df["status"] == "active"]
big = df.loc[df["amount"] > 100, ["name", "amount"]]
print(df.head(), active.shape)
```

**Groupby:**

```python
import pandas as pd

df = pd.read_csv("orders.csv")
summary = (
    df.groupby("region", as_index=False)["amount"]
    .sum()
    .sort_values("amount", ascending=False)
)
print(summary)
```

**Merge:**

```python
import pandas as pd

orders = pd.read_csv("orders.csv")
customers = pd.read_csv("customers.csv")
joined = pd.merge(orders, customers, on="customer_id", how="left")
print(joined.head())
```

**Write CSV:**

```python
import pandas as pd

df = pd.DataFrame({"a": [1, 2], "b": ["x", "y"]})
df.to_csv("out.csv", index=False, encoding="utf-8")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Install first: `pip install pandas` (not in the stdlib).
* Chained indexing (`df[...][...] =`) can fail silently — prefer `.loc`.
* `groupby` default may leave the key as index; use `as_index=False` when you want a flat frame.
* Merges duplicate key columns as `_x` / `_y` if names collide — set `suffixes`.
* Large CSVs: pass `usecols`, `dtype`, or chunk with `chunksize=`.

## 🔗 Related [#-related]

* [Csv](/docs/python/csv)
* [Files I/O](/docs/python/files-io)
* [Pip](/docs/python/pip)
* [Venv](/docs/python/venv)


# Pathlib (/docs/python/pathlib)



# Pathlib [#pathlib]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`pathlib.Path` is the modern object-oriented path API. Prefer it over `os.path` string munging. Paths use `/` operator, work cross-platform, and integrate with open/read/write helpers.

## 🔧 Core concepts [#-core-concepts]

| API                                | Role                |
| ---------------------------------- | ------------------- |
| `Path("a/b")`                      | Create path         |
| `p / "c"`                          | Join                |
| `.name` `.stem` `.suffix`          | Parts               |
| `.parent` `.parents`               | Ancestors           |
| `.resolve()`                       | Absolute + symlinks |
| `.exists()` `.is_file()`           | Queries             |
| `.iterdir()` `.glob()` `.rglob()`  | Listing             |
| `.read_text()` `.write_text()`     | Convenience I/O     |
| `.mkdir()` `.unlink()` `.rename()` | FS ops              |

Use `PurePath` when you only need parsing without touching the filesystem.

## 💡 Examples [#-examples]

**Build and inspect:**

```python
from pathlib import Path

base = Path(__file__).resolve().parent
data = base / "data" / "input.csv"
print(data.name, data.suffix, data.parent)
print(data.with_suffix(".json"))
```

**Read / write:**

```python
from pathlib import Path

p = Path("notes.txt")
p.write_text("hello\n", encoding="utf-8")
text = p.read_text(encoding="utf-8")
p.write_bytes(b"\x00\x01")
```

**Walk and filter:**

```python
root = Path("src")
for py in sorted(root.rglob("*.py")):
    if py.is_file() and "test" not in py.parts:
        print(py.relative_to(root))
```

**mkdir / safe delete:**

```python
out = Path("build/out")
out.mkdir(parents=True, exist_ok=True)
tmp = out / "tmp.txt"
tmp.write_text("x", encoding="utf-8")
tmp.unlink(missing_ok=True)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Relative paths depend on process cwd — anchor with `Path(__file__).parent`.
* Always pass `encoding` for text helpers.
* `Path.glob("**/*")` can be huge; narrow patterns.
* Mixing `str` paths and `Path` works often, but keep one style in APIs.
* `resolve(strict=True)` raises if the path does not exist.

## 🔗 Related [#-related]

* [Files I/O](/docs/python/files-io)
* [Examples: manage files](/docs/python/examples/manage-files)
* [Context managers](/docs/python/context-managers)
* [Strings](/docs/python/strings)
* [JSON](/docs/python/json)
* [Import / export](/docs/python/import-export)


# Pip (/docs/python/pip)



# Pip [#pip]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`pip` installs packages from PyPI (and other indexes) into the current environment. Use `python -m pip` for reliability. Pin versions for apps; keep libraries flexible within SemVer ranges.

## 🔧 Core concepts [#-core-concepts]

| Command                           | Role                      |
| --------------------------------- | ------------------------- |
| `pip install pkg`                 | Install latest            |
| `pip install pkg==1.2.3`          | Pin version               |
| `pip install -r requirements.txt` | From file                 |
| `pip install -e .`                | Editable project          |
| `pip uninstall pkg`               | Remove                    |
| `pip list` / `show`               | Inspect                   |
| `pip freeze`                      | Export pins               |
| `pip index versions pkg`          | List versions (newer pip) |

Constraints files (`constraints.txt`) pin transitive deps without listing them as direct requirements.

## 💡 Examples [#-examples]

**Everyday installs:**

```shellscript
python -m pip install -U pip setuptools wheel
python -m pip install 'requests>=2.31'
python -m pip install -r requirements.txt
```

**Editable local package:**

```shellscript
python -m pip install -e .
python -m pip install -e ".[dev]"
```

**requirements vs freeze:**

```shellscript
# hand-maintained direct deps
echo "flask>=3.0" > requirements.txt

# full lock-ish dump of current env
python -m pip freeze > requirements.lock.txt
```

**Extra index / trusted host (careful):**

```shellscript
python -m pip install pkg --index-url https://pypi.org/simple
```

## ⚠️ Pitfalls [#️-pitfalls]

* Never `curl | sh` unknown installers; prefer `python -m pip`.
* `pip freeze` includes transitive pins — great for apps, noisy for libraries.
* Mixing `--user` installs with venvs causes confusion.
* Compiling wheels may need build tools (Rust/C compilers) for some packages.
* Private indexes: protect tokens; don't commit credentials.

## 🔗 Related [#-related]

* [Venv](/docs/python/venv)
* [Packaging](/docs/python/packaging)
* [Import / export](/docs/python/import-export)
* [Testing with pytest](/docs/python/testing-pytest)
* [Examples: http requests](/docs/python/examples/http-requests)
* [Logging](/docs/python/logging)


# Print and Input (/docs/python/print-input)



# Print and Input [#print-and-input]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`print` writes to stdout; `input` reads a line from stdin as `str`. Fine for CLIs and debugging; prefer `logging` for applications and `argparse` for structured CLIs.

## 🔧 Core concepts [#-core-concepts]

| API                                                      | Role                         |
| -------------------------------------------------------- | ---------------------------- |
| `print(*objs, sep=' ', end='\n', file=..., flush=False)` | Output                       |
| `input(prompt="")`                                       | Read line (no trailing `\n`) |
| `sys.stdout` / `stderr`                                  | Streams                      |
| `sys.stdin`                                              | Input stream                 |

`print` converts with `str()`. Soft space separation via `sep`. Use f-strings for formatting.

## 💡 Examples [#-examples]

**print options:**

```python
print("a", "b", "c", sep="-")
print("loading", end="...", flush=True)
print(" done")

import sys
print("error!", file=sys.stderr)
```

**input and parse:**

```python
name = input("Name: ").strip()
raw = input("Count: ").strip()
try:
    count = int(raw)
except ValueError:
    print("Not an integer", file=sys.stderr)
    raise SystemExit(1)
print(f"Hello {name} x{count}")
```

**EOF-safe loop:**

```python
import sys

def main() -> None:
    for line in sys.stdin:
        text = line.strip()
        if not text:
            continue
        print(text.upper())

if __name__ == "__main__":
    main()
```

**Pretty debug:**

```python
from pprint import pprint

data = {"users": [{"id": 1, "name": "Ada"}], "ok": True}
pprint(data, width=40)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `input` always returns `str` — cast explicitly.
* EOF (`Ctrl+D` / `Ctrl+Z`) raises `EOFError` on `input()`.
* Password prompts: use `getpass.getpass` so input is not echoed.
* Leaving debug `print`s in libraries pollutes consumer output — use logging.
* Locale/encoding issues on redirected pipes — prefer UTF-8 aware environments.

## 🔗 Related [#-related]

* [F-strings](/docs/python/f-string)
* [Argparse](/docs/python/argparse)
* [Logging](/docs/python/logging)
* [Examples: cli tool](/docs/python/examples/cli-tool)
* [Strings](/docs/python/strings)
* [Exceptions](/docs/python/exceptions)


# Properties and Descriptors (/docs/python/properties-descriptors)



# Properties and Descriptors [#properties-and-descriptors]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Properties manage attribute access with getters/setters. Descriptors are the underlying protocol (`__get__` / `__set__` / `__delete__`) used by `property`, `classmethod`, and ORMs. Use properties for derived or validated fields; custom descriptors for reusable attribute behavior.

## 🔧 Core concepts [#-core-concepts]

| Tool                       | Role                                      |
| -------------------------- | ----------------------------------------- |
| `@property`                | Getter                                    |
| `@x.setter` / `@x.deleter` | Mutate / delete                           |
| Data descriptor            | Defines `__set__` and/or `__delete__`     |
| Non-data descriptor        | Only `__get__` (e.g. functions)           |
| Lookup order               | Data desc > instance dict > non-data desc |

`property` is implemented as a data descriptor. Slotted classes still work with descriptors on the class.

## 💡 Examples [#-examples]

**Property with validation:**

```python
class Person:
    def __init__(self, name: str, age: int) -> None:
        self.name = name
        self.age = age

    @property
    def age(self) -> int:
        return self._age

    @age.setter
    def age(self, value: int) -> None:
        if value < 0:
            raise ValueError("age must be >= 0")
        self._age = value

    @property
    def label(self) -> str:
        return f"{self.name} ({self._age})"
```

**Simple descriptor:**

```python
from typing import Any

class Positive:
    def __set_name__(self, owner: type, name: str) -> None:
        self.public_name = name
        self.private_name = f"_{name}"

    def __get__(self, obj: object | None, objtype: type | None = None) -> Any:
        if obj is None:
            return self
        return getattr(obj, self.private_name)

    def __set__(self, obj: object, value: int) -> None:
        if value <= 0:
            raise ValueError(f"{self.public_name} must be > 0")
        setattr(obj, self.private_name, value)

class Item:
    qty = Positive()

    def __init__(self, qty: int) -> None:
        self.qty = qty
```

**cached\_property:**

```python
from functools import cached_property

class Report:
    def __init__(self, rows: list[int]) -> None:
        self.rows = rows

    @cached_property
    def total(self) -> int:
        return sum(self.rows)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Infinite recursion: don't touch `self.age` inside its own getter — use `self._age`.
* Data descriptors hide same-named instance attributes.
* `cached_property` is not thread-lock-safe for all use cases; know the docs.
* Overusing setters instead of immutable design can complicate state.
* Descriptors must live on the **class**, not on instances.

## 🔗 Related [#-related]

* [Classes](/docs/python/classes)
* [Decorators](/docs/python/decorators)
* [Magic methods](/docs/python/magic-methods)
* [Dataclasses](/docs/python/dataclasses)
* [ABC / protocols](/docs/python/abc-protocols)
* [Typing hints](/docs/python/typing-hints)


# Random (/docs/python/random)



# Random [#random]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `random` module provides pseudo-random numbers for simulations, sampling, and shuffling. Do **not** use it for security (passwords, tokens) — use `secrets` instead.

## 🔧 Core concepts [#-core-concepts]

| API                                  | Role                   |
| ------------------------------------ | ---------------------- |
| `random()`                           | Float in `[0.0, 1.0)`  |
| `randrange(stop)` / `randint(a, b)`  | Integers               |
| `choice(seq)` / `choices` / `sample` | Pick items             |
| `shuffle(list)`                      | In-place shuffle       |
| `uniform(a, b)` / `gauss`            | Distributions          |
| `seed(n)`                            | Reproducible sequences |
| `Random()`                           | Isolated RNG instance  |

## 💡 Examples [#-examples]

```python
import random

random.seed(42)
print(random.randint(1, 6))
print(random.choice(["red", "green", "blue"]))

deck = list(range(1, 53))
random.shuffle(deck)
hand = random.sample(deck, 5)
```

```python
import random

# Weighted picks
colors = ["common", "rare", "epic"]
print(random.choices(colors, weights=[80, 15, 5], k=3))
```

```python
import secrets

token = secrets.token_urlsafe(16)
code = secrets.randbelow(1_000_000)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `random` is not cryptographically secure — use `secrets` for auth material.
* `shuffle` mutates the list; copy first if you need the original order.
* Global RNG is shared — prefer `random.Random()` in libraries/tests.
* Seeding makes runs reproducible but predictable.

## 🔗 Related [#-related]

* [hashlib](/docs/python/hashlib)
* [statistics](/docs/python/statistics)
* [lambda](/docs/python/lambda)
* [lists](/docs/python/lists)


# Regex (/docs/python/regex)



# Regex [#regex]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The `re` module provides regular expressions for search, match, split, and substitute. Prefer raw strings (`r"..."`). For complex grammars, consider parsers; for fixed substrings, prefer `str` methods.

## 🔧 Core concepts [#-core-concepts]

| API                       | Role                                           |
| ------------------------- | ---------------------------------------------- |
| `re.search`               | First match anywhere                           |
| `re.match`                | Match at start                                 |
| `re.fullmatch`            | Entire string                                  |
| `re.findall` / `finditer` | All matches                                    |
| `re.split`                | Split by pattern                               |
| `re.sub`                  | Replace                                        |
| `re.compile`              | Reuse pattern                                  |
| Flags                     | `IGNORECASE`, `MULTILINE`, `DOTALL`, `VERBOSE` |

Groups: `(...)` capturing, `(?:...)` non-capturing, `(?P<name>...)` named. Conditional patterns exist but stay rare.

## 💡 Examples [#-examples]

**Search and groups:**

```python
import re

text = "user=ada id=42"
m = re.search(r"user=(?P<user>\w+)\s+id=(?P<id>\d+)", text)
if m:
    print(m.group("user"), int(m.group("id")))
```

**Compile and findall:**

```python
import re

email = re.compile(r"[\w.+-]+@[\w-]+\.[\w.-]+")
print(email.findall("a@x.com b@y.org"))
```

**sub and backrefs:**

```python
import re

raw = "2024-07-10"
print(re.sub(r"(\d{4})-(\d{2})-(\d{2})", r"\2/\3/\1", raw))
```

**VERBOSE + flags:**

```python
import re

pattern = re.compile(
    r"""
    ^
    (?P<year>\d{4}) -
    (?P<month>\d{2}) -
    (?P<day>\d{2})
    $
    """,
    re.VERBOSE,
)
print(pattern.fullmatch("2024-07-10").groupdict())  # type: ignore[union-attr]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Catastrophic backtracking on crafted input — avoid nested ambiguous quantifiers on untrusted data.
* `re.match` only checks the start — use `fullmatch` or `search` intentionally.
* Forgetting raw strings: `"\n"` vs `r"\n"` / `"\\d"` mistakes.
* `str.split` / `replace` is clearer for fixed delimiters.
* Bytes patterns require `bytes` input — don't mix str/bytes.

## 🔗 Related [#-related]

* [Strings](/docs/python/strings)
* [F-strings](/docs/python/f-string)
* [JSON](/docs/python/json)
* [Examples: scrape HTML](/docs/python/examples/scrape-html)
* [Files I/O](/docs/python/files-io)
* [Argparse](/docs/python/argparse)


# Requests (/docs/python/requests-http)



# Requests [#requests]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`requests` is the popular third-party HTTP client. Install: `pip install requests`. Use it for GET/POST, JSON APIs, headers, and timeouts. For stdlib-only code, see `urllib` — most apps prefer `requests`.

## 🔧 Core concepts [#-core-concepts]

| API                                 | Role                                   |
| ----------------------------------- | -------------------------------------- |
| `requests.get(url, ...)`            | HTTP GET                               |
| `requests.post(url, ...)`           | HTTP POST                              |
| `params=`                           | Query string dict                      |
| `json=`                             | Encode body as JSON + set content-type |
| `data=` / `files=`                  | Form body / multipart                  |
| `headers=`                          | Custom headers                         |
| `timeout=`                          | Connect/read timeout (seconds)         |
| `r.raise_for_status()`              | Raise on 4xx/5xx                       |
| `r.json()` / `r.text` / `r.content` | Parse response                         |
| `requests.Session()`                | Reuse cookies/connection               |

## 💡 Examples [#-examples]

**GET + JSON:**

```python
import requests

r = requests.get(
    "https://httpbin.org/get",
    params={"q": "python"},
    timeout=10,
)
r.raise_for_status()
print(r.json()["args"])
```

**POST JSON:**

```python
import requests

r = requests.post(
    "https://httpbin.org/post",
    json={"name": "Ada", "active": True},
    headers={"X-Client": "demo"},
    timeout=10,
)
r.raise_for_status()
print(r.json()["json"])
```

**Session:**

```python
import requests

with requests.Session() as s:
    s.headers.update({"Accept": "application/json"})
    r = s.get("https://httpbin.org/headers", timeout=10)
    print(r.json()["headers"]["Accept"])
```

**Error handling:**

```python
import requests

try:
    r = requests.get("https://httpbin.org/status/404", timeout=5)
    r.raise_for_status()
except requests.HTTPError as e:
    print("http error", e.response.status_code)
except requests.RequestException as e:
    print("network/other", e)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Always set `timeout=` — otherwise calls can hang forever.
* Check status: `raise_for_status()` or inspect `r.status_code`.
* `r.json()` fails on empty/non-JSON bodies — catch `ValueError`.
* Don’t disable TLS verify (`verify=False`) in production.
* Third-party package: pin versions in requirements; not in the stdlib.

## 🔗 Related [#-related]

* [Json](/docs/python/json)
* [Urllib parse](/docs/python/urllib-parse)
* [Exceptions](/docs/python/exceptions)
* [Pip](/docs/python/pip)
* [Venv](/docs/python/venv)


# Scope and Namespaces (/docs/python/scope-namespaces)



# Scope and Namespaces [#scope-and-namespaces]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Name lookup follows the **LEGB** rule: Local → Enclosing → Global → Built-in. Assignment creates bindings in the current scope unless `global` or `nonlocal` is declared. Each module and function has its own namespace.

## 🔧 Core concepts [#-core-concepts]

| Scope        | Where                                                         |
| ------------ | ------------------------------------------------------------- |
| Local        | Current function                                              |
| Enclosing    | Outer function(s) — closures                                  |
| Global       | Module level                                                  |
| Built-in     | `builtins` module                                             |
| `global x`   | Bind / assign module name                                     |
| `nonlocal x` | Rebind enclosing function name                                |
| Class body   | Its own namespace; methods don't see it as enclosing for LEGB |

Comprehensions (3.x) have their own local scope for loop targets.

## 💡 Examples [#-examples]

**LEGB:**

```python
len = 3  # shadows built-in — avoid!

def outer() -> None:
    x = "enclosing"

    def inner() -> None:
        print(x)  # enclosing

    inner()

outer()
```

**global / nonlocal:**

```python
counter = 0

def bump_global() -> None:
    global counter
    counter += 1

def make_counter():
    n = 0

    def inc() -> int:
        nonlocal n
        n += 1
        return n

    return inc
```

**Class vs instance:**

```python
class Demo:
    kind = "demo"

    def label(self) -> str:
        # 'kind' is not local; looked up on class via self/type
        return self.kind

print(Demo().label())
```

**Inspect:**

```python
import builtins

def f(a: int = 1) -> None:
    b = 2
    print(locals())
    print("sum" in dir(builtins))

f()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Assignment anywhere in a function makes the name local for the whole function — easy `UnboundLocalError`.
* Shadowing builtins (`list`, `id`, `type`) causes confusing bugs.
* `from module import *` pollutes namespaces — avoid.
* Class attributes vs instance attributes: mutable class attrs are shared.
* Closures late-bind — see [closures](/docs/python/closures).

## 🔗 Related [#-related]

* [Closures](/docs/python/closures)
* [Functions](/docs/python/functions)
* [Classes](/docs/python/classes)
* [Import / export](/docs/python/import-export)
* [Walrus](/docs/python/walrus)
* [Lambda](/docs/python/lambda)


# Secrets (/docs/python/secrets)



# Secrets [#secrets]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`secrets` generates cryptographically strong random numbers suitable for passwords, tokens, and auth codes. Prefer it over `random` whenever unpredictability matters.

## 🔧 Core concepts [#-core-concepts]

| API                | Role                              |
| ------------------ | --------------------------------- |
| `token_bytes(n)`   | `n` random bytes                  |
| `token_hex(n)`     | Hex string (\~2n chars)           |
| `token_urlsafe(n)` | URL-safe base64                   |
| `randbelow(n)`     | Int in `0 .. n-1`                 |
| `choice(seq)`      | Secure pick from sequence         |
| `SystemRandom`     | CSPRNG-backed `random.Random` API |

## 💡 Examples [#-examples]

```python
import secrets
import string

alphabet = string.ascii_letters + string.digits
password = "".join(secrets.choice(alphabet) for _ in range(20))
api_key = secrets.token_urlsafe(32)
otp = f"{secrets.randbelow(1_000_000):06d}"
```

```python
import secrets
from hmac import compare_digest

expected = secrets.token_hex(16)
# constant-time compare for tokens
ok = compare_digest(expected, expected)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Still hash/store passwords with a KDF (e.g. `hashlib.scrypt` / Argon2) — don’t store raw secrets.
* `token_hex(16)` is 16 bytes of entropy → 32 hex chars, not “16 hex chars”.
* Don’t use `random` for session IDs or reset tokens.

## 🔗 Related [#-related]

* [random](/docs/python/random)
* [hashlib](/docs/python/hashlib)
* [dotenv](/docs/python/dotenv)
* [hmac note via hashlib](/docs/python/hashlib)


# Sets (/docs/python/sets)



# Sets [#sets]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A `set` is an unordered collection of unique hashable elements. Use for membership tests, deduplication, and set algebra (union, intersection, difference). `frozenset` is the immutable, hashable variant.

## 🔧 Core concepts [#-core-concepts]

| Operation      | Example                                              |
| -------------- | ---------------------------------------------------- |
| Create         | `\{1, 2\}`, `set(iterable)`, `set()` (not `\{\}`)    |
| Add / remove   | `s.add(x)`, `s.discard(x)`, `s.remove(x)`, `s.pop()` |
| Membership     | `x in s` — average O(1)                              |
| Union          | `a \| b`, `a.union(b)`                               |
| Intersection   | `a & b`, `a.intersection(b)`                         |
| Difference     | `a - b`, `a.difference(b)`                           |
| Symmetric diff | `a ^ b`                                              |
| Subset         | `a &lt;= b`, `a &lt; b` (proper)                     |

Elements must be hashable. Insertion order is preserved for iteration in 3.7+ CPython, but do not treat sets as ordered sequences.

## 💡 Examples [#-examples]

**Deduplicate and membership:**

```python
tags = ["py", "web", "py", "api"]
unique = set(tags)                 # {"py", "web", "api"}
print("web" in unique)             # True
```

**Set algebra:**

```python
required = {"auth", "db", "cache"}
installed = {"auth", "db", "logs"}

missing = required - installed     # {"cache"}
extra = installed - required       # {"logs"}
both = required & installed        # {"auth", "db"}
```

**Comprehension and frozenset:**

```python
evens = {n for n in range(10) if n % 2 == 0}
key = frozenset({"a", "b"})
groups: dict[frozenset[str], int] = {key: 1}
```

**Update in place:**

```python
s = {1, 2}
s |= {2, 3}      # {1, 2, 3}
s &= {2, 3, 4}   # {2, 3}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `\{\}` creates an empty **dict**, not a set — use `set()`.
* Unhashable elements (`list`, `dict`, `set`) raise `TypeError`.
* `remove` raises `KeyError` if missing; `discard` does not.
* Set equality ignores order; do not rely on iteration order for logic.
* Prefer `frozenset` when you need a set as a dict key or nested in another set.

## 🔗 Related [#-related]

* [Lists](/docs/python/lists)
* [Dictionaries](/docs/python/dictionaries)
* [Comprehensions](/docs/python/comprehensions)
* [Types](/docs/python/types)
* [Collections module](/docs/python/collections-module)
* [Truthiness](/docs/python/truthiness)


# Shutil (/docs/python/shutil)



# Shutil [#shutil]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`shutil` is high-level file operations: copy, move, delete trees, find executables, and check disk space. Prefer it over hand-rolled recursive delete/copy. Pair with `pathlib` for path construction.

## 🔧 Core concepts [#-core-concepts]

| API                         | Role                          |
| --------------------------- | ----------------------------- |
| `shutil.copy(src, dst)`     | Copy file (data + mode)       |
| `shutil.copy2(src, dst)`    | Copy + metadata               |
| `shutil.copytree(src, dst)` | Recursive directory copy      |
| `shutil.move(src, dst)`     | Move / rename across devices  |
| `shutil.rmtree(path)`       | Delete directory tree         |
| `shutil.which(cmd)`         | Resolve executable on `PATH`  |
| `shutil.disk_usage(path)`   | `total`, `used`, `free` bytes |
| `shutil.make_archive`       | Zip/tar helpers               |

## 💡 Examples [#-examples]

**Copy and move:**

```python
import shutil
from pathlib import Path

src = Path("report.txt")
shutil.copy(src, "backup/report.txt")       # file → file/dir
shutil.copy2(src, "backup/report_meta.txt")
shutil.move("backup/report.txt", "archive/report.txt")
```

**Remove a tree safely:**

```python
import shutil
from pathlib import Path

build = Path("build")
if build.exists():
    shutil.rmtree(build)
build.mkdir()
```

**which + disk\_usage:**

```python
import shutil

print(shutil.which("python"), shutil.which("git"))
usage = shutil.disk_usage(".")
print(f"free={usage.free / 1e9:.1f} GB of {usage.total / 1e9:.1f} GB")
```

**copytree with dirs\_exist\_ok (3.8+):**

```python
import shutil

shutil.copytree("templates", "out/templates", dirs_exist_ok=True)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `rmtree` is irreversible — confirm the path; no recycle bin.
* `copy` overwrites existing destination files without asking.
* `copytree` fails if `dst` exists unless `dirs_exist_ok=True`.
* `which` returns `None` if not found — check before `subprocess`.
* On Windows, open files can block `rmtree` / `move`.

## 🔗 Related [#-related]

* [Pathlib](/docs/python/pathlib)
* [Files I/O](/docs/python/files-io)
* [Os](/docs/python/os)
* [Tempfile](/docs/python/tempfile)
* [Glob](/docs/python/glob-module)


# Slicing (/docs/python/slicing)



# Slicing [#slicing]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Slicing extracts subsequences with `seq[start:stop:step]`. Works on lists, tuples, strings, bytes, and custom sequences implementing `__getitem__`. Slices return a new object for built-in sequences (shallow copy of references).

## 🔧 Core concepts [#-core-concepts]

| Form             | Meaning                             |
| ---------------- | ----------------------------------- |
| `s[i]`           | Single index (negatives from end)   |
| `s[a:b]`         | From `a` inclusive to `b` exclusive |
| `s[a:b:c]`       | Step `c`                            |
| `s[:]`           | Shallow copy (list/tuple/str)       |
| `s[::-1]`        | Reversed copy                       |
| `slice(a, b, c)` | Slice object                        |
| Assign           | `xs[a:b] = iterable` (lists)        |

Omitted bounds default to ends. Out-of-range slice bounds are clipped; single-index OOB raises `IndexError`.

## 💡 Examples [#-examples]

**Basics:**

```python
xs = ["a", "b", "c", "d", "e"]
print(xs[1:4])     # ['b', 'c', 'd']
print(xs[:2])      # ['a', 'b']
print(xs[::2])     # ['a', 'c', 'e']
print(xs[::-1])    # ['e', 'd', 'c', 'b', 'a']
print(xs[-3:-1])   # ['c', 'd']
```

**Strings and bytes:**

```python
text = "Python"
print(text[1:4])       # "yth"
print(text[::-1])      # "nohtyP"
data = b"\x00\x01\x02\x03"
print(data[1:3])       # b'\x01\x02'
```

**List slice assign / delete:**

```python
nums = [0, 1, 2, 3, 4]
nums[1:3] = [8, 9, 10]   # [0, 8, 9, 10, 3, 4]
del nums[2:4]            # [0, 8, 3, 4]
nums[::2] = [7, 7]       # length must match for extended slice
```

**slice object:**

```python
window = slice(1, 4)
print("abcdef"[window])  # "bcd"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `xs[:]` is shallow — nested mutables are shared.
* Slice assignment length rules differ for plain vs extended (`step != 1`) slices.
* `s[i:j]` never raises for bad bounds; `s[i]` does.
* Strings/tuples are immutable — cannot slice-assign.
* Copying huge sequences with `[:]` costs memory; prefer views/iterators when possible.

## 🔗 Related [#-related]

* [Lists](/docs/python/lists)
* [Strings](/docs/python/strings)
* [Tuples](/docs/python/tuples)
* [Bytes / bytearray](/docs/python/bytes-bytearray)
* [Copy / deepcopy](/docs/python/copy-deepcopy)
* [Comprehensions](/docs/python/comprehensions)


# Sqlite3 (/docs/python/sqlite3)



# Sqlite3 [#sqlite3]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`sqlite3` is the stdlib binding to SQLite — a serverless SQL database in a single file (or `:memory:`). Use parameterized queries always. Prefer the connection as a context manager for transactions.

## 🔧 Core concepts [#-core-concepts]

| API                            | Role                                 |
| ------------------------------ | ------------------------------------ |
| `sqlite3.connect(path)`        | Open DB file / `:memory:`            |
| `conn.execute(sql, params)`    | Run one statement                    |
| `conn.executemany(sql, seq)`   | Batch inserts/updates                |
| `conn.commit()` / `rollback()` | Transactions                         |
| `conn.cursor()`                | Explicit cursor (optional)           |
| `with conn:`                   | Commit on success, rollback on error |
| `row_factory = sqlite3.Row`    | Name-based row access                |
| `conn.close()`                 | Release file                         |

Placeholders: `?` positional or `:name` named — never f-string SQL.

## 💡 Examples [#-examples]

**Connect + create + insert:**

```python
import sqlite3
from pathlib import Path

db = Path("app.db")
with sqlite3.connect(db) as conn:
    conn.execute(
        "CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"
    )
    conn.execute("INSERT INTO users (name) VALUES (?)", ("Ada",))
    # with-block commits on success
```

**Query rows:**

```python
import sqlite3

conn = sqlite3.connect("app.db")
conn.row_factory = sqlite3.Row
try:
    rows = conn.execute("SELECT id, name FROM users WHERE name = ?", ("Ada",)).fetchall()
    for row in rows:
        print(row["id"], row["name"])
finally:
    conn.close()
```

**executemany:**

```python
import sqlite3

rows = [("Lin",), ("Grace",), ("Ken",)]
with sqlite3.connect("app.db") as conn:
    conn.executemany("INSERT INTO users (name) VALUES (?)", rows)
```

**In-memory + context manager:**

```python
import sqlite3

with sqlite3.connect(":memory:") as conn:
    conn.execute("CREATE TABLE t (x INTEGER)")
    conn.execute("INSERT INTO t VALUES (1), (2)")
    print(conn.execute("SELECT SUM(x) FROM t").fetchone()[0])
```

## ⚠️ Pitfalls [#️-pitfalls]

* Never interpolate user input into SQL — use `?` / named params.
* Outside `with conn:`, remember `commit()` or changes vanish.
* SQLite locks the DB file; long writes block readers.
* `Row` access needs `row_factory`; default rows are tuples.
* Keep connections short-lived in web apps, or use a pool carefully.

## 🔗 Related [#-related]

* [Context managers](/docs/python/context-managers)
* [Pathlib](/docs/python/pathlib)
* [Exceptions](/docs/python/exceptions)
* [Json](/docs/python/json)


# Statistics (/docs/python/statistics)



# Statistics [#statistics]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`statistics` is the stdlib module for basic descriptive stats on numeric data. For heavy analysis and DataFrames, prefer [pandas](/docs/python/pandas) / NumPy.

## 🔧 Core concepts [#-core-concepts]

| API                      | Role                                        |
| ------------------------ | ------------------------------------------- |
| `mean` / `fmean`         | Arithmetic mean (`fmean` faster for floats) |
| `median` / `mode`        | Middle value / most common                  |
| `pstdev` / `stdev`       | Population / sample stdev                   |
| `pvariance` / `variance` | Variance                                    |
| `quantiles`              | Cut points                                  |
| `correlation`            | Pearson correlation (3.10+)                 |

## 💡 Examples [#-examples]

```python
from statistics import mean, median, mode, stdev

xs = [2, 4, 4, 4, 5, 5, 7, 9]
print(mean(xs), median(xs), mode(xs))
print(stdev(xs))
```

```python
from statistics import quantiles, correlation

data = [1, 2, 3, 4, 5, 6, 7, 8, 9]
print(quantiles(data, n=4))  # quartiles
print(correlation([1, 2, 3], [2, 4, 6]))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Empty sequences raise `StatisticsError`.
* `mode` raises if no unique mode (use `multimode`).
* Sample vs population (`stdev` vs `pstdev`) — know which you need.
* Not a substitute for pandas groupby / NumPy vectorized ops on large data.

## 🔗 Related [#-related]

* [pandas](/docs/python/pandas)
* [random](/docs/python/random)
* [lists](/docs/python/lists)
* [functools](/docs/python/functools)


# Strings (/docs/python/strings)



# Strings [#strings]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`str` is an immutable sequence of Unicode code points. Build strings with f-strings, `join`, and methods like `split`/`strip`/`replace`. Prefer methods and the `str` API over manual index loops. For binary data use `bytes` / `bytearray`.

## 🔧 Core concepts [#-core-concepts]

**Literals / access**

| Area          | Notes                                                               |
| ------------- | ------------------------------------------------------------------- |
| Literals      | `'...'`, `"..."`, `'''...'''`, `"""..."""`, raw `r"..."`, f-strings |
| Immutability  | Methods return **new** strings                                      |
| Index / slice | `s[0]`, `s[-1]`, `s[1:4]`, `s[::-1]`                                |
| Encode        | `s.encode("utf-8")`, `b.decode("utf-8")`                            |

**Search / test**

| Method                                                                         | Notes                              |
| ------------------------------------------------------------------------------ | ---------------------------------- |
| `in` / `find` / `rfind`                                                        | Substring; `find` → −1 if missing  |
| `index` / `rindex`                                                             | Like find; raises `ValueError`     |
| `startswith` / `endswith`                                                      | Prefix/suffix; tuple of options ok |
| `count(sub[, start[, end]])`                                                   | Non-overlapping count              |
| `isalnum` / `isalpha` / `isdigit` / `isdecimal` / `isnumeric`                  | Character class tests              |
| `islower` / `isupper` / `istitle` / `isspace` / `isidentifier` / `isprintable` | More predicates                    |

**Case / strip / pad / align**

| Method                                                  | Notes                           |
| ------------------------------------------------------- | ------------------------------- |
| `lower` / `upper` / `title` / `capitalize` / `swapcase` | Case transforms                 |
| `casefold()`                                            | Aggressive caseless matching    |
| `strip` / `lstrip` / `rstrip`                           | Trim chars (default whitespace) |
| `removeprefix` / `removesuffix`                         | Exact affix remove (3.9+)       |
| `center` / `ljust` / `rjust` / `zfill`                  | Pad / zero-pad                  |

**Split / join / partition / replace**

| Method                                  | Notes                             |
| --------------------------------------- | --------------------------------- |
| `split(sep=None, maxsplit=-1)`          | `None` collapses whitespace       |
| `rsplit` / `splitlines(keepends=False)` | From right; by line breaks        |
| `partition` / `rpartition`              | → `(before, sep, after)`          |
| `",".join(parts)`                       | Join iterable of **str**          |
| `replace(old, new, count=-1)`           | Replace occurrences               |
| `translate(table)` / `maketrans`        | Char mapping (fast multi-replace) |
| `format` / `format_map` / f-strings     | Interpolation                     |

Multiline strings keep newlines; use `textwrap.dedent` for indented source blocks.

## 💡 Examples [#-examples]

**Clean and split:**

```python
raw = "  Ada, Bob, Cary  "
names = [p.strip() for p in raw.split(",")]
print(names)  # ['Ada', 'Bob', 'Cary']
print(", ".join(names))
```

**Checks and replace:**

```python
path = "Report.PDF"
print(path.lower().endswith(".pdf"))
print(path.removesuffix(".PDF") + ".pdf")  # 3.9+
```

**Slicing and membership:**

```python
s = "python"
print(s[1:4])      # yth
print("th" in s)   # True
print(s[::-1])     # nohtyp
```

**Bytes boundary:**

```python
text = "café"
data = text.encode("utf-8")
print(data)                 # b'caf\xc3\xa9'
print(data.decode("utf-8"))
```

## ⚠️ Pitfalls [#️-pitfalls]

* `str` is immutable—`s[0] = "X"` is illegal; build a new string.
* `+` in a loop is quadratic for large joins—use `"".join(parts)`.
* Default `split()` collapses whitespace; `split(" ")` does not.
* Comparing with `==` is case-sensitive; normalize with `casefold()` for caseless match.
* Mixing `str` and `bytes` raises `TypeError`—decode/encode explicitly.

## 🔗 Related [#-related]

* [F-strings](/docs/python/f-string)
* [Types](/docs/python/types)
* [Loops](/docs/python/loops)
* [Docstrings](/docs/python/docstrings)
* [Dictionaries](/docs/python/dictionaries)
* [Examples: convert files](/docs/python/examples/convert-files)


# Subprocess (/docs/python/subprocess)



# Subprocess [#subprocess]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`subprocess` runs external programs. Prefer `subprocess.run(...)` over older `Popen`/`call` helpers for most scripts. Capture output when you need it; raise on failure with `check=True`.

## 🔧 Core concepts [#-core-concepts]

| API                           | Role                                     |
| ----------------------------- | ---------------------------------------- |
| `subprocess.run(args, ...)`   | Run and wait; returns `CompletedProcess` |
| `capture_output=True`         | Capture stdout/stderr as bytes           |
| `text=True` / `encoding=`     | Decode streams as str                    |
| `check=True`                  | Raise `CalledProcessError` on non-zero   |
| `cwd=` / `env=`               | Working dir / environment                |
| `timeout=`                    | Kill if too slow                         |
| `shell=True`                  | Run via shell (usually avoid)            |
| `CompletedProcess.returncode` | Exit status                              |

Pass args as a **list** unless you truly need shell features.

## 💡 Examples [#-examples]

**Basic run:**

```python
import subprocess

r = subprocess.run(["python", "-c", "print(1+1)"], capture_output=True, text=True)
print(r.returncode, r.stdout.strip())
```

**check + capture:**

```python
import subprocess

try:
    r = subprocess.run(
        ["git", "rev-parse", "HEAD"],
        capture_output=True,
        text=True,
        check=True,
    )
    print(r.stdout.strip())
except subprocess.CalledProcessError as e:
    print("failed:", e.returncode, e.stderr)
```

**cwd and env:**

```python
import os
import subprocess

env = {**os.environ, "MY_FLAG": "1"}
subprocess.run(["ls"], cwd="/tmp", env=env, check=True)
```

**Avoid shell when possible:**

```python
import subprocess

# Good: list form, no shell
subprocess.run(["echo", "hello"], check=True)

# Risky: shell=True with untrusted input → injection
# subprocess.run(f"echo {user}", shell=True)  # DON'T
```

## ⚠️ Pitfalls [#️-pitfalls]

* `shell=True` + unsanitized input enables command injection — use argument lists.
* Without `capture_output` / `stdout=PIPE`, output goes to the console.
* Forgotten `text=True` leaves `bytes` in `.stdout`.
* `check=False` (default) hides failures — set `check=True` or inspect `returncode`.
* Deadlocks are rare with `run`; with raw `Popen` pipes, always drain or use `communicate`.

## 🔗 Related [#-related]

* [Sys](/docs/python/sys)
* [Os](/docs/python/os)
* [Shutil](/docs/python/shutil)
* [Argparse](/docs/python/argparse)
* [Exceptions](/docs/python/exceptions)


# Sys (/docs/python/sys)



# Sys [#sys]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`sys` exposes interpreter and process plumbing: CLI args, module search path, exit codes, and standard streams. Use it for lightweight CLIs; prefer `argparse` when flags grow.

## 🔧 Core concepts [#-core-concepts]

| API                                | Role                                  |
| ---------------------------------- | ------------------------------------- |
| `sys.argv`                         | CLI args: `[script, ...]`             |
| `sys.path`                         | Module import search list             |
| `sys.exit(code)`                   | Exit process (`0` ok, non-zero error) |
| `sys.stdin` / `stdout` / `stderr`  | Text streams                          |
| `sys.version` / `sys.version_info` | Runtime version                       |
| `sys.platform`                     | `win32`, `linux`, `darwin`, …         |
| `sys.executable`                   | Path to this Python binary            |
| `sys.getsizeof(obj)`               | Approx. object size (bytes)           |

## 💡 Examples [#-examples]

**argv:**

```python
import sys

# python tool.py a b
script, *args = sys.argv
print("script:", script)
print("args:", args)
if not args:
    sys.exit("usage: tool.py <files...>")
```

**path and version:**

```python
import sys
from pathlib import Path

print(sys.version_info[:3])
print(sys.executable)
# Add local package root for scripts (prefer installable packages):
root = Path(__file__).resolve().parent
if str(root) not in sys.path:
    sys.path.insert(0, str(root))
```

**stdin / stdout:**

```python
import sys

for line in sys.stdin:
    sys.stdout.write(line.upper())
# echo hello | python upper.py
```

**exit codes:**

```python
import sys

ok = True
sys.exit(0 if ok else 1)
# or: raise SystemExit(2)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `sys.argv[0]` is the script path (or `-c` / `-m`), not always a useful name.
* Mutating `sys.path` is a last resort — prefer packages / `PYTHONPATH` / editable installs.
* `sys.exit("msg")` prints to stderr and exits with code `1`.
* Redirected stdout may be block-buffered — flush or use `print(..., flush=True)`.
* Don’t compare versions as strings; use `sys.version_info >= (3, 11)`.

## 🔗 Related [#-related]

* [Argparse](/docs/python/argparse)
* [Os](/docs/python/os)
* [Subprocess](/docs/python/subprocess)
* [Print / input](/docs/python/print-input)
* [Import / export](/docs/python/import-export)


# Tempfile (/docs/python/tempfile)



# Tempfile [#tempfile]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`tempfile` creates temporary files and directories that are unique and (usually) cleaned up automatically. Prefer context managers (`TemporaryDirectory`, `NamedTemporaryFile`) so cleanup happens even on errors.

## 🔧 Core concepts [#-core-concepts]

| API                            | Role                              |
| ------------------------------ | --------------------------------- |
| `TemporaryDirectory()`         | Temp dir; deleted on exit         |
| `NamedTemporaryFile()`         | Named temp file on disk           |
| `TemporaryFile()`              | Anon file (may lack usable name)  |
| `mkstemp()` / `mkdtemp()`      | Low-level create (manual cleanup) |
| `gettempdir()`                 | System temp directory             |
| `suffix=` / `prefix=` / `dir=` | Naming / location                 |

On Windows, `NamedTemporaryFile(delete=True)` may block reopening by name while still open — use `delete=False` and unlink yourself when needed.

## 💡 Examples [#-examples]

**TemporaryDirectory:**

```python
from pathlib import Path
from tempfile import TemporaryDirectory

with TemporaryDirectory(prefix="job-") as tmp:
    root = Path(tmp)
    (root / "out.txt").write_text("ok", encoding="utf-8")
    print(list(root.iterdir()))
# directory is gone here
```

**NamedTemporaryFile:**

```python
from tempfile import NamedTemporaryFile

with NamedTemporaryFile("w+", suffix=".csv", delete=True, encoding="utf-8") as f:
    f.write("a,b\n1,2\n")
    f.flush()
    print(f.name)
    f.seek(0)
    print(f.read())
```

**delete=False for external tools:**

```python
from pathlib import Path
from tempfile import NamedTemporaryFile

with NamedTemporaryFile("w", suffix=".txt", delete=False, encoding="utf-8") as f:
    path = Path(f.name)
    f.write("payload")

try:
    print(path.read_text(encoding="utf-8"))
finally:
    path.unlink(missing_ok=True)
```

**gettempdir:**

```python
import tempfile
from pathlib import Path

print(Path(tempfile.gettempdir()))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Temp dirs vanish when the context exits — copy results out first.
* Windows: can’t always reopen a still-open `NamedTemporaryFile` by name.
* `mkstemp` returns an open fd you must close and a path you must delete.
* Secure defaults matter for secrets; avoid world-readable custom `dir=`.
* Don’t assume temp paths persist across reboots or process restarts.

## 🔗 Related [#-related]

* [Pathlib](/docs/python/pathlib)
* [Files I/O](/docs/python/files-io)
* [Shutil](/docs/python/shutil)
* [Context managers](/docs/python/context-managers)
* [Os](/docs/python/os)


# Testing with pytest (/docs/python/testing-pytest)



# Testing with pytest [#testing-with-pytest]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`pytest` discovers and runs tests with plain `assert`, fixtures, parametrization, and rich failure diffs. Prefer it over `unittest` for new projects. Name files `test_*.py` or `*_test.py`.

## 🔧 Core concepts [#-core-concepts]

| Feature       | Role                                 |
| ------------- | ------------------------------------ |
| Discovery     | `test_*` functions/classes           |
| `assert`      | Rewritten with introspection         |
| Fixtures      | Setup/teardown via `@pytest.fixture` |
| `parametrize` | Data-driven cases                    |
| Markers       | `@pytest.mark.skip`, `slow`, etc.    |
| `raises`      | Expect exceptions                    |
| `tmp_path`    | Temp directory fixture               |
| Plugins       | `pytest-cov`, `pytest-asyncio`, …    |

Run with `pytest` or `python -m pytest`. Exit code 0 = all passed.

## 💡 Examples [#-examples]

**Basic tests:**

```python
# test_mathutil.py
def add(a: int, b: int) -> int:
    return a + b

def test_add():
    assert add(2, 3) == 5

def test_add_negative():
    assert add(-1, 1) == 0
```

**Fixtures and tmp\_path:**

```python
import pytest
from pathlib import Path

@pytest.fixture
def sample_file(tmp_path: Path) -> Path:
    p = tmp_path / "data.txt"
    p.write_text("hello", encoding="utf-8")
    return p

def test_read(sample_file: Path):
    assert sample_file.read_text(encoding="utf-8") == "hello"
```

**Parametrize and raises:**

```python
import pytest

@pytest.mark.parametrize("n,expected", [(0, 0), (1, 1), (2, 4)])
def test_square(n: int, expected: int):
    assert n * n == expected

def test_div_zero():
    with pytest.raises(ZeroDivisionError):
        _ = 1 / 0
```

**CLI:**

```shellscript
pytest -q
pytest -k "add" --maxfail=1
pytest --cov=mypkg --cov-report=term-missing
```

## ⚠️ Pitfalls [#️-pitfalls]

* Tests that depend on execution order or shared global state flake.
* Overusing mocks hides real integration bugs — mix unit + integration.
* Mutable fixture state shared across tests when scope is wrong.
* Asserting on exact error strings is brittle — match exception type.
* Don't commit secrets into test fixtures.

## 🔗 Related [#-related]

* [Examples: pytest example](/docs/python/examples/pytest-example)
* [Exceptions](/docs/python/exceptions)
* [Venv](/docs/python/venv)
* [Pip](/docs/python/pip)
* [Functions](/docs/python/functions)
* [Packaging](/docs/python/packaging)


# Truthiness (/docs/python/truthiness)



# Truthiness [#truthiness]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

In boolean contexts (`if`, `while`, `and`/`or`, `bool(x)`), objects are truthy or falsy. Prefer explicit checks (`is None`, `len`, `==`) when zero/empty must be distinguished from missing.

## 🔧 Core concepts [#-core-concepts]

| Falsy            | Examples                                 |
| ---------------- | ---------------------------------------- |
| Constants        | `None`, `False`                          |
| Numbers          | `0`, `0.0`, `0j`                         |
| Empty containers | `""`, `[]`, `()`, `\{\}`, `set()`        |
| Empty binary     | `b""`, `bytearray()`                     |
| Custom           | `__bool__` → `False`, or `__len__` → `0` |

Everything else is truthy by default — including `"0"`, `[0]`, and custom objects.

## 💡 Examples [#-examples]

**Typical checks:**

```python
name = ""
items: list[int] = []

if not name:
    print("missing name")
if items:
    print("has items")
```

**None vs empty:**

```python
def title(value: str | None) -> str:
    if value is None:
        return "default"
    if not value:
        return "empty"
    return value

print(title(None), title(""), title("Hi"))
```

**and / or return operands:**

```python
print("" or "fallback")     # "fallback"
print("hi" or "fallback")   # "hi"
print("hi" and "there")     # "there"
user = None
print((user or {}).get("id"))
```

**Custom bool:**

```python
class Gate:
    def __init__(self, open_: bool) -> None:
        self.open = open_

    def __bool__(self) -> bool:
        return self.open

g = Gate(False)
print(bool(g), "yes" if g else "no")
```

## ⚠️ Pitfalls [#️-pitfalls]

* `if xs` is False for empty lists — OK for "any items?", wrong for "was provided?".
* `if count:` fails for `0` even when zero is valid.
* NumPy arrays: truth value is ambiguous — use `.any()` / `.all()`.
* Don't use `== True` / `== False`; use `is True` only for actual bools, else rely on truthiness carefully.
* `__bool__` and `__len__` must be consistent if both exist.

## 🔗 Related [#-related]

* [Conditionals](/docs/python/conditionals)
* [Operators](/docs/python/operators)
* [Lists](/docs/python/lists)
* [Dictionaries](/docs/python/dictionaries)
* [Magic methods](/docs/python/magic-methods)
* [Types](/docs/python/types)


# Tuples (/docs/python/tuples)



# Tuples [#tuples]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A `tuple` is an ordered, immutable sequence. Use for fixed records, multiple return values, and hashable keys (when all elements are hashable). Prefer tuples over lists when the length and contents should not change.

## 🔧 Core concepts [#-core-concepts]

| Operation       | Example                                       |
| --------------- | --------------------------------------------- |
| Create          | `(1, 2)`, `1, 2`, `tuple(iterable)`, `()`     |
| Single element  | `(1,)` — trailing comma required              |
| Index / slice   | `t[0]`, `t[1:]`                               |
| Unpack          | `a, b = t`, `a, *rest = t`                    |
| Concat / repeat | `t + u`, `t * n` (new tuples)                 |
| Named           | `collections.namedtuple`, `typing.NamedTuple` |

Immutability means you cannot assign `t[i] = x` or `append`. Nested mutable objects inside a tuple can still mutate.

## 💡 Examples [#-examples]

**Returns and unpacking:**

```python
def divmod_pair(a: int, b: int) -> tuple[int, int]:
    return a // b, a % b

q, r = divmod_pair(17, 5)
```

**As dict keys:**

```python
point = (3, 4)
grid: dict[tuple[int, int], str] = {point: "occupied"}
print(grid[(3, 4)])
```

**NamedTuple (typed record):**

```python
from typing import NamedTuple

class User(NamedTuple):
    id: int
    name: str
    active: bool = True

u = User(1, "Ada")
print(u.name, u._asdict())
```

**Tuple vs list choice:**

```python
coords = (10.0, 20.0)      # fixed pair — tuple
history: list[float] = []  # grows over time — list
history.append(1.5)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `(1)` is just `int` 1 — use `(1,)` for a one-element tuple.
* Tuples containing lists/dicts are not hashable.
* `t += (x,)` rebinds `t` to a new tuple (ok for local names; confusing for aliases).
* Prefer `NamedTuple` / `dataclass(frozen=True)` over anonymous long tuples for clarity.
* Slicing a tuple returns a tuple, not a list.

## 🔗 Related [#-related]

* [Lists](/docs/python/lists)
* [Sets](/docs/python/sets)
* [Dataclasses](/docs/python/dataclasses)
* [Unpacking](/docs/python/unpacking)
* [Types](/docs/python/types)
* [Dictionaries](/docs/python/dictionaries)


# Types (/docs/python/types)



# Types [#types]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Python is dynamically typed at runtime and optionally statically checked via type annotations (PEP 484+). Use built-in generics (`list[str]`, `dict[str, int]`), `typing` utilities, and `|` unions (3.10+). Annotations document APIs and enable mypy/pyright—they do not enforce types at runtime unless you add a validator.

## 🔧 Core concepts [#-core-concepts]

| Kind             | Examples                                         |
| ---------------- | ------------------------------------------------ |
| Built-ins        | `int`, `float`, `bool`, `str`, `bytes`, `None`   |
| Collections      | `list[T]`, `dict[K, V]`, `set[T]`, `tuple[A, B]` |
| Union / optional | `int \| None`, `str \| int`                      |
| Callables        | `Callable[[int, str], bool]`                     |
| Protocols        | Structural typing (`typing.Protocol`)            |
| Aliases          | `type UserId = int` (3.12+) or `TypeAlias`       |
| Generics         | `class Box[T]: ...` (3.12+) or `TypeVar`         |

`isinstance` / `issubclass` for runtime checks; prefer EAFP with care for public boundaries.

## 💡 Examples [#-examples]

**Annotations and unions:**

```python
def parse_id(value: str | int) -> int:
    return int(value)

def find(name: str) -> str | None:
    return name if name else None
```

**Collections and TypedDict:**

```python
from typing import TypedDict

class User(TypedDict):
    id: int
    name: str
    active: bool

users: list[User] = [{"id": 1, "name": "Ada", "active": True}]
```

**Protocol (duck typing):**

```python
from typing import Protocol

class Closeable(Protocol):
    def close(self) -> None: ...

def shutdown(resource: Closeable) -> None:
    resource.close()
```

**Runtime check helpers:**

```python
from collections.abc import Iterable

def total(xs: Iterable[int]) -> int:
    return sum(xs)

assert isinstance(True, int)  # bool is a subclass of int
```

## ⚠️ Pitfalls [#️-pitfalls]

* Annotations are not runtime-enforced: `def f(x: int): ...` still accepts any object.
* Mutable default arguments (`def f(xs=[])`) share one list—use `None` + create inside.
* `list` vs `List` from `typing`: prefer built-ins on 3.9+.
* `tuple[int]` is a one-int tuple; `tuple[int, ...]` is variable length.
* Over-annotating trivial locals adds noise; focus on public functions and complex structures.

## 🔗 Related [#-related]

* [Dictionaries](/docs/python/dictionaries)
* [Docstrings](/docs/python/docstrings)
* [\*args and \*\*kwargs](/docs/python/kwags)
* [Strings](/docs/python/strings)
* [Import / export](/docs/python/import-export)
* [Async / await](/docs/python/async)


# Typing Hints (/docs/python/typing-hints)



# Typing Hints [#typing-hints]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Type hints document and check interfaces with tools like mypy/pyright. They are not enforced at runtime by default. Prefer built-in generics (`list[int]`) on 3.9+ and `|` unions on 3.10+.

## 🔧 Core concepts [#-core-concepts]

| Feature             | Example                              |
| ------------------- | ------------------------------------ |
| Built-in generics   | `list[int]`, `dict[str, int]`        |
| Union               | `int \| None`, `str \| bytes`        |
| Optional            | `X \| None` (prefer over `Optional`) |
| Callable            | `Callable[[int], str]`               |
| TypeAlias           | `type Vector = list[float]` (3.12+)  |
| TypeVar / ParamSpec | Generics                             |
| Protocol            | Structural typing                    |
| TypedDict           | Dict shapes                          |
| `typing.cast`       | Escape hatch for checkers            |
| `typing.Any`        | Opt out (use sparingly)              |

From 3.11+: `Self`, `LiteralString`, improved error types. From 3.12+: `type` statement, PEP 695 generics.

## 💡 Examples [#-examples]

**Functions and collections:**

```python
from collections.abc import Iterable, Sequence

def average(xs: Sequence[float]) -> float:
    return sum(xs) / len(xs)

def flatten(rows: Iterable[Iterable[int]]) -> list[int]:
    return [n for row in rows for n in row]
```

**Aliases and TypedDict:**

```python
from typing import TypedDict

type UserId = int  # 3.12+; else TypeAlias

class User(TypedDict):
    id: UserId
    name: str
    active: bool

def label(u: User) -> str:
    return f'{u["name"]}#{u["id"]}'
```

**Generics (3.12+):**

```python
def first[T](items: Sequence[T]) -> T | None:
    return items[0] if items else None
```

**Protocol:**

```python
from typing import Protocol

class Closable(Protocol):
    def close(self) -> None: ...

def shutdown(resource: Closable) -> None:
    resource.close()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hints are ignored at runtime unless you validate (pydantic, beartype, etc.).
* Use `collections.abc` for `Iterable`/`Mapping`/`Sequence`, not concrete lists only.
* `list` is invariant — `list[int]` is not a `list[float | int]` for checkers.
* Avoid `Any` sprawl; prefer `object` or precise unions.
* Forward refs: quote names or `from __future__ import annotations`.

## 🔗 Related [#-related]

* [Functions](/docs/python/functions)
* [ABC / protocols](/docs/python/abc-protocols)
* [Dataclasses](/docs/python/dataclasses)
* [Classes](/docs/python/classes)
* [Types](/docs/python/types)
* [Docstrings](/docs/python/docstrings)


# Unpacking (/docs/python/unpacking)



# Unpacking [#unpacking]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Unpacking assigns elements of iterables (and keys/values of mappings with `**`) into names or containers. Covers tuple unpacking, starred targets, function call unpacking, and dict merges. Related to but broader than [\*args/\*\*kwargs](/docs/python/kwags).

## 🔧 Core concepts [#-core-concepts]

| Form               | Role                           |
| ------------------ | ------------------------------ |
| `a, b = pair`      | Sequence unpack                |
| `a, *rest, z = xs` | Starred target                 |
| `*args` in call    | Unpack iterable as positionals |
| `**kwargs` in call | Unpack mapping as keywords     |
| `\{**a, **b\}`     | Dict merge (right wins)        |
| `[*a, *b]`         | List concat via unpack         |
| Nested             | ` (a, (b, c)) = ...`           |

Length must match unless a starred target absorbs extras. `strict=True` on `zip` helps parallel unpack.

## 💡 Examples [#-examples]

**Basics and star:**

```python
first, second = (10, 20)
head, *mid, tail = [1, 2, 3, 4, 5]
# head=1, mid=[2,3,4], tail=5
```

**Swap and nested:**

```python
a, b = 1, 2
a, b = b, a

row = (1, (2, 3))
i, (j, k) = row
```

**Call site unpacking:**

```python
def greeter(name: str, city: str, *titles: str) -> str:
    extra = " ".join(titles)
    return f"{name} @ {city} {extra}".strip()

args = ("Ada", "London")
opts = {"titles": ("Dr",)}  # won't work as ** for *titles
print(greeter(*args, "Dr"))

vals = [1, 2, 3]
print(max(*vals))
```

**Dict / list merges:**

```python
defaults = {"host": "localhost", "port": 8000}
user = {"port": 9000}
cfg = {**defaults, **user}      # port=9000

a, b = [1, 2], [3, 4]
merged = [*a, *b]               # [1, 2, 3, 4]
```

**For-loop unpack:**

```python
pairs = [("a", 1), ("b", 2)]
for key, value in pairs:
    print(key, value)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Too many / too few values raises `ValueError`.
* `**` keys must be strings for function calls.
* Later `**` wins on key clashes — order matters.
* Starred expression in assignment: only one `*` target allowed.
* Unpacking generators consumes them.

## 🔗 Related [#-related]

* [\*args and \*\*kwargs](/docs/python/kwags)
* [Tuples](/docs/python/tuples)
* [Lists](/docs/python/lists)
* [Dictionaries](/docs/python/dictionaries)
* [Functions](/docs/python/functions)
* [Loops](/docs/python/loops)


# Urllib.parse (/docs/python/urllib-parse)



# Urllib.parse [#urllibparse]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`urllib.parse` splits and builds URLs: parse components, encode query strings, and percent-encode path segments. Stdlib — no install. Pair with `urllib.request` or [Requests](/docs/python/requests-http) for HTTP.

## 🔧 Core concepts [#-core-concepts]

| API                        | Role                                   |
| -------------------------- | -------------------------------------- |
| `urlparse(url)`            | Split into scheme/netloc/path/…        |
| `urlunparse(parts)`        | Rebuild from parts                     |
| `urlsplit` / `urlunsplit`  | Similar; path keeps params differently |
| `parse_qs` / `parse_qsl`   | Query string → dict / list of pairs    |
| `urlencode(query)`         | Dict/pairs → query string              |
| `quote(s)` / `quote_plus`  | Percent-encode (path vs form)          |
| `unquote` / `unquote_plus` | Decode                                 |
| `urljoin(base, url)`       | Resolve relative URLs                  |

`ParseResult` fields: `scheme`, `netloc`, `path`, `params`, `query`, `fragment`.

## 💡 Examples [#-examples]

**urlparse:**

```python
from urllib.parse import urlparse

u = urlparse("https://example.com:443/a/b?x=1#top")
print(u.scheme, u.hostname, u.port, u.path, u.query, u.fragment)
```

**urlencode + quote:**

```python
from urllib.parse import urlencode, quote, urljoin

qs = urlencode({"q": "hello world", "lang": "en"})
print(qs)  # q=hello+world&lang=en

path = "/docs/" + quote("C++ tips")
print(urljoin("https://example.com", path))
```

**parse query:**

```python
from urllib.parse import parse_qs, urlsplit

parts = urlsplit("https://x.test/search?q=a&q=b&page=2")
print(parse_qs(parts.query))  # {'q': ['a', 'b'], 'page': ['2']}
```

**Rebuild URL:**

```python
from urllib.parse import urlparse, urlunparse, urlencode

p = urlparse("https://api.example.com/v1/items")
query = urlencode({"limit": 10, "tag": "py"})
print(urlunparse(p._replace(query=query)))
```

## ⚠️ Pitfalls [#️-pitfalls]

* `quote` vs `quote_plus`: `+` for form bodies; `%20` often for paths.
* `parse_qs` returns **lists** of values — use `[0]` carefully.
* Don’t assemble URLs with raw f-strings for user input — encode first.
* `urljoin` replaces the path when the second arg starts with `/`.
* IPv6 / unusual URLs: prefer `urlsplit` and inspect `netloc` carefully.

## 🔗 Related [#-related]

* [Requests](/docs/python/requests-http)
* [Json](/docs/python/json)
* [Strings](/docs/python/strings)
* [Regex](/docs/python/regex)


# Variables (/docs/python/variables)



# Variables [#variables]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A variable is a name that refers to a value in memory. Python creates the binding when you assign with `=`. You do not declare types up front (though type hints are optional).

## 🔧 Core concepts [#-core-concepts]

| Idea           | Meaning                                         |
| -------------- | ----------------------------------------------- |
| Assignment     | `name = value` binds a name to an object        |
| Rebinding      | `name = other` points the name at a new object  |
| Dynamic typing | The same name can later hold a different type   |
| Naming         | Letters, digits, `_`; cannot start with a digit |
| Convention     | `snake_case` for variables and functions        |

Common built-in types beginners meet first: `int`, `float`, `str`, `bool`, `list`, `dict`, `None`.

## 💡 Examples [#-examples]

**Create and use variables:**

```python
age = 30
name = "Sam"
height_m = 1.75
is_student = True

print(name, age)
print(f"{name} is {age} years old")
```

**Rebind and swap:**

```python
x = 10
x = x + 5          # now 15
x += 1             # now 16

a, b = 1, 2
a, b = b, a        # swap
print(a, b)        # 2 1
```

**Multiple assignment and unpacking:**

```python
city, country = "Lisbon", "Portugal"
first, *rest = [10, 20, 30, 40]
print(first, rest)  # 10 [20, 30, 40]
```

**Names are references:**

```python
nums = [1, 2, 3]
alias = nums
alias.append(4)
print(nums)  # [1, 2, 3, 4] — same list object
```

## ⚠️ Pitfalls [#️-pitfalls]

* `=` is assignment; `==` is comparison.
* Using a name before assignment raises `NameError`.
* Mutable defaults and shared list/dict aliases surprise beginners.
* Avoid names that shadow builtins: `list`, `str`, `id`, `type`, `input`.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/python/hello-world)
* [comments.md](/docs/python/comments)
* [none\_and\_truthy.md](/docs/python/none-and-truthy)
* [scope\_namespaces.md](/docs/python/scope-namespaces)


# Venv (/docs/python/venv)



# Venv [#venv]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`venv` creates isolated Python environments so project dependencies do not clash with system packages. Always use a virtualenv per project; activate it before installing with pip.

## 🔧 Core concepts [#-core-concepts]

| Task               | Command                                     |
| ------------------ | ------------------------------------------- |
| Create             | `python -m venv .venv`                      |
| Activate (Windows) | `.venv\Scripts\activate`                    |
| Activate (Unix)    | `source .venv/bin/activate`                 |
| Deactivate         | `deactivate`                                |
| Install            | `python -m pip install -r requirements.txt` |
| Record             | `python -m pip freeze > requirements.txt`   |
| Remove             | Delete the `.venv` folder                   |

Prefer `python -m pip` so you install into the active interpreter. `.venv` is the common directory name (gitignored).

## 💡 Examples [#-examples]

**Create and use (PowerShell):**

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install requests pytest
```

**Create and use (bash):**

```shellscript
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -r requirements.txt
```

**Check which Python:**

```shellscript
python -c "import sys; print(sys.executable)"
where python   # Windows
which python   # Unix
```

**requirements pinning:**

```plaintext
# requirements.txt
requests==2.32.3
pytest>=8.0,<9
```

## ⚠️ Pitfalls [#️-pitfalls]

* Installing with a global `pip` while thinking the venv is active — verify `sys.executable`.
* Committing `.venv` to git bloats the repo — ignore it.
* Mixing conda and venv accidentally — pick one workflow.
* Nested venvs and path confusion after IDE interpreter switches.
* On Windows, execution policy may block `Activate.ps1` — adjust policy or use `cmd` activate.

## 🔗 Related [#-related]

* [Pip](/docs/python/pip)
* [Packaging](/docs/python/packaging)
* [Import / export](/docs/python/import-export)
* [Testing with pytest](/docs/python/testing-pytest)
* [Examples: cli tool](/docs/python/examples/cli-tool)
* [Argparse](/docs/python/argparse)


# Walrus Operator (/docs/python/walrus)



# Walrus Operator [#walrus-operator]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The walrus operator `:=` (PEP 572, 3.8+) assigns inside an expression. Use it to avoid double computation or awkward control-flow temporaries — sparingly, for clarity.

## 🔧 Core concepts [#-core-concepts]

| Form              | Meaning                                       |
| ----------------- | --------------------------------------------- |
| `name := expr`    | Assign and yield `expr`                       |
| In `if` / `while` | Bind then test                                |
| In comprehensions | Bind in filter/value                          |
| Scope             | Same rules as normal assignment in that block |

Cannot replace plain statement assignment everywhere; illegal in some syntactic positions (e.g. unparenthesized in some tuple contexts historically — prefer parentheses when unsure).

## 💡 Examples [#-examples]

**if / while:**

```python
from pathlib import Path

path = Path("data.txt")
if (text := path.read_text(encoding="utf-8")).strip():
    print(text[:20])

while (line := input("cmd> ")) != "quit":
    print("got", line)
```

**Reuse match result:**

```python
import re

pattern = re.compile(r"(\d+)")
if m := pattern.search("id=42"):
    print(int(m.group(1)))
```

**Comprehension:**

```python
def costly(x: int) -> int:
    return x * x

nums = [1, 2, 3, 4]
# compute once per item
big = [y for x in nums if (y := costly(x)) > 5]
print(big)  # [9, 16]
```

**Chunked read:**

```python
from pathlib import Path

with Path("blob.bin").open("rb") as f:
    while chunk := f.read(4096):
        print(len(chunk))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Overuse hurts readability — if the name is important, use a normal assignment.
* In comprehensions, the bound name's scope can surprise readers (leaks in some contexts historically; in 3.x comps have isolated scopes for `for` targets, but `:=` targets in the comprehension scope).
* Don't hide side effects inside walrus expressions.
* Not valid as a standalone replacement for all `=` uses.
* Combine carefully with `and`/`or` — parentheses help.

## 🔗 Related [#-related]

* [Conditionals](/docs/python/conditionals)
* [Loops](/docs/python/loops)
* [Comprehensions](/docs/python/comprehensions)
* [Files I/O](/docs/python/files-io)
* [Regex](/docs/python/regex)
* [Operators](/docs/python/operators)


# Zip, Enumerate, Map, Filter (/docs/python/zip-enumerate-map-filter)



# Zip, Enumerate, Map, Filter [#zip-enumerate-map-filter]

*Python · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`enumerate`, `zip`, `map`, and `filter` are built-in iteration helpers. Prefer `enumerate`/`zip` and comprehensions in idiomatic Python; `map`/`filter` shine with existing callables.

## 🔧 Core concepts [#-core-concepts]

| Built-in                  | Role                                |
| ------------------------- | ----------------------------------- |
| `enumerate(it, start=0)`  | Index + value pairs                 |
| `zip(*its, strict=False)` | Parallel iteration (3.10+ `strict`) |
| `map(fn, it, ...)`        | Apply fn lazily                     |
| `filter(pred, it)`        | Keep truthy pred                    |
| `reversed` / `sorted`     | Related helpers                     |

All return iterators (except `sorted` → list). Consume once unless recreated.

## 💡 Examples [#-examples]

**enumerate and zip:**

```python
names = ["ada", "bob", "cy"]
scores = [9, 7, 8]

for i, name in enumerate(names, start=1):
    print(i, name)

for name, score in zip(names, scores, strict=True):
    print(f"{name}: {score}")
```

**unzip:**

```python
pairs = [("a", 1), ("b", 2)]
letters, nums = zip(*pairs)
print(letters, nums)
```

**map / filter vs comps:**

```python
nums = [1, 2, 3, 4]
print(list(map(str, nums)))
print(list(filter(lambda n: n % 2 == 0, nums)))

# Prefer:
print([str(n) for n in nums])
print([n for n in nums if n % 2 == 0])
```

**dict from parallel lists:**

```python
keys = ["host", "port"]
vals = ["localhost", "8000"]
cfg = dict(zip(keys, vals, strict=True))
```

## ⚠️ Pitfalls [#️-pitfalls]

* `zip` stops at the shortest iterable unless `strict=True` (then errors on mismatch).
* `map`/`filter` are lazy — wrap `list()` for reuse/debug.
* `enumerate` on a dict iterates keys — use `.items()` when you need pairs.
* Star-unzip `zip(*xs)` fails on empty `xs`.
* Heavy `lambda` with map/filter is usually clearer as a comprehension.

## 🔗 Related [#-related]

* [Loops](/docs/python/loops)
* [Comprehensions](/docs/python/comprehensions)
* [Lambda](/docs/python/lambda)
* [Iterators](/docs/python/iterators)
* [Unpacking](/docs/python/unpacking)
* [Examples: list to dict](/docs/python/examples/list-to-dict)


# Accessibility (/docs/react-native/accesebility)



# Accessibility [#accessibility]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Make screens usable with VoiceOver / TalkBack via accessibility props on native views. Test with real screen readers; labels and roles matter more than visual-only cues.

## 🔧 Core concepts [#-core-concepts]

* **`accessible`** — groups children into one focusable element.
* **`accessibilityLabel` / `accessibilityHint`** — what is read aloud.
* **`accessibilityRole`** — `button`, `header`, `link`, `image`, `adjustable`, …
* **`accessibilityState`** — `\{ disabled, selected, checked, busy, expanded \}`.
* **`accessibilityActions` / `onAccessibilityAction`** — custom actions.

## 💡 Examples [#-examples]

```tsx
import { Pressable, Text } from "react-native";

export function IconButton({
  label,
  onPress,
}: {
  label: string;
  onPress: () => void;
}) {
  return (
    <Pressable
      onPress={onPress}
      accessibilityRole="button"
      accessibilityLabel={label}
      accessibilityHint="Double tap to activate"
    >
      <Text>★</Text>
    </Pressable>
  );
}
```

```tsx
<View
  accessible
  accessibilityRole="header"
  accessibilityLabel="Account settings"
>
  <Text>Settings</Text>
</View>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Icon-only buttons without `accessibilityLabel`.
* Nesting multiple `accessible` views that trap focus incorrectly.
* Relying on placeholder text as the only label for inputs — set explicit labels.

## 🔗 Related [#-related]

* [touchable.md](/docs/react-native/touchable) — press targets
* [basic\_primitives.md](/docs/react-native/basic-primitives) — Text / View
* [gesture.md](/docs/react-native/gesture) — gestures vs a11y
* [Expo/plugins.md](/docs/react-native/expo/plugins) — native config


# Activity Indicator (/docs/react-native/activity-indicator)



# Activity Indicator [#activity-indicator]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`ActivityIndicator` shows a platform-native spinner for loading states. Prefer it for indeterminate progress; use progress bars for determinate tasks. Size and color are the main knobs.

## 🔧 Core concepts [#-core-concepts]

| Prop               | Role                                  |
| ------------------ | ------------------------------------- |
| `animating`        | Show/hide animation                   |
| `size`             | `small` / `large` (number on Android) |
| `color`            | Spinner color                         |
| `hidesWhenStopped` | iOS hide when not animating           |

Place near the content that is loading; announce loading to a11y when blocking.

## 💡 Examples [#-examples]

```tsx
import { ActivityIndicator, View, StyleSheet, Text } from "react-native";

export function LoadingBlock({ label = "Loading" }: { label?: string }) {
  return (
    <View
      style={styles.wrap}
      accessibilityRole="progressbar"
      accessibilityLabel={label}
    >
      <ActivityIndicator size="large" color="#111" />
      <Text style={styles.label}>{label}</Text>
    </View>
  );
}

export function InlineBusy({ busy }: { busy: boolean }) {
  return busy ? <ActivityIndicator /> : null;
}

const styles = StyleSheet.create({
  wrap: { alignItems: "center", justifyContent: "center", padding: 24, gap: 12 },
  label: { color: "#444" },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Full-screen spinner with no escape for slow networks.
* Wrong contrast (`color` on similar background).
* Leaving `animating` true forever after errors.
* Using indicators instead of skeleton UI for large layout shifts.

## 🔗 Related [#-related]

* [refresh\_control.md](/docs/react-native/refresh-control) — pull to refresh
* [modal.md](/docs/react-native/modal) — blocking overlays
* [networking.md](/docs/react-native/networking) — request states
* [accesebility.md](/docs/react-native/accesebility) — announcements
* [styling.md](/docs/react-native/styling) — layout


# Alert (/docs/react-native/alert)



# Alert [#alert]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Alert.alert` shows a native system dialog with a title, message, and buttons. Use for confirmations and simple errors. For custom UI, use a modal—not Alert. On web/unsupported platforms behavior differs.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                                 |
| ------------------- | ------------------------------------ |
| `title` / `message` | Copy                                 |
| `buttons`           | `\{ text, onPress, style \}[]`       |
| `style`             | `default` / `cancel` / `destructive` |
| `Alert.prompt`      | iOS text prompt only                 |

Buttons dismiss the alert when pressed; keep handlers light.

## 💡 Examples [#-examples]

```tsx
import { Alert, Pressable, Text } from "react-native";

export function DeleteButton({ onConfirm }: { onConfirm: () => void }) {
  return (
    <Pressable
      onPress={() =>
        Alert.alert("Delete item?", "This cannot be undone.", [
          { text: "Cancel", style: "cancel" },
          { text: "Delete", style: "destructive", onPress: onConfirm },
        ])
      }
    >
      <Text>Delete</Text>
    </Pressable>
  );
}

function showError(err: Error) {
  Alert.alert("Something went wrong", err.message);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Relying on `Alert.prompt` on Android—not available.
* Stacking multiple alerts.
* Putting long forms inside Alert—use a screen/modal.
* Forgetting a cancel action on destructive flows.

## 🔗 Related [#-related]

* [modal.md](/docs/react-native/modal) — custom dialogs
* [pressable.md](/docs/react-native/pressable) — triggers
* [vibration.md](/docs/react-native/vibration) — haptic emphasis
* [accesebility.md](/docs/react-native/accesebility) — announcements
* [share.md](/docs/react-native/share) — system sheets


# Animation (/docs/react-native/animation)



# Animation [#animation]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Animate with the built-in `Animated` API, `LayoutAnimation`, or libraries like **Reanimated**. Prefer the UI thread (Reanimated / native driver) for smooth 60fps motion.

## 🔧 Core concepts [#-core-concepts]

* **`Animated.Value`** — drive opacity, transform, color interpolations.
* **`useNativeDriver: true`** — opacity/transform only; offloads to native.
* **`Animated.timing` / `spring` / `parallel` / `sequence`**.
* **Reanimated** — `useSharedValue`, `withTiming`, `useAnimatedStyle` for gestures + UI thread.
* **`LayoutAnimation`** — simple layout transitions (Android needs `UIManager` flag on older RN).

## 💡 Examples [#-examples]

```tsx
import { useRef, useEffect } from "react";
import { Animated, View } from "react-native";

export function FadeIn({ children }: { children: React.ReactNode }) {
  const opacity = useRef(new Animated.Value(0)).current;

  useEffect(() => {
    Animated.timing(opacity, {
      toValue: 1,
      duration: 300,
      useNativeDriver: true,
    }).start();
  }, [opacity]);

  return <Animated.View style={{ opacity }}>{children}</Animated.View>;
}
```

```tsx
import Animated, { useSharedValue, withSpring, useAnimatedStyle } from "react-native-reanimated";

export function Bounce() {
  const scale = useSharedValue(1);
  const style = useAnimatedStyle(() => ({ transform: [{ scale: scale.value }] }));
  return (
    <Animated.View
      style={style}
      onTouchEnd={() => {
        scale.value = withSpring(1.2);
      }}
    />
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `useNativeDriver: true` with `width`/`height`/`top` — not supported; use Reanimated or layout anims.
* Starting animations every render without deps.
* Fighting the navigator’s own transition configs.

## 🔗 Related [#-related]

* [transition.md](/docs/react-native/transition) — screen transitions
* [gesture.md](/docs/react-native/gesture) — gesture-driven motion
* [layout.md](/docs/react-native/layout) — layout props
* [touchable.md](/docs/react-native/touchable) — press feedback


# AppRegistry (/docs/react-native/appregistry)



# AppRegistry [#appregistry]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`AppRegistry` is the JS entry that registers the root component. The native host looks up the app key and runs that component. Expo / CLI templates wire this for you.

## 🔧 Core concepts [#-core-concepts]

* **`AppRegistry.registerComponent(appKey, () => Root)`** — required entry.
* **App key** — must match native (`AppDelegate` / `MainActivity` / `app.json` name).
* **`runApplication`** — used by the native side; rarely called from app code.
* **Expo** — `registerRootComponent` from `expo` wraps `AppRegistry`.

## 💡 Examples [#-examples]

```tsx
import { AppRegistry } from "react-native";
import App from "./App";
import { name as appName } from "./app.json";

AppRegistry.registerComponent(appName, () => App);
```

```tsx
// Expo
import { registerRootComponent } from "expo";
import App from "./App";

registerRootComponent(App);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mismatched app name between JS and native → blank screen / redbox.
* Registering twice with different roots in the same bundle.
* Forgetting the factory `() => App` (passing `App` directly is also accepted in modern RN, but factory is the classic pattern).

## 🔗 Related [#-related]

* [basic\_primitives.md](/docs/react-native/basic-primitives) — building UI
* [Expo/filestructure.md](/docs/react-native/expo/filestructure) — Expo entry
* [Expo/config.md](/docs/react-native/expo/config) — app name / slug
* [widget.md](/docs/react-native/widget) — alternate surfaces


# AppState (/docs/react-native/appstate)



# AppState [#appstate]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`AppState` reports whether the app is `active`, `background`, or (iOS) `inactive`. Subscribe to changes to pause video, sync data, or lock a secure screen when backgrounding.

## 🔧 Core concepts [#-core-concepts]

| State        | Meaning                       |
| ------------ | ----------------------------- |
| `active`     | Foreground, interactive       |
| `background` | Not visible                   |
| `inactive`   | iOS transition / multitasking |

APIs: `AppState.currentState`, `addEventListener('change', handler)`.

## 💡 Examples [#-examples]

```tsx
import { useEffect, useRef, useState } from "react";
import { AppState, Text } from "react-native";

export function useAppActive() {
  const [active, setActive] = useState(AppState.currentState === "active");
  useEffect(() => {
    const sub = AppState.addEventListener("change", (next) => {
      setActive(next === "active");
    });
    return () => sub.remove();
  }, []);
  return active;
}

export function SecureGate({ children }: { children: React.ReactNode }) {
  const appState = useRef(AppState.currentState);
  const [locked, setLocked] = useState(false);

  useEffect(() => {
    const sub = AppState.addEventListener("change", (next) => {
      if (
        appState.current === "active" &&
        next.match(/inactive|background/)
      ) {
        setLocked(true);
      }
      appState.current = next;
    });
    return () => sub.remove();
  }, []);

  if (locked) return <Text>Unlock to continue</Text>;
  return <>{children}</>;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Doing heavy work on every blur without debounce.
* Forgetting to remove the subscription.
* Assuming `inactive` exists on Android the same way.
* Polling instead of listening.

## 🔗 Related [#-related]

* [biometrics.md](/docs/react-native/biometrics) — unlock
* [player.md](/docs/react-native/player) — pause media
* [notification.md](/docs/react-native/notification) — background
* [storage.md](/docs/react-native/storage) — persist on blur
* [navigation.md](/docs/react-native/navigation) — blur events


# BackHandler (/docs/react-native/backhandler)



# BackHandler [#backhandler]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`BackHandler` listens for the Android hardware back button (and some back gestures). iOS has no system back button — use navigation stack gestures instead.

## 🔧 Core concepts [#-core-concepts]

* **`BackHandler.addEventListener("hardwareBackPress", handler)`**.
* **Return `true`*&#x2A; — you handled it; &#x2A;*`false`** — let default (exit / pop) proceed.
* **Cleanup** — remove the subscription in effect cleanup.
* **React Navigation** — prefer `beforeRemove` / stack options over raw BackHandler when using a navigator.

## 💡 Examples [#-examples]

```tsx
import { useEffect } from "react";
import { BackHandler, Alert } from "react-native";

export function useConfirmExit(enabled: boolean) {
  useEffect(() => {
    if (!enabled) return;
    const sub = BackHandler.addEventListener("hardwareBackPress", () => {
      Alert.alert("Exit?", "Leave the screen?", [
        { text: "Cancel", style: "cancel" },
        { text: "Exit", onPress: () => BackHandler.exitApp() },
      ]);
      return true;
    });
    return () => sub.remove();
  }, [enabled]);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Stacking multiple listeners without cleanup → unpredictable back behavior.
* Handling back on iOS unnecessarily — no-op or wrong UX.
* Calling `exitApp()` casually — poor UX; prefer navigating away.

## 🔗 Related [#-related]

* [deeplinking.md](/docs/react-native/deeplinking) — navigation entry
* [drawer.md](/docs/react-native/drawer) — drawer back behavior
* [modal.md](/docs/react-native/modal) — dismiss on back
* [gesture.md](/docs/react-native/gesture) — gesture navigation


# Basic primitives (/docs/react-native/basic-primitives)



# Basic primitives [#basic-primitives]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Core building blocks: `View`, `Text`, `Image`, `ScrollView`, `TextInput`, `Pressable`, `FlatList`. There is no HTML — style with the `StyleSheet` API (Flexbox by default).

## 🔧 Core concepts [#-core-concepts]

* **`View`** — container (like `div`); flex layout.
* **`Text`** — all strings must be inside `Text`.
* **`Image` / `ImageBackground`** — local `require` or remote `\{ uri \}`.
* **`ScrollView` vs `FlatList`** — lists of unknown length → `FlatList` / `SectionList`.
* **`StyleSheet.create`** — validated style objects; density-independent units.

## 💡 Examples [#-examples]

```tsx
import {
  View,
  Text,
  Image,
  StyleSheet,
  FlatList,
  Pressable,
} from "react-native";

const styles = StyleSheet.create({
  row: { flexDirection: "row", alignItems: "center", gap: 12, padding: 16 },
  title: { fontSize: 18, fontWeight: "600" },
  avatar: { width: 40, height: 40, borderRadius: 20 },
});

export function UserRow({
  name,
  uri,
  onPress,
}: {
  name: string;
  uri: string;
  onPress: () => void;
}) {
  return (
    <Pressable onPress={onPress} style={styles.row}>
      <Image source={{ uri }} style={styles.avatar} />
      <Text style={styles.title}>{name}</Text>
    </Pressable>
  );
}
```

```tsx
<FlatList
  data={users}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <UserRow {...item} onPress={() => {}} />}
/>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Raw text outside `<Text>` crashes.
* Nesting `VirtualizedList` inside `ScrollView` without care → warnings / perf issues.
* Inline styles everywhere — harder to reuse; prefer `StyleSheet`.

## 🔗 Related [#-related]

* [layout.md](/docs/react-native/layout) — flex layout
* [touchable.md](/docs/react-native/touchable) — press handling
* [accesebility.md](/docs/react-native/accesebility) — a11y props
* [animation.md](/docs/react-native/animation) — animated views


# Biometrics (/docs/react-native/biometrics)



# Biometrics [#biometrics]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Biometric auth (Face ID, Touch ID, fingerprint) unlocks local secrets or confirms sensitive actions. Expo: &#x2A;*`expo-local-authentication`**. Bare: `react-native-biometrics` / Keychain integration. Always provide a device passcode fallback.

## 🔧 Core concepts [#-core-concepts]

| API                                 | Role                                           |
| ----------------------------------- | ---------------------------------------------- |
| `hasHardwareAsync`                  | Sensor present                                 |
| `isEnrolledAsync`                   | User enrolled biometrics                       |
| `supportedAuthenticationTypesAsync` | Face / fingerprint                             |
| `authenticateAsync`                 | Prompt                                         |
| Secure storage                      | Store tokens in Keychain/Keystore after unlock |

OS policy controls rate limits and lockouts.

## 💡 Examples [#-examples]

```tsx
import * as LocalAuthentication from "expo-local-authentication";
import { Alert, Pressable, Text } from "react-native";

export function UnlockButton({ onUnlocked }: { onUnlocked: () => void }) {
  return (
    <Pressable
      onPress={async () => {
        const hasHardware = await LocalAuthentication.hasHardwareAsync();
        const enrolled = await LocalAuthentication.isEnrolledAsync();
        if (!hasHardware || !enrolled) {
          Alert.alert("Biometrics unavailable", "Use your passcode instead.");
          return;
        }
        const result = await LocalAuthentication.authenticateAsync({
          promptMessage: "Unlock",
          fallbackLabel: "Use passcode",
          disableDeviceFallback: false,
        });
        if (result.success) onUnlocked();
      }}
    >
      <Text>Unlock with biometrics</Text>
    </Pressable>
  );
}
```

**Info.plist / Android:** Face ID usage string; no special permission for basic LocalAuthentication on modern Expo.

## ⚠️ Pitfalls [#️-pitfalls]

* Treating biometrics as server authentication—it's local presence only.
* Storing session tokens in AsyncStorage instead of secure storage.
* No fallback when enrollment is missing.
* Re-prompting in a tight loop after cancel.

## 🔗 Related [#-related]

* [Expo secure\_store](/docs/react-native/expo/secure-store) — Keychain
* [appstate.md](/docs/react-native/appstate) — lock on background
* [storage.md](/docs/react-native/storage) — insecure vs secure
* [permissions.md](/docs/react-native/permissions) — related prompts
* [alert.md](/docs/react-native/alert) — fallback UX


# Blur (/docs/react-native/blur)



# Blur [#blur]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Blurred glass effects use platform views: Expo `@react-native-community/blur&#x60; alternatives or &#x2A;*`expo-blur`** (`BlurView`). Common for headers, tab bars, and modal scrims. Performance varies—avoid huge animated blurs on low-end Android.

## 🔧 Core concepts [#-core-concepts]

| Piece       | Role                                     |
| ----------- | ---------------------------------------- |
| `BlurView`  | Blurs content behind the view            |
| `intensity` | Blur strength (Expo)                     |
| `tint`      | light / dark / default                   |
| Fallback    | Solid translucent color when unsupported |

Blur only affects views **behind** it in the native hierarchy—not React siblings painted later without proper ordering.

## 💡 Examples [#-examples]

```tsx
import { BlurView } from "expo-blur";
import { StyleSheet, Text, View } from "react-native";

export function FrostedHeader({ title }: { title: string }) {
  return (
    <View style={styles.wrap}>
      <BlurView intensity={60} tint="light" style={StyleSheet.absoluteFill} />
      <Text style={styles.title}>{title}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  wrap: {
    height: 56,
    justifyContent: "center",
    paddingHorizontal: 16,
    overflow: "hidden",
  },
  title: { fontSize: 17, fontWeight: "600" },
});
```

**Config plugin (Expo):** ensure `expo-blur` is installed; prebuild if needed.

## ⚠️ Pitfalls [#️-pitfalls]

* Expecting BlurView to blur its own children—it blurs what’s behind.
* Heavy blur + frequent re-renders → jank on Android.
* Missing fallback UI on web/unsupported targets.
* Stacking multiple full-screen blurs.

## 🔗 Related [#-related]

* [styling.md](/docs/react-native/styling) — translucent UI
* [modal.md](/docs/react-native/modal) — overlays
* [navigation.md](/docs/react-native/navigation) — translucent headers
* [Expo config](/docs/react-native/expo/config) — plugins
* [animation.md](/docs/react-native/animation) — animated opacity


# Camera (/docs/react-native/camera)



# Camera [#camera]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Camera access uses &#x2A;*`expo-camera`** (Expo) or `react-native-vision-camera` (bare/advanced). Request permission before preview; handle denied states. For still photos only, `expo-image-picker` may be enough.

## 🔧 Core concepts [#-core-concepts]

| Topic      | Notes                                |
| ---------- | ------------------------------------ |
| Permission | Camera (and mic for video)           |
| Preview    | `<CameraView>` / VisionCamera        |
| Capture    | `takePictureAsync` / photo callbacks |
| Facing     | front / back                         |
| Barcode    | Optional scanners                    |

Background: pause camera when screen blurs (`useIsFocused`).

## 💡 Examples [#-examples]

```tsx
import { useState, useRef, useEffect } from "react";
import { View, Pressable, Text, StyleSheet } from "react-native";
import { CameraView, useCameraPermissions } from "expo-camera";

export function CameraScreen() {
  const [permission, requestPermission] = useCameraPermissions();
  const ref = useRef<CameraView>(null);
  const [facing, setFacing] = useState<"back" | "front">("back");

  if (!permission) return <View />;
  if (!permission.granted) {
    return (
      <Pressable onPress={requestPermission}>
        <Text>Grant camera access</Text>
      </Pressable>
    );
  }

  return (
    <View style={styles.flex}>
      <CameraView ref={ref} style={styles.flex} facing={facing} />
      <Pressable
        style={styles.btn}
        onPress={async () => {
          const photo = await ref.current?.takePictureAsync();
          console.log(photo?.uri);
        }}
      >
        <Text>Capture</Text>
      </Pressable>
      <Pressable
        onPress={() => setFacing((f) => (f === "back" ? "front" : "back"))}
      >
        <Text>Flip</Text>
      </Pressable>
    </View>
  );
}

const styles = StyleSheet.create({
  flex: { flex: 1 },
  btn: { padding: 16, backgroundColor: "#fff" },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Starting camera without permission UX.
* Leaving camera running on blurred tabs—battery/heat.
* Ignoring simulator limitations (no camera).
* Storing captures without compression / cleanup.

## 🔗 Related [#-related]

* [permissions.md](/docs/react-native/permissions) — runtime perms
* [Expo image\_picker](/docs/react-native/expo/image-picker) — gallery/camera stills
* [image.md](/docs/react-native/image) — display
* [navigation.md](/docs/react-native/navigation) — focus cleanup
* [appstate.md](/docs/react-native/appstate) — background


# Clipboard (/docs/react-native/clipboard)



# Clipboard [#clipboard]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Read and write the system clipboard. In modern RN / Expo, use `@react-native-clipboard/clipboard` or `expo-clipboard` — the core `Clipboard` API was removed from the RN core package.

## 🔧 Core concepts [#-core-concepts]

* **`setString(text)`** — copy to clipboard.
* **`getString()`** — async read (may need permission prompts on some platforms).
* **Expo** — `import * as Clipboard from "expo-clipboard"`.
* **Security** — don’t log clipboard contents; treat as sensitive.

## 💡 Examples [#-examples]

```tsx
import * as Clipboard from "expo-clipboard";
import { Pressable, Text, Alert } from "react-native";

export function CopyButton({ value }: { value: string }) {
  async function copy() {
    await Clipboard.setStringAsync(value);
    Alert.alert("Copied");
  }
  return (
    <Pressable onPress={copy} accessibilityRole="button" accessibilityLabel="Copy">
      <Text>Copy</Text>
    </Pressable>
  );
}
```

```tsx
import Clipboard from "@react-native-clipboard/clipboard";

async function paste() {
  const text = await Clipboard.getString();
  return text;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using deprecated `react-native` Clipboard import.
* Expecting sync `getString` — it’s async.
* Copying secrets into clipboard without user intent.

## 🔗 Related [#-related]

* [share.md](/docs/react-native/share) — system share sheet
* [storage.md](/docs/react-native/storage) — persistent storage
* [permissions.md](/docs/react-native/permissions) — platform permissions
* [Expo/plugins.md](/docs/react-native/expo/plugins) — Expo modules


# Deep linking (/docs/react-native/deep-linking)



# Deep linking [#deep-linking]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Deep links open a specific screen from a URL (`myapp://profile/42` or `https://…`). Use React Navigation linking config or Expo Router path maps.

## 🔧 Core concepts [#-core-concepts]

| Piece             | Role                                        |
| ----------------- | ------------------------------------------- |
| Scheme            | Custom URL scheme / universal links         |
| Linking API       | `Linking.getInitialURL`, `addEventListener` |
| Navigation config | Map path prefixes → screens                 |
| Expo Router       | File-based routes = URLs                    |

## 💡 Examples [#-examples]

```tsx
import * as Linking from 'expo-linking';

const url = Linking.createURL('profile/42');
// e.g. myapp://profile/42
```

```tsx
import { Linking } from 'react-native';

Linking.addEventListener('url', ({ url }) => {
  // navigate from url
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Test cold start (`getInitialURL`) and warm start (event) separately.
* Universal links need platform domain association files.
* Encode path params consistently.

## 🔗 Related [#-related]

* [launcher\_shortcut\_menu](/docs/react-native/launcher-shortcut-menu)
* [notifications](/docs/react-native/notifications)
* [getting\_started](/docs/react-native/getting-started)


# Deep linking (/docs/react-native/deeplinking)



# Deep linking [#deep-linking]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Deep links open a specific screen from a URL (`myapp://path`, HTTPS universal / app links). Configure native intent filters / associated domains, then map URLs in your navigator.

## 🔧 Core concepts [#-core-concepts]

* **Schemes** — custom (`myapp://`) vs HTTPS app links / universal links.
* **React Navigation** — `linking` config: `prefixes` + `config.screens`.
* **Expo** — `scheme` in `app.json` / `app.config`; `expo-linking`, `npx uri-scheme`.
* **Cold start** — read initial URL; also subscribe to URL events while running.

## 💡 Examples [#-examples]

```tsx
import { NavigationContainer } from "@react-navigation/native";

const linking = {
  prefixes: ["myapp://", "https://myapp.example.com"],
  config: {
    screens: {
      Home: "home",
      User: "users/:id",
    },
  },
};

export function RootNav() {
  return (
    <NavigationContainer linking={linking}>
      {/* navigators */}
    </NavigationContainer>
  );
}
```

```tsx
import * as Linking from "expo-linking";

const url = Linking.createURL("users/42");
// e.g. myapp://users/42
```

## ⚠️ Pitfalls [#️-pitfalls]

* Native config missing → links open browser or do nothing.
* Mismatched path params vs screen names.
* Not handling the case when the app is already open (`url` event).

## 🔗 Related [#-related]

* [Expo/config.md](/docs/react-native/expo/config) — scheme config
* [backhandler.md](/docs/react-native/backhandler) — Android back
* [notification.md](/docs/react-native/notification) — notification deep links
* [request.md](/docs/react-native/request) — API after open


# Dimensions (/docs/react-native/dimensions)



# Dimensions [#dimensions]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Dimensions` and `useWindowDimensions` report screen/window size for responsive layouts. Prefer the hook so rotations and split-screen updates re-render.

## 🔧 Core concepts [#-core-concepts]

* **`useWindowDimensions()`** — `\{ width, height, scale, fontScale \}` (recommended).
* **`Dimensions.get("window" | "screen")`** — snapshot; subscribe manually if needed.
* **Safe areas** — use `react-native-safe-area-context`, not raw status bar math alone.
* **PixelRatio** — `PixelRatio.roundToNearestPixel`, font scaling awareness.

## 💡 Examples [#-examples]

```tsx
import { useWindowDimensions, View, Text } from "react-native";

export function Responsive() {
  const { width } = useWindowDimensions();
  const columns = width >= 768 ? 2 : 1;
  return (
    <View style={{ flexDirection: columns === 2 ? "row" : "column" }}>
      <Text>Columns: {columns}</Text>
    </View>
  );
}
```

```tsx
import { Dimensions } from "react-native";

const { width } = Dimensions.get("window");
```

## ⚠️ Pitfalls [#️-pitfalls]

* Caching `Dimensions.get` at module load — stale after rotate.
* Ignoring `fontScale` → clipped text for a11y users.
* Using screen size instead of window on Android with system bars / foldables.

## 🔗 Related [#-related]

* [layout.md](/docs/react-native/layout) — flex layouts
* [statusbar.md](/docs/react-native/statusbar) — insets / bars
* [platform\_specific.md](/docs/react-native/platform-specific) — platform splits
* [basic\_primitives.md](/docs/react-native/basic-primitives) — View sizing


# Drawer (/docs/react-native/drawer)



# Drawer [#drawer]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Drawers are side navigation panels. Use `@react-navigation/drawer` (or a custom `Animated`/`Reanimated` panel). Gesture + back-button behavior should match platform norms.

## 🔧 Core concepts [#-core-concepts]

* **Drawer navigator** — screens as drawer destinations; `drawerContent` for custom UI.
* **Options** — `drawerPosition`, `swipeEnabled`, `headerShown`.
* **Nesting** — often wrap a stack inside each drawer screen.
* **Custom** — modal-like overlay with translateX animation if you don’t need a full navigator.

## 💡 Examples [#-examples]

```tsx
import { createDrawerNavigator } from "@react-navigation/drawer";

const Drawer = createDrawerNavigator();

export function AppDrawer() {
  return (
    <Drawer.Navigator initialRouteName="Home">
      <Drawer.Screen name="Home" component={HomeScreen} />
      <Drawer.Screen name="Settings" component={SettingsScreen} />
    </Drawer.Navigator>
  );
}
```

```tsx
<Drawer.Navigator
  screenOptions={{
    drawerType: "front",
    swipeEdgeWidth: 40,
  }}
  drawerContent={(props) => <CustomDrawer {...props} />}
/>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Conflicting gestures with tabs/stacks — tune `swipeEnabled` per screen.
* Forgetting Android back should close an open drawer first.
* Heavy drawer content re-rendering on every navigation event.

## 🔗 Related [#-related]

* [gesture.md](/docs/react-native/gesture) — swipe gestures
* [backhandler.md](/docs/react-native/backhandler) — Android back
* [transition.md](/docs/react-native/transition) — motion
* [layout.md](/docs/react-native/layout) — screen layout


# FlatList (/docs/react-native/flatlist)



# FlatList [#flatlist]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`FlatList` efficiently renders long scrolling lists by virtualizing off-screen rows. Provide `data`, `renderItem`, and a stable `keyExtractor`. For sectioned data use `SectionList`; for very large lists consider FlashList.

## 🔧 Core concepts [#-core-concepts]

| Prop                                | Role                         |
| ----------------------------------- | ---------------------------- |
| `data`                              | Array of items               |
| `renderItem`                        | Row renderer                 |
| `keyExtractor`                      | Stable keys                  |
| `ItemSeparatorComponent`            | Dividers                     |
| `ListHeaderComponent` / `Footer`    | Chrome                       |
| `onEndReached`                      | Infinite scroll              |
| `refreshing` / `onRefresh`          | Pull to refresh              |
| `getItemLayout`                     | Skip measure if fixed height |
| `windowSize` / `initialNumToRender` | Tuning                       |

Avoid anonymous inline components that remount every parent render—extract `Row`.

## 💡 Examples [#-examples]

```tsx
import { FlatList, Text, View, StyleSheet } from "react-native";

type Item = { id: string; title: string };

export function Feed({ items }: { items: Item[] }) {
  return (
    <FlatList
      data={items}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View style={styles.row}>
          <Text>{item.title}</Text>
        </View>
      )}
      ItemSeparatorComponent={() => <View style={styles.sep} />}
      onEndReachedThreshold={0.4}
      onEndReached={() => {
        /* load more */
      }}
    />
  );
}

const styles = StyleSheet.create({
  row: { padding: 16 },
  sep: { height: 1, backgroundColor: "#eee" },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using `ScrollView` + `.map` for huge lists.
* Inline `renderItem=\{() => ...\}` creating new types + unstable handlers without care.
* Missing keys / using index when reordering.
* Nesting VirtualizedLists (FlatList inside ScrollView) without care.
* Heavy rows—memoize row components.

## 🔗 Related [#-related]

* [sectionlist.md](/docs/react-native/sectionlist) — sections
* [scrollview.md](/docs/react-native/scrollview) — non-virtualized
* [refresh\_control.md](/docs/react-native/refresh-control) — pull to refresh
* [performance](/docs/react-native/../react/performance) — list perf
* [keys\_lists](/docs/react-native/../react/keys-lists) — identity


# Gesture (/docs/react-native/gesture)



# Gesture [#gesture]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Handle touches beyond simple presses with **React Native Gesture Handler** + **Reanimated**. Prefer RNGH over the old PanResponder for modern apps.

## 🔧 Core concepts [#-core-concepts]

* **`GestureDetector` + `Gesture`** — tap, pan, pinch, long press, race/simultaneous.
* **Root** — wrap app in `GestureHandlerRootView`.
* **Pressable / Touchable** — from `react-native-gesture-handler` inside navigators.
* **Native driver / UI thread** — update shared values in gesture callbacks.

## 💡 Examples [#-examples]

```tsx
import { Gesture, GestureDetector, GestureHandlerRootView } from "react-native-gesture-handler";
import Animated, { useSharedValue, useAnimatedStyle } from "react-native-reanimated";

export function Draggable() {
  const x = useSharedValue(0);
  const y = useSharedValue(0);
  const pan = Gesture.Pan().onChange((e) => {
    x.value += e.changeX;
    y.value += e.changeY;
  });
  const style = useAnimatedStyle(() => ({
    transform: [{ translateX: x.value }, { translateY: y.value }],
  }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[{ width: 80, height: 80, backgroundColor: "#333" }, style]} />
    </GestureDetector>
  );
}

export function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Draggable />
    </GestureHandlerRootView>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `GestureHandlerRootView` → gestures silently fail.
* Mixing RN `Touchable*` inside RNGH navigators without RNGH replacements.
* Gesture fights with `ScrollView` — use `simultaneousWithExternalGesture` / `native` gesture carefully.

## 🔗 Related [#-related]

* [touchable.md](/docs/react-native/touchable) — simple presses
* [animation.md](/docs/react-native/animation) — animated values
* [drawer.md](/docs/react-native/drawer) — drawer swipes
* [transition.md](/docs/react-native/transition) — interactive transitions


# Getting Started with React Native (/docs/react-native/getting-started)



# Getting Started with React Native [#getting-started-with-react-native]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

React Native (RN) lets you build mobile apps with React. Instead of HTML tags (`div`, `p`), you use native components (`View`, `Text`). One codebase can target iOS and Android (and web via React Native for Web).

## 🔧 Core concepts [#-core-concepts]

| Idea              | Meaning                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| Native components | `View`, `Text`, `Image`, `Pressable`, …                                |
| StyleSheet        | JS objects for styling (Flexbox by default)                            |
| Metro / Expo      | Bundlers & tooling for RN apps                                         |
| Expo              | Beginner-friendly way to start without Xcode/Android Studio on day one |
| Platform APIs     | Camera, haptics, linking, etc. via modules                             |

**Recommended start:** Expo (`npx create-expo-app`).

## 💡 Examples [#-examples]

**Create an Expo app:**

```shellscript
npx create-expo-app@latest MyApp
cd MyApp
npx expo start
```

**Core imports:**

```jsx
import { View, Text, StyleSheet } from "react-native";

export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Hello, React Native</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center",
  },
  title: { fontSize: 22 },
});
```

**Platform check:**

```jsx
import { Platform, Text } from "react-native";

<Text>Running on {Platform.OS}</Text>;
```

## ⚠️ Pitfalls [#️-pitfalls]

* There is no DOM — `document` / `div` / CSS files don’t apply the same way.
* All text must be inside `<Text>` — raw strings in `<View>` error.
* Flexbox defaults differ slightly from web (`flexDirection: "column"` by default).
* Testing on a real device needs the Expo Go app or a dev build.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/react-native/hello-world)
* [reactnativeforweb.md](/docs/react-native/reactnativeforweb)
* [styling.md](/docs/react-native/styling)
* [pressable.md](/docs/react-native/pressable)


# Glossary (/docs/react-native/glossary)



# Glossary [#glossary]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core React Native terms for components, navigation, native modules, and mobile UI patterns.

## 🔧 Core concepts [#-core-concepts]

| Term              | Definition                                                                      |
| ----------------- | ------------------------------------------------------------------------------- |
| ActivityIndicator | A built-in spinner component for indeterminate loading states.                  |
| AppRegistry       | The JS entry that registers the root component with the native runtime.         |
| AppState          | An API reporting whether the app is active, background, or inactive.            |
| Bridge            | The legacy message channel between JavaScript and native modules.               |
| Dimensions        | An API that reads window or screen width and height.                            |
| Expo              | A toolchain and SDK that simplifies React Native development and builds.        |
| FlatList          | A performant scrolling list that virtualizes large data sets.                   |
| Flexbox           | The default layout system used by React Native styles.                          |
| Gesture           | Touch interaction handling, often via Gesture Handler or Pressable.             |
| Hermes            | A JavaScript engine optimized for React Native startup and memory.              |
| Linking           | An API for opening URLs and handling deep links into the app.                   |
| Metro             | The JavaScript bundler commonly used by React Native projects.                  |
| Modal             | A component that presents content above the current screen.                     |
| Native module     | Platform code (Swift/Kotlin/etc.) exposed to JavaScript.                        |
| Navigation        | Moving between screens, typically via React Navigation stacks/tabs.             |
| New Architecture  | Fabric renderer and TurboModules replacing the legacy bridge path.              |
| Platform          | Helpers to branch behavior for iOS, Android, or web.                            |
| Pressable         | A core component for detecting presses with fine-grained feedback.              |
| SafeAreaView      | A view that insets content away from notches and system UI.                     |
| ScrollView        | A scrollable container for content that fits reasonably in memory.              |
| SectionList       | A virtualized list organized into titled sections.                              |
| StatusBar         | Control over the system status bar style and visibility.                        |
| StyleSheet        | An API that creates optimized style objects for components.                     |
| TextInput         | A core editable text field component.                                           |
| Touchable         | Legacy press wrappers (`TouchableOpacity`, etc.) largely replaced by Pressable. |
| View              | The fundamental container component, analogous to a `div` on web.               |
| Yoga              | The cross-platform layout engine implementing Flexbox for native views.         |

## 💡 Examples [#-examples]

**View, Text, and StyleSheet:**

```tsx
import { StyleSheet, Text, View } from "react-native";

const styles = StyleSheet.create({
  box: { padding: 16, flex: 1 },
  title: { fontSize: 18, fontWeight: "600" },
});

export function Card() {
  return (
    <View style={styles.box}>
      <Text style={styles.title}>Hello</Text>
    </View>
  );
}
```

**FlatList:**

```tsx
<FlatList
  data={users}
  keyExtractor={(item) => item.id}
  renderItem={({ item }) => <Text>{item.name}</Text>}
/>
```

**AppState:**

```tsx
useEffect(() => {
  const sub = AppState.addEventListener("change", (next) => {
    console.log(next);
  });
  return () => sub.remove();
}, []);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **ScrollView** (simple, all-in-memory) with **FlatList** (virtualized).
* Mixing web **CSS** assumptions with React Native **StyleSheet** — many properties differ.
* Treating **Touchable**\* and **Pressable** as identical — Pressable is the modern API.
* Assuming **Linking** alone equals full **navigation** — deep links still need a navigator.
* Equating **Expo** managed workflow with bare React Native — tooling and native access differ.

## 🔗 Related [#-related]

* [basic\_primitives](/docs/react-native/basic-primitives)
* [flatlist](/docs/react-native/flatlist)
* [navigation](/docs/react-native/navigation)
* [styling](/docs/react-native/styling)
* [appstate](/docs/react-native/appstate)
* [safe\_area](/docs/react-native/safe-area)


# Haptics (/docs/react-native/haptics)



# Haptics [#haptics]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Haptics provide nuanced tactile feedback (impact, notification, selection). In Expo use `expo-haptics`; in bare RN use platform modules or community packages. Prefer haptics over crude `Vibration` for UI polish—especially iOS.

## 🔧 Core concepts [#-core-concepts]

| Type         | When                      |
| ------------ | ------------------------- |
| Impact       | Light/medium/heavy taps   |
| Notification | Success / warning / error |
| Selection    | Picker ticks, toggles     |

Always no-op gracefully on unsupported hardware/simulators.

## 💡 Examples [#-examples]

```tsx
import * as Haptics from "expo-haptics";
import { Pressable, Text } from "react-native";

export function LikeButton({ onLike }: { onLike: () => void }) {
  return (
    <Pressable
      onPress={async () => {
        await Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium);
        onLike();
      }}
    >
      <Text>Like</Text>
    </Pressable>
  );
}

export async function notifySuccess() {
  await Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
}

export async function tick() {
  await Haptics.selectionAsync();
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Firing haptics on every scroll event—too noisy.
* Ignoring “Reduce Motion” / haptic disable preferences when available.
* Blocking UI on awaited haptics unnecessarily—fire-and-forget is fine.
* Assuming Android parity with iOS Taptic Engine.

## 🔗 Related [#-related]

* [vibration.md](/docs/react-native/vibration) — basic vibrate
* [pressable.md](/docs/react-native/pressable) — buttons
* [picker.md](/docs/react-native/picker) — selection ticks
* [gesture.md](/docs/react-native/gesture) — gesture feedback
* [touchable.md](/docs/react-native/touchable) — press handling


# Hello World (/docs/react-native/hello-world)



# Hello World [#hello-world]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

React Native Hello World shows text on a screen using `View` + `Text`. With Expo, you scan a QR code (Expo Go) or use an emulator to see the result live.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                              |
| ------------------- | --------------------------------- |
| `App` / screen      | Root component Expo loads         |
| `View`              | Container (like a non-text `div`) |
| `Text`              | Renders strings                   |
| `StyleSheet.create` | Defines reusable styles           |
| Fast Refresh        | Saves reload UI as you edit       |

Keep the first screen tiny so tooling issues are obvious.

## 💡 Examples [#-examples]

**Minimal screen:**

```jsx
import { View, Text, StyleSheet } from "react-native";

export default function App() {
  return (
    <View style={styles.container}>
      <Text>Hello, World!</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
});
```

**Styled greeting:**

```jsx
import { View, Text, StyleSheet } from "react-native";

export default function App() {
  const name = "Ada";
  return (
    <View style={styles.container}>
      <Text style={styles.hello}>Hello, {name}!</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: "center", alignItems: "center" },
  hello: { fontSize: 24, fontWeight: "600" },
});
```

**Pressable interaction:**

```jsx
import { useState } from "react";
import { Pressable, Text, View } from "react-native";

export default function App() {
  const [n, setN] = useState(0);
  return (
    <View style={{ flex: 1, justifyContent: "center", alignItems: "center" }}>
      <Pressable onPress={() => setN(n + 1)}>
        <Text>Hello taps: {n}</Text>
      </Pressable>
    </View>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Putting text directly in `View` without `Text` throws.
* Web CSS class names don’t apply — use style objects.
* Safe area / notches: later use `SafeAreaView` or safe-area libraries.
* If the bundle fails, read the Metro/Expo terminal error first.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/react-native/getting-started)
* [reactnativeforweb.md](/docs/react-native/reactnativeforweb)
* [styling.md](/docs/react-native/styling)
* [pressable.md](/docs/react-native/pressable)


# Image (/docs/react-native/image)



# Image [#image]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Image` displays local `require` assets or remote `\{ uri \}` sources. Set dimensions (or use `style` width/height); remote images need explicit size. Prefer `expo-image` for caching, blurhash, and better performance in Expo apps.

## 🔧 Core concepts [#-core-concepts]

| Topic         | Notes                                         |
| ------------- | --------------------------------------------- |
| Local         | `source=\{require("./pic.png")\}`             |
| Remote        | `source=\{\{ uri, headers? \}\}`              |
| Resize        | `resizeMode`: cover, contain, stretch, center |
| Events        | `onLoad`, `onError`                           |
| Prefetch      | `Image.prefetch(url)`                         |
| Accessibility | `accessibilityLabel` for meaningful images    |

Network security: HTTPS; ATS / cleartext rules on iOS/Android.

## 💡 Examples [#-examples]

```tsx
import { Image, StyleSheet, View } from "react-native";

export function Avatar({ url }: { url: string }) {
  return (
    <Image
      source={{ uri: url }}
      style={styles.avatar}
      resizeMode="cover"
      accessibilityLabel="Profile photo"
      onError={() => {
        /* fallback */
      }}
    />
  );
}

export function Logo() {
  return (
    <View>
      <Image source={require("../assets/logo.png")} style={styles.logo} />
    </View>
  );
}

const styles = StyleSheet.create({
  avatar: { width: 64, height: 64, borderRadius: 32 },
  logo: { width: 120, height: 40 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Remote images without width/height → layout 0.
* Huge unoptimized assets in the bundle.
* Missing cache strategy for lists of remote images.
* Decorative images announced to VoiceOver—set `accessible=\{false\}` when appropriate.

## 🔗 Related [#-related]

* [styling.md](/docs/react-native/styling) — layout
* [Expo image\_picker](/docs/react-native/expo/image-picker) — picking
* [networking.md](/docs/react-native/networking) — remote assets
* [basic\_primitives.md](/docs/react-native/basic-primitives) — View/Text
* [permissions.md](/docs/react-native/permissions) — media library


# React Native (/docs/react-native)



# React Native [#react-native]

Mobile UI, APIs, Expo.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)
* [Expo](./expo)


# Keyboard (/docs/react-native/keyboard)



# Keyboard [#keyboard]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Manage soft keyboard visibility, dismissals, and layout shifts with `Keyboard`, `KeyboardAvoidingView`, and community libs like `keyboard-controller` / `react-native-keyboard-aware-scroll-view`.

## 🔧 Core concepts [#-core-concepts]

* **`Keyboard.dismiss()`** — hide keyboard.
* **Events** — `keyboardDidShow` / `keyboardDidHide` (platform naming differs for Will/Did).
* **`KeyboardAvoidingView`** — `behavior="padding"` (iOS) / often `"height"` or none on Android.
* **`keyboardShouldPersistTaps`** — on scroll views so taps register while keyboard is open.

## 💡 Examples [#-examples]

```tsx
import {
  Keyboard,
  KeyboardAvoidingView,
  Platform,
  Pressable,
  TextInput,
  StyleSheet,
} from "react-native";

export function ChatInput() {
  return (
    <KeyboardAvoidingView
      style={styles.flex}
      behavior={Platform.OS === "ios" ? "padding" : undefined}
      keyboardVerticalOffset={64}
    >
      <Pressable style={styles.flex} onPress={Keyboard.dismiss}>
        <TextInput placeholder="Message" style={styles.input} />
      </Pressable>
    </KeyboardAvoidingView>
  );
}

const styles = StyleSheet.create({
  flex: { flex: 1 },
  input: { borderWidth: 1, margin: 16, padding: 12, borderRadius: 8 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Double-avoiding (AvoidingView + manual padding) → huge gaps.
* Android `windowSoftInputMode` in manifest conflicting with JS avoidance.
* Forgetting `keyboardShouldPersistTaps="handled"` on forms in ScrollViews.

## 🔗 Related [#-related]

* [layout.md](/docs/react-native/layout) — flex + offsets
* [basic\_primitives.md](/docs/react-native/basic-primitives) — TextInput
* [modal.md](/docs/react-native/modal) — keyboard inside modals
* [platform\_specific.md](/docs/react-native/platform-specific) — iOS vs Android


# React Native Launcher Shortcuts (/docs/react-native/launcher-shortcut-menu)



# React Native Launcher Shortcuts [#react-native-launcher-shortcuts]

*React Native · Quick Reference*

***

## 📋 Overview [#-overview]

Android App Shortcuts allow users to long-press your app icon to access quick actions directly from the launcher. Supported on Android 7.1+ (API 25+).

***

## 🔧 Core Concepts [#-core-concepts]

| Shortcut Type | Description                                                            |
| ------------- | ---------------------------------------------------------------------- |
| **Static**    | Defined in `AndroidManifest.xml`, fixed at build time                  |
| **Dynamic**   | Added/removed at runtime via JavaScript                                |
| **Pinned**    | User manually pins to home screen (cannot be removed programmatically) |

***

## 🚀 Libraries [#-libraries]

### Recommended: `@rn-org/react-native-shortcuts` [#recommended-rn-orgreact-native-shortcuts]

```shellscript
npm install @rn-org/react-native-shortcuts
# or
yarn add @rn-org/react-native-shortcuts
```

### Alternative: `@mobigaurav/react-native-quick-actions` [#alternative-mobigauravreact-native-quick-actions]

```shellscript
npm install @mobigaurav/react-native-quick-actions
```

***

## 💡 Basic Implementation [#-basic-implementation]

### Check Support & Add Shortcuts [#check-support--add-shortcuts]

```tsx
import Shortcuts from '@rn-org/react-native-shortcuts'

// Check if supported (Android 7.1+)
const supported = await Shortcuts.isShortcutSupported()

// Add shortcuts
await Shortcuts.addShortcut({
  id: 'compose',
  title: 'Compose',
  longLabel: 'Start new message', // Max 25 chars
  iconName: 'ic_compose'          // Drawable resource name
})

await Shortcuts.addShortcut({
  id: 'search', 
  title: 'Search',
  iconName: 'ic_search'
})

// Remove all shortcuts
await Shortcuts.removeAllShortcuts()

// Remove specific shortcut
await Shortcuts.removeShortcut('compose')
```

### Handle Shortcut Navigation [#handle-shortcut-navigation]

```tsx
import { useEffect, useRef } from 'react'
import Shortcuts from '@rn-org/react-native-shortcuts'

function App() {
  // Handle initial launch via shortcut (cold start)
  useEffect(() => {
    const checkInitial = async () => {
      const id = await Shortcuts.getInitialShortcutId()
      if (id) navigateToShortcut(id)
    }
    checkInitial()
  }, [])

  // Handle shortcut when app is in background (warm start)
  useEffect(() => {
    const sub = Shortcuts.addOnShortcutUsedListener((id) => {
      navigateToShortcut(id)
    })
    return () => sub.remove()
  }, [])

  const navigateToShortcut = (id: string) => {
    switch(id) {
      case 'compose': navigation.navigate('Compose'); break
      case 'search': navigation.navigate('Search'); break
    }
  }

  return <YourApp />
}
```

***

## 🎨 Android Icons [#-android-icons]

Add icons to `android/app/src/main/res/drawable/`:

```
android/app/src/main/res/drawable/
  ├── ic_compose.xml      # Vector drawable
  ├── ic_search.png       # PNG image
  └── ic_settings.xml
```

**Requirements:**

* Material Design guidelines
* Vector (XML) preferred over raster (PNG)
* 48dp x 48dp recommended

***

## 📋 Android Manifest Setup [#-android-manifest-setup]

For **static** shortcuts (optional - pre-defined at build time):

```xml
<!-- android/app/src/main/AndroidManifest.xml -->
<application ...>
  <activity android:name=".MainActivity">
    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- Static shortcuts -->
    <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
  </activity>
</application>
```

```xml
<!-- android/app/src/main/res/xml/shortcuts.xml -->
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <shortcut
    android:shortcutId="compose"
    android:enabled="true"
    android:icon="@drawable/ic_compose"
    android:shortcutShortLabel="Compose"
    android:shortcutLongLabel="Compose Message">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.yourapp"
      android:targetClass="com.yourapp.MainActivity" />
    <categories android:name="android.shortcut.conversation" />
  </shortcut>
</shortcuts>
```

***

## ⚠️ Pitfalls [#️-pitfalls]

| Issue                                                   | Solution                                               |
| ------------------------------------------------------- | ------------------------------------------------------ |
| **Pinned shortcuts** cannot be removed programmatically | User must unpin manually                               |
| **4 shortcut limit** (dynamic + static)                 | Prioritize most used actions                           |
| **Launch mode issues**                                  | Check `android:launchMode` in manifest                 |
| **Icon not showing**                                    | Verify drawable resource exists and is correctly named |

***

## 🔗 Related [#-related]

* [deep\_linking.md](/docs/react-native/deep-linking) — Navigation from shortcuts
* [notifications.md](/docs/react-native/notifications) — Push notifications
* [keyboard.md](/docs/react-native/keyboard) — Keyboard handling

***

## 📚 Documentation [#-documentation]

* [Android App Shortcuts](https://developer.android.com/develop/ui/views/launch/shortcuts)
* [react-native-shortcuts](https://github.com/rn-org/react-native-shortcuts)
* [react-native-quick-actions](https://github.com/mobigaurav/react-native-quick-actions)


# Layout (/docs/react-native/layout)



# Layout [#layout]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Layout uses **Flexbox** (default `flexDirection: "column"`). Yoga implements flex on both platforms. Position with `flex`, alignment, margins/padding — not CSS Grid.

## 🔧 Core concepts [#-core-concepts]

* **Defaults** — column direction; `alignItems: stretch`.
* **Key props** — `flex`, `justifyContent`, `alignItems`, `alignSelf`, `gap` (newer RN).
* **Sizing** — numbers are density-independent pixels; `%` relative to parent.
* **Absolute** — `position: "absolute"` + `top`/`left`/`right`/`bottom`.
* **Safe area** — insets for notches / home indicator.

## 💡 Examples [#-examples]

```tsx
import { View, StyleSheet } from "react-native";

const styles = StyleSheet.create({
  screen: { flex: 1, padding: 16 },
  row: { flexDirection: "row", alignItems: "center", justifyContent: "space-between" },
  card: { flex: 1, minHeight: 120, borderRadius: 12, backgroundColor: "#eee" },
  fab: {
    position: "absolute",
    right: 16,
    bottom: 16,
    width: 56,
    height: 56,
    borderRadius: 28,
  },
});

export function Screen() {
  return (
    <View style={styles.screen}>
      <View style={styles.row}>
        <View style={styles.card} />
        <View style={[styles.card, { marginLeft: 12 }]} />
      </View>
      <View style={[styles.fab, { backgroundColor: "#111" }]} />
    </View>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Web CSS habits (`display: block`, grid) don’t apply.
* Missing `flex: 1` on parents → children with flex don’t expand.
* Fixed widths that overflow small phones — prefer flex + `minWidth`/`maxWidth`.

## 🔗 Related [#-related]

* [basic\_primitives.md](/docs/react-native/basic-primitives) — View / Text
* [dimensions.md](/docs/react-native/dimensions) — window size
* [statusbar.md](/docs/react-native/statusbar) — top inset
* [animation.md](/docs/react-native/animation) — layout animations


# Linking (/docs/react-native/linking)



# Linking [#linking]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Linking` opens URLs (https, tel, mailto, custom schemes) and listens for deep links that open the app. Configure schemes in native projects / `app.json`. For navigation integration, use React Navigation linking config or Expo Router.

## 🔧 Core concepts [#-core-concepts]

| API                       | Role                           |
| ------------------------- | ------------------------------ |
| `openURL`                 | Open external / custom URL     |
| `canOpenURL`              | Check handler (iOS LS queries) |
| `getInitialURL`           | Cold-start link                |
| `addEventListener('url')` | Warm links                     |
| `openSettings`            | App settings                   |

Universal Links / App Links need domain association files.

## 💡 Examples [#-examples]

```tsx
import { Linking, Pressable, Text, Alert } from "react-native";

async function openSupport() {
  const url = "mailto:support@example.com?subject=Help";
  const ok = await Linking.canOpenURL(url);
  if (!ok) {
    Alert.alert("No mail app available");
    return;
  }
  await Linking.openURL(url);
}

export function SupportLink() {
  return (
    <Pressable onPress={openSupport}>
      <Text>Email support</Text>
    </Pressable>
  );
}
```

**Listen for URLs:**

```tsx
import { useEffect } from "react";
import { Linking } from "react-native";

useEffect(() => {
  Linking.getInitialURL().then((url) => {
    if (url) handleUrl(url);
  });
  const sub = Linking.addEventListener("url", ({ url }) => handleUrl(url));
  return () => sub.remove();
}, []);
```

## ⚠️ Pitfalls [#️-pitfalls]

* iOS `canOpenURL` requires declared schemes in `LSApplicationQueriesSchemes`.
* Not handling both cold and warm start.
* Custom scheme collisions with other apps.
* Using Linking alone without mapping to navigation routes.

## 🔗 Related [#-related]

* [deeplinking.md](/docs/react-native/deeplinking) — deep link setup
* [navigation.md](/docs/react-native/navigation) — route mapping
* [Expo linking\_expo](/docs/react-native/expo/linking-expo) — Expo helpers
* [permissions.md](/docs/react-native/permissions) — settings
* [pressable.md](/docs/react-native/pressable) — buttons


# Maps (/docs/react-native/maps)



# Maps [#maps]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Maps are typically &#x2A;*`react-native-maps`** (Google/Apple MapKit) or Expo-friendly wrappers. Show a region, markers, and user location (with permissions). API keys required for Google Maps on Android (and iOS if using Google).

## 🔧 Core concepts [#-core-concepts]

| Piece                 | Role                               |
| --------------------- | ---------------------------------- |
| `MapView`             | Map canvas                         |
| `Marker` / `Polyline` | Annotations                        |
| `region` / `camera`   | Viewport                           |
| `showsUserLocation`   | Blue dot (permission)              |
| Provider              | `PROVIDER_GOOGLE` vs default Apple |

Cluster markers for dense data; avoid re-creating marker arrays carelessly.

## 💡 Examples [#-examples]

```tsx
import MapView, { Marker, PROVIDER_GOOGLE } from "react-native-maps";
import { StyleSheet } from "react-native";

export function StoreMap() {
  return (
    <MapView
      style={styles.map}
      provider={PROVIDER_GOOGLE}
      initialRegion={{
        latitude: 37.78825,
        longitude: -122.4324,
        latitudeDelta: 0.05,
        longitudeDelta: 0.05,
      }}
    >
      <Marker
        coordinate={{ latitude: 37.78825, longitude: -122.4324 }}
        title="Store"
        description="Open 9–5"
      />
    </MapView>
  );
}

const styles = StyleSheet.create({
  map: { flex: 1 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing Google Maps API key / billing → blank map.
* Tracking user location without purpose string / runtime permission.
* Animating region on every render.
* Huge numbers of markers without clustering.

## 🔗 Related [#-related]

* [permissions.md](/docs/react-native/permissions) — location
* [linking.md](/docs/react-native/linking) — open in Maps app
* [Expo config](/docs/react-native/expo/config) — keys / plugins
* [styling.md](/docs/react-native/styling) — layout
* [networking.md](/docs/react-native/networking) — geocoding APIs


# Modal (/docs/react-native/modal)



# Modal [#modal]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Modal` presents content above the current screen (native modal host). For navigation-style modals, prefer a stack with `presentation: "modal"`.

## 🔧 Core concepts [#-core-concepts]

* **Props** — `visible`, `transparent`, `animationType` (`none` | `slide` | `fade`).
* **`onRequestClose`** — required on Android (back button).
* **Nesting** — avoid deep modal stacks; use navigation instead.
* **Accessibility** — focus trap / labels for dismiss controls.

## 💡 Examples [#-examples]

```tsx
import { Modal, View, Text, Pressable, StyleSheet } from "react-native";

export function ConfirmModal({
  open,
  onClose,
  message,
}: {
  open: boolean;
  onClose: () => void;
  message: string;
}) {
  return (
    <Modal
      visible={open}
      transparent
      animationType="fade"
      onRequestClose={onClose}
    >
      <View style={styles.backdrop}>
        <View style={styles.sheet}>
          <Text>{message}</Text>
          <Pressable onPress={onClose} accessibilityRole="button">
            <Text>Close</Text>
          </Pressable>
        </View>
      </View>
    </Modal>
  );
}

const styles = StyleSheet.create({
  backdrop: {
    flex: 1,
    backgroundColor: "rgba(0,0,0,0.5)",
    justifyContent: "center",
    padding: 24,
  },
  sheet: { backgroundColor: "#fff", borderRadius: 12, padding: 16 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `onRequestClose` on Android.
* Putting a Modal inside a view with `opacity` / transforms — weird clipping.
* Using Modal for every route — navigators scale better.

## 🔗 Related [#-related]

* [backhandler.md](/docs/react-native/backhandler) — Android back
* [keyboard.md](/docs/react-native/keyboard) — inputs in modals
* [transition.md](/docs/react-native/transition) — presentation motion
* [touchable.md](/docs/react-native/touchable) — dismiss controls


# Navigation (/docs/react-native/navigation)



# Navigation [#navigation]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**React Navigation** is the standard stack for RN screens: native stack, bottom tabs, drawer. Define a navigator tree, pass params with types, and use hooks (`useNavigation`, `useRoute`). Expo Router is file-based on top of the same primitives—see Expo `router.md`.

## 🔧 Core concepts [#-core-concepts]

| Piece                 | Role                                   |
| --------------------- | -------------------------------------- |
| `NavigationContainer` | Root (bare RN; Expo Router wraps this) |
| Native Stack          | Push/pop screens                       |
| Tabs / Drawer         | Top-level IA                           |
| Params                | Typed route params                     |
| Linking               | Deep links ↔ routes                    |
| Nested navigators     | Independent histories                  |

Prefer `@react-navigation/native-stack` over JS stack for performance.

## 💡 Examples [#-examples]

```tsx
import { NavigationContainer } from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";

type RootStackParamList = {
  Home: undefined;
  Details: { id: string };
};

const Stack = createNativeStackNavigator<RootStackParamList>();

export function App() {
  return (
    <NavigationContainer>
      <Stack.Navigator>
        <Stack.Screen name="Home" component={HomeScreen} />
        <Stack.Screen name="Details" component={DetailsScreen} />
      </Stack.Navigator>
    </NavigationContainer>
  );
}
```

```tsx
import { useNavigation, useRoute } from "@react-navigation/native";
import type { NativeStackNavigationProp } from "@react-navigation/native-stack";
import type { RouteProp } from "@react-navigation/native";

function HomeScreen() {
  const navigation =
    useNavigation<NativeStackNavigationProp<RootStackParamList>>();
  return (
    <Pressable onPress={() => navigation.navigate("Details", { id: "1" })}>
      <Text>Open</Text>
    </Pressable>
  );
}

function DetailsScreen() {
  const route = useRoute<RouteProp<RootStackParamList, "Details">>();
  return <Text>{route.params.id}</Text>;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Multiple `NavigationContainer`s without a clear root.
* Untyped params → runtime surprises.
* Heavy work in screen components that stay mounted in tabs.
* Ignoring deep linking / back behavior on Android.

## 🔗 Related [#-related]

* [touchable.md](/docs/react-native/touchable) — Pressable
* [deeplinking.md](/docs/react-native/deeplinking) — URL schemes
* [drawer.md](/docs/react-native/drawer) — drawer patterns
* [backhandler.md](/docs/react-native/backhandler) — Android back
* [Expo router](/docs/react-native/expo/router) — file-based routing


# Networking (/docs/react-native/networking)



# Networking [#networking]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

RN supports `fetch`, `XMLHttpRequest`, and WebSockets. Use HTTPS, handle offline, and prefer a thin API client (fetch wrapper, axios, ky, React Query).

## 🔧 Core concepts [#-core-concepts]

* **`fetch(url, init)`** — Promise-based; no timeout built-in.
* **JSON** — `res.json()`; set `Content-Type` on requests.
* **Auth** — attach tokens in headers; store securely (SecureStore / Keychain).
* **Dev** — Android cleartext / ATS exceptions only for local debug.
* **Abort** — `AbortController` to cancel on unmount.

## 💡 Examples [#-examples]

```tsx
async function getUser(id: string, signal?: AbortSignal) {
  const res = await fetch(`https://api.example.com/users/${id}`, {
    headers: { Accept: "application/json" },
    signal,
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json() as Promise<{ id: string; name: string }>;
}
```

```tsx
import { useEffect, useState } from "react";

export function useUser(id: string) {
  const [data, setData] = useState<{ name: string } | null>(null);
  useEffect(() => {
    const ctrl = new AbortController();
    getUser(id, ctrl.signal).then(setData).catch(() => {});
    return () => ctrl.abort();
  }, [id]);
  return data;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* No network permission issues on iOS/Android for plain HTTPS — but ATS / cleartext can block HTTP.
* Ignoring non-2xx status — `fetch` only rejects on network failure.
* Leaking tokens in logs.

## 🔗 Related [#-related]

* [request.md](/docs/react-native/request) — request helpers
* [storage.md](/docs/react-native/storage) — token storage
* [permissions.md](/docs/react-native/permissions) — related OS permissions
* [notification.md](/docs/react-native/notification) — push payloads


# Notification (/docs/react-native/notification)



# Notification [#notification]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Local and push notifications need OS permission, device tokens, and a service (FCM / APNs). In Expo, use &#x2A;*`expo-notifications`** + EAS credentials; in bare RN, `@react-native-firebase/messaging` or Notifee are common.

## 🔧 Core concepts [#-core-concepts]

* **Permission** — request before scheduling / registering.
* **Channels (Android)** — create notification channels for importance.
* **Handlers** — foreground presentation; response (tap) → navigate / deep link.
* **Push tokens** — Expo push token or native FCM/APNs token → your backend.
* **EAS** — credentials for FCM / APNs managed via `eas credentials`.

## 💡 Examples [#-examples]

```tsx
import * as Notifications from "expo-notifications";
import { useEffect } from "react";
import { Platform } from "react-native";

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});

export function useNotificationSetup() {
  useEffect(() => {
    (async () => {
      const { status } = await Notifications.requestPermissionsAsync();
      if (status !== "granted") return;
      if (Platform.OS === "android") {
        await Notifications.setNotificationChannelAsync("default", {
          name: "default",
          importance: Notifications.AndroidImportance.DEFAULT,
        });
      }
      const token = (await Notifications.getExpoPushTokenAsync()).data;
      // send token to backend
      console.log(token);
    })();
  }, []);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Testing push on simulators — limited; use physical devices.
* Missing Android channels → silent / wrong importance.
* Not handling notification taps when app is killed (use last response API).

## 🔗 Related [#-related]

* [permissions.md](/docs/react-native/permissions) — permission flow
* [deeplinking.md](/docs/react-native/deeplinking) — open screens from taps
* [Expo/config.md](/docs/react-native/expo/config) — plugins / entitlements
* [Expo/build.md](/docs/react-native/expo/build) — store builds with push


# Notifications (/docs/react-native/notifications)



# Notifications [#notifications]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Local and push notifications alert users outside the app UI. On Expo, use `expo-notifications`; bare RN often uses Firebase / Notifee.

## 🔧 Core concepts [#-core-concepts]

| Piece       | Role                            |
| ----------- | ------------------------------- |
| Permissions | Request before scheduling       |
| Local       | Scheduled on-device             |
| Push        | Remote via FCM/APNs             |
| Handlers    | Foreground / response listeners |

## 💡 Examples [#-examples]

```tsx
import * as Notifications from 'expo-notifications';

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
    shouldShowBanner: true,
    shouldShowList: true,
  }),
});
```

```tsx
await Notifications.scheduleNotificationAsync({
  content: { title: 'Reminder', body: 'Ship the docs' },
  trigger: { type: Notifications.SchedulableTriggerInputTypes.TIME_INTERVAL, seconds: 5 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* iOS requires explicit permission; Android 13+ needs POST\_NOTIFICATIONS.
* Don’t assume push tokens are stable forever.
* Handle notification taps to deep-link into the right screen.

## 🔗 Related [#-related]

* [deep\_linking](/docs/react-native/deep-linking)
* [launcher\_shortcut\_menu](/docs/react-native/launcher-shortcut-menu)
* [getting\_started](/docs/react-native/getting-started)


# Permissions (/docs/react-native/permissions)



# Permissions [#permissions]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Sensitive APIs (camera, photos, location, mic, notifications, tracking) require runtime permission prompts plus Info.plist / AndroidManifest declarations. Expo: `expo-*` modules + config plugins.

## 🔧 Core concepts [#-core-concepts]

* **Declare** — usage strings (`NSCameraUsageDescription`) and manifest permissions.
* **Request at need** — when the user taps an action, not on cold start spam.
* **Check status** — `granted` | `denied` | `undetermined` | limited (iOS photos).
* **Settings** — if denied, deep-link to app settings (`Linking.openSettings()`).
* **Expo** — `expo-camera`, `expo-location`, `expo-image-picker`, etc.

## 💡 Examples [#-examples]

```tsx
import * as ImagePicker from "expo-image-picker";
import { Alert, Linking } from "react-native";

export async function pickImage() {
  const current = await ImagePicker.getMediaLibraryPermissionsAsync();
  let status = current.status;
  if (status !== "granted") {
    const req = await ImagePicker.requestMediaLibraryPermissionsAsync();
    status = req.status;
  }
  if (status !== "granted") {
    Alert.alert("Permission needed", "Enable photo access in Settings", [
      { text: "Open Settings", onPress: () => Linking.openSettings() },
      { text: "Cancel", style: "cancel" },
    ]);
    return null;
  }
  const result = await ImagePicker.launchImageLibraryAsync({
    mediaTypes: ImagePicker.MediaTypeOptions.Images,
    quality: 0.8,
  });
  return result.canceled ? null : result.assets[0];
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing plist usage descriptions → App Store reject / crash on access.
* Requesting everything at launch → users deny all.
* Ignoring Android 13+ granular media permissions.

## 🔗 Related [#-related]

* [Expo/plugins.md](/docs/react-native/expo/plugins) — config plugins
* [Expo/config.md](/docs/react-native/expo/config) — app config
* [notification.md](/docs/react-native/notification) — notification permission
* [settings.md](/docs/react-native/settings) — open settings


# Picker (/docs/react-native/picker)



# Picker [#picker]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Pickers select from a list (date, time, dropdown). Core RN removed the old `Picker`; use `@react-native-picker/picker`, `@react-native-community/datetimepicker`, or Expo equivalents.

## 🔧 Core concepts [#-core-concepts]

* **`@react-native-picker/picker`** — `Picker` + `Picker.Item`.
* **Date/time** — community datetime picker; platform-native UI.
* **Expo** — `expo-date-picker` patterns via community modules; or JS UI pickers.
* **Controlled** — `selectedValue` + `onValueChange`.

## 💡 Examples [#-examples]

```tsx
import { useState } from "react";
import { Picker } from "@react-native-picker/picker";

export function FruitPicker() {
  const [fruit, setFruit] = useState("apple");
  return (
    <Picker selectedValue={fruit} onValueChange={(v) => setFruit(v)}>
      <Picker.Item label="Apple" value="apple" />
      <Picker.Item label="Banana" value="banana" />
      <Picker.Item label="Orange" value="orange" />
    </Picker>
  );
}
```

```tsx
import DateTimePicker from "@react-native-community/datetimepicker";
import { Platform } from "react-native";

export function Birthday({
  value,
  onChange,
}: {
  value: Date;
  onChange: (d: Date) => void;
}) {
  return (
    <DateTimePicker
      value={value}
      mode="date"
      display={Platform.OS === "ios" ? "spinner" : "default"}
      onChange={(_, date) => date && onChange(date)}
    />
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Importing removed core `Picker` from `react-native`.
* Android date picker fires once and closes — manage `show` state.
* Styling differences: wrap platform-specific UI.

## 🔗 Related [#-related]

* [platform\_specific.md](/docs/react-native/platform-specific) — iOS vs Android UI
* [basic\_primitives.md](/docs/react-native/basic-primitives) — form layout
* [touchable.md](/docs/react-native/touchable) — open custom pickers
* [modal.md](/docs/react-native/modal) — picker in modal


# Platform-specific (/docs/react-native/platform-specific)



# Platform-specific [#platform-specific]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Branch behavior and files per OS with `Platform`, `.ios.tsx` / `.android.tsx` extensions, and platform select helpers. Keep shared logic in common modules.

## 🔧 Core concepts [#-core-concepts]

* **`Platform.OS`** — `"ios" | "android" | "web" | …`.
* **`Platform.select(\{ ios, android, default \})`**.
* **`Platform.Version`** — API level / iOS version.
* **Extensions** — `Button.ios.tsx`, `Button.android.tsx` resolved by Metro.
* **Expo** — `Platform` still applies; also check Constants for store client vs standalone.

## 💡 Examples [#-examples]

```tsx
import { Platform, StyleSheet, Text } from "react-native";

const styles = StyleSheet.create({
  shadow: Platform.select({
    ios: {
      shadowColor: "#000",
      shadowOpacity: 0.15,
      shadowRadius: 8,
      shadowOffset: { width: 0, height: 4 },
    },
    android: { elevation: 4 },
    default: {},
  }),
});

export function Hint() {
  return (
    <Text>
      {Platform.OS === "ios" ? "Swipe from left to go back" : "Use the back button"}
    </Text>
  );
}
```

```plaintext
components/
  Map.tsx          # shared types / re-export
  Map.ios.tsx
  Map.android.tsx
```

## ⚠️ Pitfalls [#️-pitfalls]

* Duplicating large components instead of small platform branches.
* Assuming `Platform.OS === "ios"` covers iPad idioms — check size classes too.
* Forgetting web when using React Native Web.

## 🔗 Related [#-related]

* [layout.md](/docs/react-native/layout) — shared layout
* [statusbar.md](/docs/react-native/statusbar) — bar styles differ
* [keyboard.md](/docs/react-native/keyboard) — avoiding behavior
* [Expo/config.md](/docs/react-native/expo/config) — platform config blocks


# Player (/docs/react-native/player)



# Player [#player]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Media playback (audio/video) uses libraries such as `expo-av`, `expo-audio` / `expo-video` (newer Expo SDK splits), `react-native-video`, or `react-native-track-player` for background audio.

## 🔧 Core concepts [#-core-concepts]

* **Load source** — local `require` or remote URI; handle buffering.
* **Controls** — play / pause / seek / rate; keep UI in sync with status callbacks.
* **Background** — audio session / foreground service; lock-screen controls need extra setup.
* **Lifecycle** — unload on unmount to free decoders.
* **Expo** — config plugins for background modes when needed.

## 💡 Examples [#-examples]

```tsx
import { useEffect, useRef } from "react";
import { Button } from "react-native";
import { Audio } from "expo-av";

export function SoundButton({ uri }: { uri: string }) {
  const soundRef = useRef<Audio.Sound | null>(null);

  useEffect(() => {
    return () => {
      soundRef.current?.unloadAsync();
    };
  }, []);

  async function toggle() {
    if (!soundRef.current) {
      const { sound } = await Audio.Sound.createAsync({ uri });
      soundRef.current = sound;
      await sound.playAsync();
      return;
    }
    const status = await soundRef.current.getStatusAsync();
    if (status.isLoaded && status.isPlaying) await soundRef.current.pauseAsync();
    else await soundRef.current.playAsync();
  }

  return <Button title="Play / Pause" onPress={toggle} />;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Not unloading players → memory / decoder leaks.
* Autoplay policies and silent switch (iOS) — configure audio mode.
* Large remote files without progress / error UI.

## 🔗 Related [#-related]

* [permissions.md](/docs/react-native/permissions) — mic / media access
* [storage.md](/docs/react-native/storage) — cached files
* [Expo/plugins.md](/docs/react-native/expo/plugins) — native modules
* [networking.md](/docs/react-native/networking) — streaming URLs


# Pressable (/docs/react-native/pressable)



# Pressable [#pressable]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Pressable` is the modern press handler—prefer it over `TouchableOpacity` / `TouchableHighlight`. Style from press state, configure hit slop, and set accessibility roles. See also [touchable.md](/docs/react-native/touchable) for legacy touchables.

## 🔧 Core concepts [#-core-concepts]

* **Events** — `onPress`, `onLongPress`, `onPressIn` / `Out`.
* **State style** — `style=\{(\{ pressed \}) => ...\}`.
* **`hitSlop`** — expand touch target.
* **`android_ripple`** — Material ripple.
* **`disabled`** — block interaction + a11y state.
* **Delay** — `delayLongPress`.

## 💡 Examples [#-examples]

```tsx
import { Pressable, Text, StyleSheet } from "react-native";

export function Button({
  label,
  onPress,
  disabled,
}: {
  label: string;
  onPress: () => void;
  disabled?: boolean;
}) {
  return (
    <Pressable
      accessibilityRole="button"
      accessibilityState={{ disabled: !!disabled }}
      disabled={disabled}
      hitSlop={8}
      android_ripple={{ color: "#ffffff55" }}
      onPress={onPress}
      style={({ pressed }) => [
        styles.btn,
        pressed && styles.pressed,
        disabled && styles.disabled,
      ]}
    >
      <Text style={styles.label}>{label}</Text>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  btn: {
    backgroundColor: "#111",
    paddingVertical: 12,
    paddingHorizontal: 16,
    borderRadius: 8,
  },
  pressed: { opacity: 0.85 },
  disabled: { opacity: 0.4 },
  label: { color: "#fff", fontWeight: "600", textAlign: "center" },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Touch targets under \~44×44 pt.
* Nested Pressables competing for gestures.
* Using Touchable\* in new code without reason.
* Missing `accessibilityRole="button"`.

## 🔗 Related [#-related]

* [touchable.md](/docs/react-native/touchable) — legacy touchables
* [gesture.md](/docs/react-native/gesture) — advanced gestures
* [haptics.md](/docs/react-native/haptics) — feedback
* [accesebility.md](/docs/react-native/accesebility) — roles
* [animation.md](/docs/react-native/animation) — press animations


# React Native for Web (/docs/react-native/reactnativeforweb)



# React Native for Web [#react-native-for-web]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**React Native for Web** (`react-native-web`) lets many React Native components and APIs run in the browser by mapping them to HTML/CSS. You keep `View` / `Text` / `StyleSheet` code and share UI across iOS, Android, and web — with platform-specific escapes when needed.

## 🔧 Core concepts [#-core-concepts]

| Idea               | Meaning                                               |
| ------------------ | ----------------------------------------------------- |
| `react-native-web` | Compatibility layer: RN primitives → DOM              |
| Alias              | Bundler maps `react-native` → `react-native-web`      |
| Shared UI          | One component tree for multiple targets               |
| Platform           | `Platform.OS === "web"` for web-only branches         |
| Expo web           | Expo can export/serve a web target with RN primitives |
| Limits             | Not every native module has a web equivalent          |

Typical stack: React + React DOM + `react-native-web` + Metro/Webpack/Vite/Expo.

## 💡 Examples [#-examples]

**Same component on native and web:**

```jsx
import { View, Text, StyleSheet, Platform } from "react-native";

export function Banner() {
  return (
    <View style={styles.box}>
      <Text style={styles.title}>Hello from {Platform.OS}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  box: {
    padding: 16,
    backgroundColor: "#e2e8f0",
    // web accepts extra CSS-like props via RN-web in many setups
    maxWidth: 480,
  },
  title: { fontSize: 18, fontWeight: "600" },
});
```

**Platform-specific file** (`Button.web.js` vs `Button.native.js`):

```jsx
// Button.web.js
export function Button({ label, onPress }) {
  return (
    <button type="button" onClick={onPress}>
      {label}
    </button>
  );
}
```

```jsx
// Button.native.js
import { Pressable, Text } from "react-native";

export function Button({ label, onPress }) {
  return (
    <Pressable onPress={onPress}>
      <Text>{label}</Text>
    </Pressable>
  );
}
```

**Expo web (concept):**

```shellscript
npx create-expo-app@latest MyApp
cd MyApp
npx expo start --web
```

**Webpack/Vite alias sketch (concept):**

```js
// resolve.alias (tool-dependent)
{
  "react-native$": "react-native-web"
}
```

**Safe branching:**

```jsx
import { Platform, Linking, Text } from "react-native";

async function openDocs() {
  const url = "https://necolas.github.io/react-native-web/";
  if (Platform.OS === "web") {
    window.open(url, "_blank", "noopener,noreferrer");
  } else {
    await Linking.openURL(url);
  }
}

// <Text onPress={openDocs}>Docs</Text>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Native-only modules (camera, biometrics, some sensors) need web stubs or alternatives.
* Accessibility and SEO differ on web — you may need real landmarks/`<a href>` for marketing pages.
* Flexbox works, but browser scrolling, hover, and cursor need web-aware styling.
* Don’t assume pixel-perfect parity; test on a real browser early.
* Alias misconfiguration causes “Invalid hook call” or dual-React copies — keep a single `react` / `react-dom` version.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/react-native/getting-started)
* [hello\_world.md](/docs/react-native/hello-world)
* [styling.md](/docs/react-native/styling)
* [linking.md](/docs/react-native/linking)
* [pressable.md](/docs/react-native/pressable)


# RefreshControl (/docs/react-native/refresh-control)



# RefreshControl [#refreshcontrol]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`RefreshControl` adds pull-to-refresh to `ScrollView` or `FlatList`. Drive it with controlled `refreshing` boolean and `onRefresh` that loads data then clears the flag.

## 🔧 Core concepts [#-core-concepts]

* **`refreshing`** — spinner visibility.
* **`onRefresh`** — start async reload.
* **Colors** — `tintColor` (iOS), `colors` (Android).
* **Progress view** — Android `progressViewOffset`.
* **Pair** — often with React Query `refetch`.

## 💡 Examples [#-examples]

```tsx
import { useCallback, useState } from "react";
import { FlatList, RefreshControl, Text } from "react-native";

export function Feed({
  items,
  reload,
}: {
  items: { id: string; title: string }[];
  reload: () => Promise<void>;
}) {
  const [refreshing, setRefreshing] = useState(false);

  const onRefresh = useCallback(async () => {
    setRefreshing(true);
    try {
      await reload();
    } finally {
      setRefreshing(false);
    }
  }, [reload]);

  return (
    <FlatList
      data={items}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => <Text>{item.title}</Text>}
      refreshControl={
        <RefreshControl refreshing={refreshing} onRefresh={onRefresh} />
      }
    />
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Leaving `refreshing` true on error—use `try/finally`.
* Triggering refresh on mount unintentionally.
* Nested scrollables fighting the gesture.
* Not awaiting the fetch before clearing state.

## 🔗 Related [#-related]

* [flatlist.md](/docs/react-native/flatlist) — lists
* [scrollview.md](/docs/react-native/scrollview) — scroll
* [networking.md](/docs/react-native/networking) — fetch
* [request.md](/docs/react-native/request) — HTTP helpers
* [activity\_indicator.md](/docs/react-native/activity-indicator) — spinners


# Request (/docs/react-native/request)



# Request [#request]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Centralize HTTP requests: base URL, auth headers, error mapping, retries. Keep UI hooks thin; put transport in a small `api` / `request` module.

## 🔧 Core concepts [#-core-concepts]

* **Wrapper** — `request(path, options)` over `fetch`.
* **Interceptors** — inject tokens; refresh on 401.
* **Errors** — typed API errors with status + body.
* **Timeouts** — `AbortController` + `setTimeout`.
* **Caching** — React Query / SWR for GET dedupe.

## 💡 Examples [#-examples]

```ts
const BASE = "https://api.example.com";

export class ApiError extends Error {
  constructor(
    message: string,
    public status: number,
    public body: unknown,
  ) {
    super(message);
  }
}

export async function request<T>(
  path: string,
  init: RequestInit & { token?: string; timeoutMs?: number } = {},
): Promise<T> {
  const ctrl = new AbortController();
  const t = setTimeout(() => ctrl.abort(), init.timeoutMs ?? 15000);
  try {
    const res = await fetch(`${BASE}${path}`, {
      ...init,
      signal: ctrl.signal,
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
        ...(init.token ? { Authorization: `Bearer ${init.token}` } : {}),
        ...init.headers,
      },
    });
    const body = await res.json().catch(() => null);
    if (!res.ok) throw new ApiError("Request failed", res.status, body);
    return body as T;
  } finally {
    clearTimeout(t);
  }
}
```

```ts
export const getProfile = (token: string) =>
  request<{ name: string }>("/me", { token });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Duplicating fetch logic in every screen.
* Swallowing errors without user feedback.
* Hardcoding secrets in the client — use backend for privileged calls.

## 🔗 Related [#-related]

* [networking.md](/docs/react-native/networking) — transport basics
* [storage.md](/docs/react-native/storage) — token persistence
* [settings.md](/docs/react-native/settings) — env / config flags
* [deeplinking.md](/docs/react-native/deeplinking) — post-auth routes


# Safe Area (/docs/react-native/safe-area)



# Safe Area [#safe-area]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Safe areas avoid notches, status bars, and home indicators. Use `react-native-safe-area-context` (`SafeAreaProvider`, `SafeAreaView`, `useSafeAreaInsets`)—the built-in `SafeAreaView` is limited (iOS-focused). Wrap the app once in a provider.

## 🔧 Core concepts [#-core-concepts]

* **`SafeAreaProvider`** — root wrapper.
* **`useSafeAreaInsets()`** — `\{ top, right, bottom, left \}`.
* **`SafeAreaView`** — applies padding edges.
* **`edges`** — choose which sides (`['top','bottom']`).
* **Headers** — native stack often handles top inset; don’t double-pad.

## 💡 Examples [#-examples]

```tsx
import {
  SafeAreaProvider,
  SafeAreaView,
  useSafeAreaInsets,
} from "react-native-safe-area-context";
import { View, Text, StyleSheet } from "react-native";

export function App() {
  return (
    <SafeAreaProvider>
      <Screen />
    </SafeAreaProvider>
  );
}

function Screen() {
  const insets = useSafeAreaInsets();
  return (
    <SafeAreaView style={styles.flex} edges={["top", "bottom"]}>
      <View style={[styles.fab, { bottom: insets.bottom + 16 }]}>
        <Text>FAB</Text>
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  flex: { flex: 1 },
  fab: {
    position: "absolute",
    right: 16,
    padding: 12,
    backgroundColor: "#111",
  },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `SafeAreaProvider` → zero insets.
* Double-counting insets with header + screen padding.
* Using legacy RN `SafeAreaView` on Android expecting notch handling.
* Absolute tab bars covering content without bottom inset.

## 🔗 Related [#-related]

* [statusbar.md](/docs/react-native/statusbar) — status bar style
* [navigation.md](/docs/react-native/navigation) — headers
* [layout.md](/docs/react-native/layout) — flex
* [dimensions.md](/docs/react-native/dimensions) — screen size
* [styling.md](/docs/react-native/styling) — padding


# ScrollView (/docs/react-native/scrollview)



# ScrollView [#scrollview]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`ScrollView` scrolls a finite set of children. Use for short content (forms, static pages). For long or dynamic lists prefer `FlatList` / `SectionList`. Combine with `KeyboardAvoidingView` / `keyboardShouldPersistTaps` for forms.

## 🔧 Core concepts [#-core-concepts]

* **All children mount** — no virtualization.
* **Horizontal** — `horizontal` prop.
* **Refresh** — `refreshControl=\{<RefreshControl ... />\}`.
* **Paging** — `pagingEnabled`, `snapToInterval`.
* **Nested** — careful with lists; prefer one scroll parent.
* **Refs** — `scrollTo` / `scrollToEnd`.

## 💡 Examples [#-examples]

```tsx
import { ScrollView, Text, StyleSheet } from "react-native";

export function About() {
  return (
    <ScrollView
      contentContainerStyle={styles.content}
      keyboardShouldPersistTaps="handled"
    >
      <Text style={styles.title}>About</Text>
      <Text>Long copy…</Text>
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  content: { padding: 16, paddingBottom: 48 },
  title: { fontSize: 22, marginBottom: 12 },
});
```

**Horizontal chips:**

```tsx
<ScrollView horizontal showsHorizontalScrollIndicator={false}>
  {tags.map((t) => (
    <Chip key={t} label={t} />
  ))}
</ScrollView>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mapping hundreds of items into ScrollView → jank/memory.
* Nesting FlatList inside ScrollView (virtualization breaks).
* Forgetting bottom padding behind tab bars / home indicator.
* `keyboardShouldPersistTaps` default blocking taps while keyboard open.

## 🔗 Related [#-related]

* [flatlist.md](/docs/react-native/flatlist) — virtualized lists
* [keyboard.md](/docs/react-native/keyboard) — keyboard UX
* [refresh\_control.md](/docs/react-native/refresh-control) — pull to refresh
* [safe\_area.md](/docs/react-native/safe-area) — insets
* [layout.md](/docs/react-native/layout) — flex layout


# SectionList (/docs/react-native/sectionlist)



# SectionList [#sectionlist]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`SectionList` is a virtualized list of sections, each with a title and `data` array. Use for alphabetical contacts, grouped settings, or day-bucketed feeds. Same performance rules as `FlatList`.

## 🔧 Core concepts [#-core-concepts]

| Prop                          | Role                         |
| ----------------------------- | ---------------------------- |
| `sections`                    | `\{ title, data \}[]`        |
| `renderItem`                  | Row                          |
| `renderSectionHeader`         | Section title                |
| `keyExtractor`                | Item keys                    |
| `stickySectionHeadersEnabled` | Sticky headers (iOS default) |

Shape: `SectionListData<ItemT>`.

## 💡 Examples [#-examples]

```tsx
import { SectionList, Text, StyleSheet } from "react-native";

type Item = { id: string; name: string };
type Section = { title: string; data: Item[] };

export function Contacts({ sections }: { sections: Section[] }) {
  return (
    <SectionList
      sections={sections}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => <Text style={styles.row}>{item.name}</Text>}
      renderSectionHeader={({ section }) => (
        <Text style={styles.header}>{section.title}</Text>
      )}
    />
  );
}

const styles = StyleSheet.create({
  header: {
    fontWeight: "700",
    padding: 8,
    backgroundColor: "#f2f2f2",
  },
  row: { padding: 12 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Empty `data` arrays still rendering awkward headers—filter sections.
* Unstable section object identities causing rerenders.
* Nesting inside ScrollView.
* Using SectionList for a single flat list—use FlatList.

## 🔗 Related [#-related]

* [flatlist.md](/docs/react-native/flatlist) — flat virtualization
* [scrollview.md](/docs/react-native/scrollview) — short content
* [refresh\_control.md](/docs/react-native/refresh-control) — pull to refresh
* [styling.md](/docs/react-native/styling) — headers
* [keys\_lists](/docs/react-native/../react/keys-lists) — keys


# Settings (/docs/react-native/settings)



# Settings [#settings]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

App settings span in-app preferences, opening the OS Settings page, and build-time config (`react-native-config`, Expo `extra` / env). Separate user prefs from secrets.

## 🔧 Core concepts [#-core-concepts]

* **In-app prefs** — theme, language, feature toggles → AsyncStorage / MMKV / SecureStore.
* **`Linking.openSettings()`** — send user to system app settings (permissions).
* **Build config** — `.env` via Expo (`EXPO_PUBLIC_*`) or native config libs.
* **Expo Constants** — `Constants.expoConfig?.extra` for non-secret config.

## 💡 Examples [#-examples]

```tsx
import { Linking, Pressable, Text } from "react-native";

export function OpenAppSettings() {
  return (
    <Pressable onPress={() => Linking.openSettings()} accessibilityRole="button">
      <Text>Open system settings</Text>
    </Pressable>
  );
}
```

```tsx
import Constants from "expo-constants";

const apiUrl =
  Constants.expoConfig?.extra?.apiUrl ?? "https://api.example.com";
```

```ts
// app.config.ts extra
export default {
  expo: {
    extra: {
      apiUrl: process.env.EXPO_PUBLIC_API_URL,
    },
  },
};
```

## ⚠️ Pitfalls [#️-pitfalls]

* Putting secrets in `EXPO_PUBLIC_*` or `extra` — they ship in the binary.
* Mixing permission recovery UI with preference screens without clear copy.
* Not migrating prefs when storage keys change.

## 🔗 Related [#-related]

* [storage.md](/docs/react-native/storage) — persistence
* [permissions.md](/docs/react-native/permissions) — settings deep link
* [Expo/config.md](/docs/react-native/expo/config) — app config
* [platform\_specific.md](/docs/react-native/platform-specific) — OS differences


# Share (/docs/react-native/share)



# Share [#share]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Share` opens the platform share sheet for text/URLs (and files via community modules). Use it for invite links, exports, and content sharing.

## 🔧 Core concepts [#-core-concepts]

* **`Share.share(\{ message, url, title \})`** — core API.
* **Result** — `sharedAction` | `dismissedAction` (iOS mainly).
* **Files** — `expo-sharing` / `react-native-share` for images/PDFs.
* **Permissions** — writing to cache before sharing files.

## 💡 Examples [#-examples]

```tsx
import { Share, Pressable, Text, Platform } from "react-native";

export function ShareLink({ url }: { url: string }) {
  async function onShare() {
    try {
      await Share.share(
        Platform.OS === "ios"
          ? { url, message: "Check this out" }
          : { message: `Check this out ${url}` },
      );
    } catch {
      // user-facing error optional
    }
  }
  return (
    <Pressable onPress={onShare} accessibilityRole="button">
      <Text>Share</Text>
    </Pressable>
  );
}
```

```tsx
import * as Sharing from "expo-sharing";

async function shareFile(uri: string) {
  if (!(await Sharing.isAvailableAsync())) return;
  await Sharing.shareAsync(uri);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Android often wants the URL inside `message`, not `url`.
* Assuming share succeeded when the sheet merely opened.
* Sharing huge files from remote URIs without downloading first.

## 🔗 Related [#-related]

* [clipboard.md](/docs/react-native/clipboard) — copy instead of share
* [storage.md](/docs/react-native/storage) — temp files
* [permissions.md](/docs/react-native/permissions) — media access
* [networking.md](/docs/react-native/networking) — download then share


# StatusBar (/docs/react-native/statusbar)



# StatusBar [#statusbar]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`StatusBar` controls the system status bar style (light/dark content) and visibility. Combine with **safe area** insets so content isn’t under the bar or notch.

## 🔧 Core concepts [#-core-concepts]

* **`barStyle`** — `"light-content"` | `"dark-content"`.
* **`backgroundColor`** — Android; iOS is typically transparent over the scene.
* **`translucent`** — Android draws under the bar.
* **Per-screen** — React Navigation `options=\{\{ statusBarStyle \}\}` or `<StatusBar />` in screen.
* **Expo** — `expo-status-bar` (`style="light"`).

## 💡 Examples [#-examples]

```tsx
import { StatusBar, View, Text, StyleSheet } from "react-native";
import { useSafeAreaInsets } from "react-native-safe-area-context";

export function DarkHeader() {
  const insets = useSafeAreaInsets();
  return (
    <View style={[styles.header, { paddingTop: insets.top, backgroundColor: "#111" }]}>
      <StatusBar barStyle="light-content" />
      <Text style={styles.title}>Inbox</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  header: { paddingHorizontal: 16, paddingBottom: 12 },
  title: { color: "#fff", fontSize: 20, fontWeight: "600" },
});
```

```tsx
import { StatusBar } from "expo-status-bar";

<StatusBar style="dark" />;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Setting bar style without matching background → unreadable icons.
* Ignoring safe area → content under notch / Dynamic Island.
* Multiple conflicting `StatusBar` mounts across stacked screens.

## 🔗 Related [#-related]

* [layout.md](/docs/react-native/layout) — padding / flex
* [dimensions.md](/docs/react-native/dimensions) — window metrics
* [platform\_specific.md](/docs/react-native/platform-specific) — Android vs iOS
* [transition.md](/docs/react-native/transition) — screen changes


# Storage (/docs/react-native/storage)



# Storage [#storage]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Persist data on device: **AsyncStorage** / **MMKV** for general prefs, **SecureStore** / Keychain for secrets, and the filesystem for files. Remember the store is per-install and can be cleared.

## 🔧 Core concepts [#-core-concepts]

* **AsyncStorage** — async key/value strings; fine for small prefs.
* **MMKV** — fast sync-ish storage (via JSI); great for app state.
* **SecureStore / Keychain** — tokens, not large blobs.
* **File system** — `expo-file-system` for downloads/cache.
* **Serialization** — `JSON.stringify` / `parse` with versioned schemas.

## 💡 Examples [#-examples]

```tsx
import AsyncStorage from "@react-native-async-storage/async-storage";

const KEY = "settings/v1";

export async function loadSettings<T>(fallback: T): Promise<T> {
  const raw = await AsyncStorage.getItem(KEY);
  if (!raw) return fallback;
  try {
    return JSON.parse(raw) as T;
  } catch {
    return fallback;
  }
}

export async function saveSettings<T>(value: T) {
  await AsyncStorage.setItem(KEY, JSON.stringify(value));
}
```

```tsx
import * as SecureStore from "expo-secure-store";

await SecureStore.setItemAsync("session", token);
const token = await SecureStore.getItemAsync("session");
```

## ⚠️ Pitfalls [#️-pitfalls]

* Storing secrets in AsyncStorage.
* Unbounded growth — no eviction strategy for caches.
* Assuming storage survives reinstall or OS backup policies for secure items.

## 🔗 Related [#-related]

* [settings.md](/docs/react-native/settings) — preferences UX
* [request.md](/docs/react-native/request) — auth tokens
* [clipboard.md](/docs/react-native/clipboard) — ephemeral data
* [Expo/config.md](/docs/react-native/expo/config) — Expo modules


# Styling (/docs/react-native/styling)



# Styling [#styling]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

RN styles use a subset of CSS via `StyleSheet.create` or inline objects. Layout is Flexbox by default (`flexDirection: 'column'`). No cascading selectors—compose style arrays. Prefer `StyleSheet` for identity and validation.

## 🔧 Core concepts [#-core-concepts]

| Topic       | Notes                                                     |
| ----------- | --------------------------------------------------------- |
| Flexbox     | `flex`, `justifyContent`, `alignItems`, `gap` (modern RN) |
| Units       | Density-independent numbers (dp), not `px` strings        |
| Platform    | `Platform.select` / `.ios.md` files                       |
| Composition | `style=\{[styles.base, cond && styles.active]\}`          |
| Text        | Limited font props; custom fonts need linking/Expo plugin |

Libraries: NativeWind, Restyle, Tamagui—optional.

## 💡 Examples [#-examples]

```tsx
import { Platform, StyleSheet, Text, View } from "react-native";

export function Card({ title }: { title: string }) {
  return (
    <View style={styles.card}>
      <Text style={styles.title}>{title}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  card: {
    padding: 16,
    borderRadius: 12,
    backgroundColor: "#fff",
    ...Platform.select({
      ios: {
        shadowColor: "#000",
        shadowOpacity: 0.1,
        shadowRadius: 8,
        shadowOffset: { width: 0, height: 2 },
      },
      android: { elevation: 3 },
    }),
  },
  title: {
    fontSize: 18,
    fontWeight: "600",
    color: "#111",
  },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Assuming web CSS (no inheritance for most text styles beyond Text parent quirks).
* Percentage heights without parent flex/height.
* Inline new style objects in hot list rows without need.
* Hardcoding colors everywhere—centralize tokens.

## 🔗 Related [#-related]

* [layout.md](/docs/react-native/layout) — flex patterns
* [platform\_specific.md](/docs/react-native/platform-specific) — Platform
* [dimensions.md](/docs/react-native/dimensions) — size
* [basic\_primitives.md](/docs/react-native/basic-primitives) — View/Text
* [safe\_area.md](/docs/react-native/safe-area) — insets


# TextInput (/docs/react-native/textinput)



# TextInput [#textinput]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`TextInput` is the core text entry component. Controlled via `value` + `onChangeText`. Tune keyboard (`keyboardType`, `autoCapitalize`, `secureTextEntry`), and handle focus with refs. Pair with labels for accessibility.

## 🔧 Core concepts [#-core-concepts]

| Prop                                | Role               |
| ----------------------------------- | ------------------ |
| `value` / `onChangeText`            | Controlled text    |
| `defaultValue`                      | Uncontrolled start |
| `placeholder`                       | Hint               |
| `secureTextEntry`                   | Password           |
| `keyboardType`                      | email/number/…     |
| `multiline` / `numberOfLines`       | Text area          |
| `returnKeyType` / `onSubmitEditing` | Keyboard action    |
| `editable`                          | Disable            |

Use `autoComplete` / `textContentType` for password managers.

## 💡 Examples [#-examples]

```tsx
import { useRef, useState } from "react";
import { TextInput, Pressable, Text, StyleSheet } from "react-native";

export function LoginFields() {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const passwordRef = useRef<TextInput>(null);

  return (
    <>
      <Text nativeID="emailLabel">Email</Text>
      <TextInput
        style={styles.input}
        value={email}
        onChangeText={setEmail}
        keyboardType="email-address"
        autoCapitalize="none"
        autoComplete="email"
        accessibilityLabelledBy="emailLabel"
        returnKeyType="next"
        onSubmitEditing={() => passwordRef.current?.focus()}
      />
      <TextInput
        ref={passwordRef}
        style={styles.input}
        value={password}
        onChangeText={setPassword}
        secureTextEntry
        autoComplete="password"
        accessibilityLabel="Password"
      />
    </>
  );
}

const styles = StyleSheet.create({
  input: {
    borderWidth: 1,
    borderColor: "#ccc",
    borderRadius: 8,
    padding: 12,
    marginBottom: 12,
  },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Controlled input without updating `value` → can’t type.
* Wrapping in a scroll view without `keyboardShouldPersistTaps`.
* Tiny touch targets / missing labels.
* Android `underlineColorAndroid` surprises—set transparent if needed.

## 🔗 Related [#-related]

* [keyboard.md](/docs/react-native/keyboard) — avoid/cover
* [scrollview.md](/docs/react-native/scrollview) — forms
* [pressable.md](/docs/react-native/pressable) — submit buttons
* [accesebility.md](/docs/react-native/accesebility) — labels
* [touchable.md](/docs/react-native/touchable) — press handling


# Touchable (/docs/react-native/touchable)



# Touchable [#touchable]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Handle presses with &#x2A;*`Pressable`** (recommended), or legacy `TouchableOpacity` / `TouchableHighlight` / `TouchableWithoutFeedback`. Inside Gesture Handler navigators, prefer RNGH touchables.

## 🔧 Core concepts [#-core-concepts]

* **`Pressable`** — `onPress`, `onLongPress`, style as function of `\{ pressed \}`.
* **Hit slop** — expand touch target without changing layout.
* **Disabled** — `disabled` + a11y state.
* **Feedback** — opacity, ripple (`android_ripple`), haptic via Expo Haptics.
* **Legacy** — Touchable\* still work; migrate to Pressable when touching code.

## 💡 Examples [#-examples]

```tsx
import { Pressable, Text, StyleSheet } from "react-native";

export function PrimaryButton({
  label,
  onPress,
  disabled,
}: {
  label: string;
  onPress: () => void;
  disabled?: boolean;
}) {
  return (
    <Pressable
      onPress={onPress}
      disabled={disabled}
      hitSlop={8}
      accessibilityRole="button"
      accessibilityState={{ disabled: !!disabled }}
      android_ripple={{ color: "#ffffff55" }}
      style={({ pressed }) => [
        styles.btn,
        pressed && styles.pressed,
        disabled && styles.disabled,
      ]}
    >
      <Text style={styles.label}>{label}</Text>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  btn: {
    backgroundColor: "#111",
    paddingVertical: 12,
    paddingHorizontal: 16,
    borderRadius: 8,
  },
  pressed: { opacity: 0.85 },
  disabled: { opacity: 0.4 },
  label: { color: "#fff", fontWeight: "600", textAlign: "center" },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Touch targets smaller than \~44×44 pt.
* Wrapping `Text` alone without Pressable when you need a button role.
* Nested pressables stealing taps — flatten or use `pointerEvents`.

## 🔗 Related [#-related]

* [gesture.md](/docs/react-native/gesture) — advanced gestures
* [accesebility.md](/docs/react-native/accesebility) — roles / labels
* [basic\_primitives.md](/docs/react-native/basic-primitives) — Text / View
* [animation.md](/docs/react-native/animation) — press animations


# Transition (/docs/react-native/transition)



# Transition [#transition]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Transitions animate between UI states or screens. Use navigator transition configs, `Animated` / Reanimated shared element patterns, or simple mount/unmount fades.

## 🔧 Core concepts [#-core-concepts]

* **Stack transitions** — slide, fade, modal presentation (React Navigation / native stack).
* **LayoutAnimation** — animate flex layout changes after state updates.
* **Shared values** — Reanimated for interactive, interruptible transitions.
* **Presence** — delay unmount until exit animation finishes.
* **Native stack** — best performance; limited custom interpolation vs JS stack.

## 💡 Examples [#-examples]

```tsx
import { createNativeStackNavigator } from "@react-navigation/native-stack";

const Stack = createNativeStackNavigator();

export function RootStack() {
  return (
    <Stack.Navigator
      screenOptions={{
        animation: "slide_from_right",
        fullScreenGestureEnabled: true,
      }}
    >
      <Stack.Screen name="Home" component={Home} />
      <Stack.Screen
        name="Details"
        component={Details}
        options={{ animation: "fade_from_bottom", presentation: "modal" }}
      />
    </Stack.Navigator>
  );
}
```

```tsx
import { LayoutAnimation, Platform, UIManager, Pressable } from "react-native";

if (Platform.OS === "android" && UIManager.setLayoutAnimationEnabledExperimental) {
  UIManager.setLayoutAnimationEnabledExperimental(true);
}

function toggle(setOpen: (fn: (v: boolean) => boolean) => void) {
  LayoutAnimation.configureNext(LayoutAnimation.Presets.easeInEaseOut);
  setOpen((v) => !v);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Heavy JS transitions dropping frames — prefer native stack / Reanimated.
* Animating during rapid navigation spam without cancellation.
* Forgetting Android LayoutAnimation experimental flag on older RN.

## 🔗 Related [#-related]

* [animation.md](/docs/react-native/animation) — Animated / Reanimated
* [drawer.md](/docs/react-native/drawer) — drawer motion
* [modal.md](/docs/react-native/modal) — modal presentation
* [gesture.md](/docs/react-native/gesture) — interactive pops


# Vibration (/docs/react-native/vibration)



# Vibration [#vibration]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`Vibration` triggers the device vibrator for tactile feedback. Simple on Android/iOS; patterns are mainly Android. For richer feedback on iOS, prefer **Expo Haptics** / native haptics APIs.

## 🔧 Core concepts [#-core-concepts]

| API                          | Role                                    |
| ---------------------------- | --------------------------------------- |
| `Vibration.vibrate()`        | Default buzz                            |
| `Vibration.vibrate(ms)`      | Duration (Android)                      |
| `Vibration.vibrate(pattern)` | Android pattern `[wait, buzz, …]`       |
| `Vibration.cancel()`         | Stop                                    |
| iOS                          | Duration often ignored; pattern limited |

Permissions: generally none for basic vibrate; respect user settings.

## 💡 Examples [#-examples]

```tsx
import { Vibration, Pressable, Text, Platform } from "react-native";

export function BuzzButton() {
  return (
    <Pressable
      onPress={() => {
        if (Platform.OS === "android") {
          Vibration.vibrate([0, 50, 40, 50]);
        } else {
          Vibration.vibrate();
        }
      }}
    >
      <Text>Buzz</Text>
    </Pressable>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Overusing vibration → annoying / battery drain.
* Expecting Android patterns to feel identical on iOS.
* Using Vibration when Haptics impact/selection is more appropriate.
* Not cancelling long patterns on unmount.

## 🔗 Related [#-related]

* [haptics.md](/docs/react-native/haptics) — Expo/iOS-quality haptics
* [pressable.md](/docs/react-native/pressable) — press feedback
* [alert.md](/docs/react-native/alert) — confirmations
* [platform\_specific.md](/docs/react-native/platform-specific) — Platform
* [accesebility.md](/docs/react-native/accesebility) — reduce motion / feedback


# Widget (/docs/react-native/widget)



# Widget [#widget]

*React Native · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Home-screen widgets are **native** (WidgetKit on iOS, App Widgets on Android). React Native doesn’t render them directly — share data via App Groups / a native module, or use libraries that bridge widget timelines.

## 🔧 Core concepts [#-core-concepts]

* **Native UI** — SwiftUI / RemoteViews; JS updates data, not the widget tree each frame.
* **Data bridge** — UserDefaults App Group, SharedPreferences, or a small native module.
* **Expo** — config plugins / custom native code (dev client or prebuild); limited Expo Go support.
* **Update cadence** — system-controlled refresh budgets; don’t expect real-time RN re-renders.
* **Deep link** — widget taps open the app via URL scheme.

## 💡 Examples [#-examples]

```tsx
// Conceptual: write shared state the native widget reads
import AsyncStorage from "@react-native-async-storage/async-storage";
// Prefer a native module that writes to App Group / SharedPreferences:
// await WidgetBridge.setData({ streak: 5 });

export async function syncWidgetPayload(streak: number) {
  await AsyncStorage.setItem("widget/streak", String(streak));
  // Native side: read key and reload timelines (WidgetCenter / updateAppWidget)
}
```

```swift
// iOS sketch — TimelineProvider reads App Group
// UserDefaults(suiteName: "group.com.example.app")?.integer(forKey: "streak")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Expecting full RN components inside the widget — not supported.
* Over-refreshing timelines → OS throttles updates.
* Missing App Group / package entitlements in Expo config plugins.

## 🔗 Related [#-related]

* [deeplinking.md](/docs/react-native/deeplinking) — open app from widget
* [storage.md](/docs/react-native/storage) — shared data
* [Expo/plugins.md](/docs/react-native/expo/plugins) — native extensions
* [Expo/build.md](/docs/react-native/expo/build) — native builds


# Aggregate functions (/docs/sql/aggregate)



# Aggregate functions [#aggregate-functions]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Aggregates compute a single value from a set of rows: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, plus dialect extras (`STRING_AGG` / `GROUP_CONCAT`, `BOOL_AND`). Combine with `GROUP BY` and filter groups with `HAVING`.

## 🔧 Core concepts [#-core-concepts]

* **COUNT(\*)** — rows; &#x2A;*COUNT(col)** — non-NULL values; &#x2A;*COUNT(DISTINCT col)**.
* **NULL** — most aggregates ignore NULL inputs; `SUM` of no rows → NULL.
* **GROUP BY** — one result row per group key.
* **FILTER** — Postgres: `COUNT(*) FILTER (WHERE …)`.
* **Window vs aggregate** — windows keep row detail; aggregates collapse rows.

## 💡 Examples [#-examples]

```sql
SELECT
  status,
  COUNT(*) AS n,
  COUNT(DISTINCT customer_id) AS customers,
  SUM(total) AS revenue,
  AVG(total) AS avg_total,
  MIN(created_at) AS first_at,
  MAX(created_at) AS last_at
FROM orders
GROUP BY status;

-- Postgres FILTER
SELECT
  COUNT(*) FILTER (WHERE status = 'paid') AS paid,
  COUNT(*) FILTER (WHERE status = 'refunded') AS refunded
FROM orders;

-- Postgres string agg / MySQL group_concat
SELECT customer_id, STRING_AGG(sku, ', ' ORDER BY sku) AS skus   -- Postgres
FROM order_items
GROUP BY customer_id;
-- MySQL: GROUP_CONCAT(sku ORDER BY sku SEPARATOR ', ')
```

## ⚠️ Pitfalls [#️-pitfalls]

* `AVG` of integers may be integer division in some modes — cast to numeric/decimal.
* `SUM`/`AVG` over empty set return NULL, not 0 — use `COALESCE`.
* Mixing aggregated and non-aggregated columns without `GROUP BY` errors (strict modes).
* `COUNT(DISTINCT …)` can be expensive on large tables.
* Distinct aggregates + multiple distincts are costly — consider approximate methods.

## 🔗 Related [#-related]

* [distinct\_group\_by.md](/docs/sql/distinct-group-by)
* [where\_having.md](/docs/sql/where-having)
* [window\_functions.md](/docs/sql/window-functions)
* [nulls.md](/docs/sql/nulls)
* [select.md](/docs/sql/select)
* [functions\_builtin.md](/docs/sql/functions-builtin)


# Constraints (/docs/sql/constraints)



# Constraints [#constraints]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Constraints enforce data integrity: `PRIMARY KEY`, `UNIQUE`, `NOT NULL`, `CHECK`, `FOREIGN KEY`, and defaults. Prefer declarative constraints over application-only checks so every client is covered.

## 🔧 Core concepts [#-core-concepts]

| Constraint    | Guarantees                                         |
| ------------- | -------------------------------------------------- |
| `PRIMARY KEY` | Unique + NOT NULL (one per table)                  |
| `UNIQUE`      | No duplicate non-NULL sets (NULL handling differs) |
| `NOT NULL`    | Column always present                              |
| `CHECK`       | Row-level predicate                                |
| `FOREIGN KEY` | References parent key                              |
| `DEFAULT`     | Value when omitted on insert                       |

* **Named constraints** — easier to drop/alter in migrations.
* **Deferral** — Postgres can `DEFERRABLE` FKs to end of transaction.

## 💡 Examples [#-examples]

```sql
CREATE TABLE products (
  id         BIGSERIAL PRIMARY KEY,
  sku        TEXT NOT NULL,
  price_cents INTEGER NOT NULL CHECK (price_cents >= 0),
  status     TEXT NOT NULL DEFAULT 'draft',
  CONSTRAINT products_sku_unique UNIQUE (sku),
  CONSTRAINT products_status_chk CHECK (status IN ('draft', 'live', 'archived'))
);

ALTER TABLE products
  ADD CONSTRAINT products_price_positive CHECK (price_cents > 0);

ALTER TABLE products DROP CONSTRAINT products_status_chk;

-- Composite unique
CREATE TABLE memberships (
  user_id BIGINT NOT NULL,
  org_id  BIGINT NOT NULL,
  PRIMARY KEY (user_id, org_id)
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* MySQL `CHECK` was ignored before 8.0.16 — verify engine/version.
* Multiple NULLs often allowed in `UNIQUE` (Postgres); MySQL/InnoDB unique NULL behavior differs by version.
* Disabling constraints for bulk load must be re-validated afterward.
* Application validation ≠ database constraint — race conditions need DB enforcement.
* Overly strict `CHECK` can block legitimate historical data migrations.

## 🔗 Related [#-related]

* [foreign\_keys.md](/docs/sql/foreign-keys)
* [create\_alter\_drop.md](/docs/sql/create-alter-drop)
* [nulls.md](/docs/sql/nulls)
* [indexes.md](/docs/sql/indexes)
* [data\_types.md](/docs/sql/data-types)
* [normalization.md](/docs/sql/normalization)


# CREATE, ALTER, DROP (/docs/sql/create-alter-drop)



# CREATE, ALTER, DROP [#create-alter-drop]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

DDL statements define and change schema objects: tables, columns, indexes, and constraints. Prefer additive, reversible migrations. Dialects differ in types, `IF EXISTS`, and online `ALTER` support (Postgres vs MySQL).

## 🔧 Core concepts [#-core-concepts]

* **CREATE** — tables, indexes, views, schemas.
* **ALTER** — add/drop/rename columns, constraints, defaults.
* **DROP** — remove objects; `CASCADE` / `RESTRICT` control dependents.
* **IF EXISTS / IF NOT EXISTS** — idempotent DDL (widely supported).
* **Transactions** — Postgres DDL is transactional; MySQL DDL often commits implicitly.

## 💡 Examples [#-examples]

```sql
CREATE TABLE users (
  id           BIGSERIAL PRIMARY KEY,          -- Postgres
  -- id BIGINT AUTO_INCREMENT PRIMARY KEY,    -- MySQL
  email        VARCHAR(255) NOT NULL UNIQUE,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

ALTER TABLE users
  ADD COLUMN display_name VARCHAR(120),
  ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT TRUE;

ALTER TABLE users RENAME COLUMN display_name TO name;  -- Postgres
-- MySQL: CHANGE/RENAME COLUMN syntax variants by version

ALTER TABLE users DROP COLUMN is_active;

DROP TABLE IF EXISTS sessions;
DROP TABLE old_events CASCADE;  -- also drops dependent views/FKs (careful)
```

```sql
CREATE INDEX CONCURRENTLY idx_users_email ON users (email);  -- Postgres online
-- MySQL: CREATE INDEX … (locks vary by version/engine)
```

## ⚠️ Pitfalls [#️-pitfalls]

* `DROP … CASCADE` can wipe far more than the target table.
* MySQL `ALTER` may rebuild tables and lock writes — plan maintenance windows.
* Changing column types can rewrite data and fail on incompatible values.
* Forgetting `NOT NULL` / defaults on new columns breaks existing row inserts.
* Don’t mix manual DDL with migration tools without a single source of truth.

## 🔗 Related [#-related]

* [constraints.md](/docs/sql/constraints)
* [data\_types.md](/docs/sql/data-types)
* [indexes.md](/docs/sql/indexes)
* [foreign\_keys.md](/docs/sql/foreign-keys)
* [schemas.md](/docs/sql/schemas)
* [views.md](/docs/sql/views)


# CTEs (WITH queries) (/docs/sql/cte)



# CTEs (WITH queries) [#ctes-with-queries]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Common Table Expressions (`WITH`) name subqueries for the main statement — clearer than nested derived tables. Postgres supports recursive CTEs well; MySQL 8+ supports recursive CTEs too. Use for multi-step transforms and graph/hierarchy walks.

## 🔧 Core concepts [#-core-concepts]

* **Non-recursive** — `WITH a AS (…), b AS (…) SELECT …`.
* **Recursive** — `WITH RECURSIVE` anchor + recursive member `UNION ALL`.
* **Scope** — CTEs visible to the final statement (and later CTEs).
* **Materialization** — optimizers may inline or materialize (Postgres hints/`MATERIALIZED`).
* **DML** — `WITH … INSERT/UPDATE/DELETE` in many engines.

## 💡 Examples [#-examples]

```sql
WITH paid AS (
  SELECT customer_id, SUM(total) AS revenue
  FROM orders
  WHERE status = 'paid'
  GROUP BY customer_id
),
big AS (
  SELECT * FROM paid WHERE revenue > 1000
)
SELECT u.email, b.revenue
FROM big b
JOIN users u ON u.id = b.customer_id
ORDER BY b.revenue DESC;

-- Recursive org tree (Postgres / MySQL 8+)
WITH RECURSIVE tree AS (
  SELECT id, manager_id, name, 1 AS depth
  FROM employees
  WHERE manager_id IS NULL
  UNION ALL
  SELECT e.id, e.manager_id, e.name, t.depth + 1
  FROM employees e
  JOIN tree t ON e.manager_id = t.id
)
SELECT * FROM tree ORDER BY depth, name;
```

```sql
-- Postgres: force materialize / inline (PG 12+)
WITH cte AS MATERIALIZED (SELECT …) …
```

## ⚠️ Pitfalls [#️-pitfalls]

* Recursive CTEs without a termination condition can loop — add depth guards.
* Multiple references to a CTE may be recomputed or materialized — check `EXPLAIN`.
* CTE ≠ temp table with indexes — heavy reuse may need real temp tables.
* Column lists in recursive unions must match types/count.
* Older MySQL (\<8) lacks CTEs — use derived tables.

## 🔗 Related [#-related]

* [subquery.md](/docs/sql/subquery)
* [select.md](/docs/sql/select)
* [window\_functions.md](/docs/sql/window-functions)
* [views.md](/docs/sql/views)
* [explain\_analyze.md](/docs/sql/explain-analyze)
* [joins.md](/docs/sql/joins)


# Data types (/docs/sql/data-types)



# Data types [#data-types]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Choose types that match domain constraints and indexing needs. Prefer precise numerics for money, `TIMESTAMPTZ` for instants (Postgres), and explicit character types. Dialects differ: Postgres `TEXT`/`JSONB` vs MySQL `VARCHAR`/`JSON`.

## 🔧 Core concepts [#-core-concepts]

| Category | Postgres                                | MySQL (typical)           |
| -------- | --------------------------------------- | ------------------------- |
| Integers | `SMALLINT`/`INT`/`BIGINT`               | same names                |
| Serial   | `GENERATED … AS IDENTITY` / `BIGSERIAL` | `AUTO_INCREMENT`          |
| Decimal  | `NUMERIC(p,s)`                          | `DECIMAL(p,s)`            |
| Float    | `REAL`/`DOUBLE PRECISION`               | `FLOAT`/`DOUBLE`          |
| String   | `TEXT`, `VARCHAR(n)`                    | `VARCHAR(n)`, `TEXT`      |
| Time     | `TIMESTAMPTZ`, `DATE`                   | `DATETIME`, `TIMESTAMP`   |
| Bool     | `BOOLEAN`                               | `TINYINT(1)` / `BOOLEAN`  |
| JSON     | `JSONB`                                 | `JSON`                    |
| UUID     | `UUID`                                  | `BINARY(16)` / `CHAR(36)` |

## 💡 Examples [#-examples]

```sql
-- Postgres
CREATE TABLE payments (
  id           BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  amount       NUMERIC(12, 2) NOT NULL,
  currency     CHAR(3) NOT NULL,
  paid_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  meta         JSONB NOT NULL DEFAULT '{}'::jsonb,
  external_id  UUID UNIQUE
);

-- MySQL
CREATE TABLE payments (
  id           BIGINT AUTO_INCREMENT PRIMARY KEY,
  amount       DECIMAL(12, 2) NOT NULL,
  currency     CHAR(3) NOT NULL,
  paid_at      DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
  meta         JSON NOT NULL,
  external_id  CHAR(36) UNIQUE
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Floating point for money causes rounding bugs — use `NUMERIC`/`DECIMAL`.
* MySQL `TIMESTAMP` converts to session time zone; `DATETIME` does not — be explicit.
* Oversized `VARCHAR` still has limits/row size issues in MySQL indexes.
* Storing enums as free `TEXT` without constraints invites junk values.
* Changing types on large tables can rewrite storage and lock (plan migrations).

## 🔗 Related [#-related]

* [create\_alter\_drop.md](/docs/sql/create-alter-drop)
* [constraints.md](/docs/sql/constraints)
* [functions\_builtin.md](/docs/sql/functions-builtin)
* [schemas.md](/docs/sql/schemas)
* [nulls.md](/docs/sql/nulls)
* [indexes.md](/docs/sql/indexes)


# DISTINCT and GROUP BY (/docs/sql/distinct-group-by)



# DISTINCT and GROUP BY [#distinct-and-group-by]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`DISTINCT` removes duplicate result rows. `GROUP BY` collapses rows by key and pairs with aggregates. Don’t use `DISTINCT` to paper over bad joins — fix the join or group explicitly.

## 🔧 Core concepts [#-core-concepts]

* **SELECT DISTINCT** — unique across the selected expression list.
* **DISTINCT ON** — Postgres: first row per expressions (needs matching `ORDER BY`).
* **GROUP BY** — group keys; other selected columns must be aggregated (strict SQL).
* **Functional dependency** — Postgres may allow PK columns when grouping by PK.
* **GROUPING SETS / ROLLUP / CUBE** — multiple groupings in one pass (dialect support varies).

## 💡 Examples [#-examples]

```sql
SELECT DISTINCT country FROM users;

SELECT customer_id, COUNT(*) AS orders
FROM orders
GROUP BY customer_id;

-- Postgres DISTINCT ON (latest order per customer)
SELECT DISTINCT ON (customer_id)
  customer_id, id, created_at, total
FROM orders
ORDER BY customer_id, created_at DESC;

-- MySQL equivalent pattern: window or join to max(created_at)

SELECT region, status, COUNT(*)
FROM orders
GROUP BY ROLLUP (region, status);  -- Postgres; MySQL has WITH ROLLUP
```

## ⚠️ Pitfalls [#️-pitfalls]

* `SELECT DISTINCT a, b` is not “distinct a” — uniqueness is on the whole row.
* `ONLY_FULL_GROUP_BY` (MySQL) rejects ambiguous non-aggregated columns.
* `DISTINCT` + `ORDER BY` expressions not in select list can error.
* Using `DISTINCT` to fix row multiplication from joins hides cardinality bugs.
* `COUNT(DISTINCT x)` vs `DISTINCT` then `COUNT` — different plans/costs.

## 🔗 Related [#-related]

* [aggregate.md](/docs/sql/aggregate)
* [where\_having.md](/docs/sql/where-having)
* [select.md](/docs/sql/select)
* [order\_limit.md](/docs/sql/order-limit)
* [window\_functions.md](/docs/sql/window-functions)
* [joins.md](/docs/sql/joins)


# EXPLAIN and ANALYZE (/docs/sql/explain-analyze)



# EXPLAIN and ANALYZE [#explain-and-analyze]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`EXPLAIN` shows the optimizer’s plan; `EXPLAIN ANALYZE` (Postgres) / `EXPLAIN ANALYZE` (MySQL 8.0.18+) executes the query and reports actual timings/rows. Use it to find sequential scans, bad join order, and misestimates.

## 🔧 Core concepts [#-core-concepts]

* **Nodes** — seq scan, index scan, nested loop, hash join, sort, aggregate.
* **Estimates vs actual** — large gaps ⇒ stale stats or correlated columns.
* **Buffers / IO** — Postgres `BUFFERS`; track hot reads.
* **Format** — `JSON`/`TEXT`/`YAML` (Postgres); tree vs traditional (MySQL).
* **Stats** — `ANALYZE` table (Postgres) / `ANALYZE TABLE` (MySQL) refresh stats.

## 💡 Examples [#-examples]

```sql
-- Postgres
EXPLAIN SELECT * FROM orders WHERE customer_id = 42;
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.*
FROM orders o
JOIN users u ON u.id = o.user_id
WHERE o.created_at >= NOW() - INTERVAL '7 days';

ANALYZE orders;  -- refresh statistics
```

```sql
-- MySQL
EXPLAIN SELECT * FROM orders WHERE customer_id = 42;
EXPLAIN ANALYZE
SELECT * FROM orders WHERE customer_id = 42;
ANALYZE TABLE orders;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `EXPLAIN ANALYZE` runs the query — careful with writes/`UPDATE`/`DELETE` (use transactions + rollback where possible).
* Reading only estimated rows without ANALYZE misleads on skewed data.
* Missing indexes show as seq scans — confirm selectivity before indexing everything.
* Parameterized app queries may get different plans than literal `EXPLAIN` — use actual params.
* Caching effects make second runs look faster — warm vs cold cache matters.

## 🔗 Related [#-related]

* [indexes.md](/docs/sql/indexes)
* [select.md](/docs/sql/select)
* [joins.md](/docs/sql/joins)
* [order\_limit.md](/docs/sql/order-limit)
* [cte.md](/docs/sql/cte)
* [subquery.md](/docs/sql/subquery)


# Foreign keys (/docs/sql/foreign-keys)



# Foreign keys [#foreign-keys]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Foreign keys enforce that values in a child table reference an existing parent key. They document relationships and prevent orphans. Define `ON DELETE` / `ON UPDATE` actions explicitly. Index FK columns for join/delete performance.

## 🔧 Core concepts [#-core-concepts]

* **References** — `FOREIGN KEY (child_col) REFERENCES parent (col)`.
* **Actions** — `NO ACTION`/`RESTRICT`, `CASCADE`, `SET NULL`, `SET DEFAULT`.
* **Composite FKs** — match multi-column parent unique/PK keys.
* **Deferral** — Postgres `DEFERRABLE INITIALLY DEFERRED` checks at commit.
* **Match** — usually `MATCH SIMPLE` (NULLs allowed in FK cols unless NOT NULL).

## 💡 Examples [#-examples]

```sql
CREATE TABLE customers (
  id BIGSERIAL PRIMARY KEY
);

CREATE TABLE orders (
  id BIGSERIAL PRIMARY KEY,
  customer_id BIGINT NOT NULL,
  CONSTRAINT orders_customer_fk
    FOREIGN KEY (customer_id) REFERENCES customers(id)
    ON DELETE RESTRICT
    ON UPDATE CASCADE
);

CREATE INDEX orders_customer_id_idx ON orders (customer_id);

-- Cascade delete children
ALTER TABLE order_items
  ADD CONSTRAINT order_items_order_fk
  FOREIGN KEY (order_id) REFERENCES orders(id)
  ON DELETE CASCADE;

-- Soft-friendly: SET NULL
ALTER TABLE posts
  ADD CONSTRAINT posts_author_fk
  FOREIGN KEY (author_id) REFERENCES users(id)
  ON DELETE SET NULL;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing indexes on FK columns make `ON DELETE` / joins slow (especially Postgres).
* `ON DELETE CASCADE` can wipe large subgraphs — prefer explicit deletes in app code for critical data.
* MySQL: FKs require InnoDB; type/signedness must match parent exactly.
* Circular FKs need deferred checks or staged inserts.
* Orphan prevention doesn’t replace soft-delete policies — decide deleted parent behavior.

## 🔗 Related [#-related]

* [constraints.md](/docs/sql/constraints)
* [normalization.md](/docs/sql/normalization)
* [indexes.md](/docs/sql/indexes)
* [create\_alter\_drop.md](/docs/sql/create-alter-drop)
* [insert\_update\_delete.md](/docs/sql/insert-update-delete)
* [joins.md](/docs/sql/joins)


# Built-in functions (/docs/sql/functions-builtin)



# Built-in functions [#built-in-functions]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

SQL provides scalar functions for strings, numbers, dates, JSON, and conditionals. Names and behavior differ across Postgres and MySQL — verify docs for edge cases (`ILIKE`, `DATE_TRUNC`, `IFNULL` vs `COALESCE`).

## 🔧 Core concepts [#-core-concepts]

| Area        | Common functions                                                                  |
| ----------- | --------------------------------------------------------------------------------- |
| String      | `CONCAT`, `LENGTH`/`CHAR_LENGTH`, `SUBSTRING`, `TRIM`, `REPLACE`, `LOWER`/`UPPER` |
| Numeric     | `ABS`, `ROUND`, `CEIL`/`FLOOR`, `MOD`, `POWER`                                    |
| Date/time   | `NOW`/`CURRENT_TIMESTAMP`, `DATE_TRUNC` (PG), `DATE_FORMAT` (MySQL), `AGE`        |
| Conditional | `COALESCE`, `NULLIF`, `CASE`, `GREATEST`/`LEAST`                                  |
| JSON        | `->`/`->>` (PG), `JSON_EXTRACT` (MySQL)                                           |
| Cast        | `CAST(x AS type)`, `x::type` (Postgres)                                           |

## 💡 Examples [#-examples]

```sql
SELECT
  LOWER(email) AS email_norm,
  CONCAT(first_name, ' ', last_name) AS full_name,
  ROUND(price * 1.1, 2) AS with_tax,
  COALESCE(nickname, first_name) AS label
FROM users;

-- Postgres dates
SELECT DATE_TRUNC('day', created_at) AS day, COUNT(*)
FROM events
GROUP BY 1;

-- MySQL dates
SELECT DATE_FORMAT(created_at, '%Y-%m-%d') AS day, COUNT(*)
FROM events
GROUP BY day;

SELECT CASE
  WHEN total >= 100 THEN 'gold'
  WHEN total >= 50 THEN 'silver'
  ELSE 'bronze'
END AS tier
FROM orders;

-- Postgres JSON
SELECT payload->>'userId' AS user_id FROM events;
-- MySQL: JSON_UNQUOTE(JSON_EXTRACT(payload, '$.userId'))
```

## ⚠️ Pitfalls [#️-pitfalls]

* `LENGTH` in Postgres is bytes for `bytea` / sometimes confusing with multibyte — prefer `CHAR_LENGTH` for characters.
* Implicit casts hide type bugs — prefer explicit `CAST`.
* Time zones: `TIMESTAMP` vs `TIMESTAMPTZ` (Postgres) — store UTC consciously.
* MySQL `ONLY_FULL_GROUP_BY` interacts with select-list functions + aliases.
* Non-immutable functions in indexes/generated columns may be disallowed.

## 🔗 Related [#-related]

* [data\_types.md](/docs/sql/data-types)
* [aggregate.md](/docs/sql/aggregate)
* [nulls.md](/docs/sql/nulls)
* [select.md](/docs/sql/select)
* [where\_having.md](/docs/sql/where-having)
* [window\_functions.md](/docs/sql/window-functions)


# Getting Started with SQL (/docs/sql/getting-started)



# Getting Started with SQL [#getting-started-with-sql]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

SQL (Structured Query Language) is how you talk to relational databases: create tables, insert rows, and query data. Dialects (PostgreSQL, MySQL, SQLite, SQL Server) share a core language with small differences.

## 🔧 Core concepts [#-core-concepts]

| Idea           | Meaning                              |
| -------------- | ------------------------------------ |
| Database       | Named collection of schemas/tables   |
| Table          | Rows + named columns                 |
| Row / record   | One entry                            |
| Column / field | One attribute with a data type       |
| Query          | Statement that reads or changes data |
| Primary key    | Uniquely identifies a row            |

Beginners often practice on **SQLite** (a file DB) or a free Postgres instance.

## 💡 Examples [#-examples]

**SQLite quick start:**

```shellscript
sqlite3 practice.db
```

```sql
SELECT 'Hello, SQL!' AS message;
```

**Create a tiny table and query it:**

```sql
CREATE TABLE friends (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL
);

INSERT INTO friends (name) VALUES ('Ada'), ('Grace');
SELECT * FROM friends;
```

**Filter rows:**

```sql
SELECT name
FROM friends
WHERE name LIKE 'A%';
```

## ⚠️ Pitfalls [#️-pitfalls]

* SQL keywords are case-insensitive by convention; `SELECT` vs `select` both work.
* String quotes are single quotes in standard SQL: `'Ada'`, not `"Ada"` (double quotes often mean identifiers).
* Each dialect has quirks (`AUTOINCREMENT`, `SERIAL`, `LIMIT` vs `TOP`).
* Never paste untrusted input into SQL strings — use parameterized queries in apps.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/sql/hello-world)
* [tables\_basics.md](/docs/sql/tables-basics)
* [primary\_keys\_basics.md](/docs/sql/primary-keys-basics)
* [null\_basics.md](/docs/sql/null-basics)


# Glossary (/docs/sql/glossary)



# Glossary [#glossary]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core SQL terms for querying, schema design, transactions, and relational database concepts.

## 🔧 Core concepts [#-core-concepts]

| Term            | Definition                                                                         |
| --------------- | ---------------------------------------------------------------------------------- |
| Aggregate       | A function that summarizes many rows into one value, such as `COUNT` or `SUM`.     |
| Alias           | A temporary name for a table or column using `AS`.                                 |
| Constraint      | A rule enforcing data integrity, such as `NOT NULL`, `UNIQUE`, or `CHECK`.         |
| CTE             | A Common Table Expression defined with `WITH` as a named subquery.                 |
| DDL             | Data Definition Language statements like `CREATE`, `ALTER`, and `DROP`.            |
| DML             | Data Manipulation Language statements like `SELECT`, `INSERT`, `UPDATE`, `DELETE`. |
| Foreign key     | A column referencing a primary key in another table.                               |
| Group by        | A clause that clusters rows so aggregates compute per group.                       |
| Having          | A filter applied after aggregation, unlike `WHERE` which filters rows first.       |
| Index           | A data structure that speeds lookups at the cost of write overhead.                |
| Join            | Combining rows from two tables based on a related column condition.                |
| Normalization   | Organizing tables to reduce redundancy and improve integrity.                      |
| Null            | A marker for missing or unknown data, not equal to any value including itself.     |
| Order by        | A clause that sorts the result set by one or more expressions.                     |
| Primary key     | A unique, non-null identifier for each row in a table.                             |
| Schema          | The namespace/structure of tables, types, and constraints in a database.           |
| Select          | The statement that retrieves rows and columns from tables or views.                |
| Subquery        | A query nested inside another statement’s `FROM`, `WHERE`, or `SELECT`.            |
| Table           | A named relation storing rows with a fixed set of columns.                         |
| Transaction     | A unit of work that commits or rolls back as a whole (ACID).                       |
| Trigger         | Procedural code that runs automatically on insert/update/delete events.            |
| Union           | Combining result sets of compatible queries into one set of rows.                  |
| Upsert          | Insert-or-update behavior, often via `ON CONFLICT` or `MERGE`.                     |
| View            | A stored query presented as a virtual table.                                       |
| Where           | A clause that filters rows before grouping.                                        |
| Window function | A function that computes across related rows without collapsing them.              |

## 💡 Examples [#-examples]

**Select, where, and join:**

```sql
SELECT u.name, o.total
FROM users AS u
JOIN orders AS o ON o.user_id = u.id
WHERE o.total > 100
ORDER BY o.total DESC;
```

**CTE and window function:**

```sql
WITH ranked AS (
  SELECT name, salary,
         RANK() OVER (PARTITION BY dept_id ORDER BY salary DESC) AS rnk
  FROM employees
)
SELECT * FROM ranked WHERE rnk <= 3;
```

**Transaction:**

```sql
BEGIN;
UPDATE accounts SET balance = balance - 50 WHERE id = 1;
UPDATE accounts SET balance = balance + 50 WHERE id = 2;
COMMIT;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **WHERE** (pre-aggregate filter) with **HAVING** (post-aggregate filter).
* Mixing **INNER JOIN** and **LEFT JOIN** expectations about unmatched rows.
* Treating **NULL** like a value — use `IS NULL`, not `= NULL`.
* Equating a **view** with a physical table — views are stored queries (unless materialized).
* Assuming **UNION** and **UNION ALL** are identical — `UNION` deduplicates.

## 🔗 Related [#-related]

* [select](/docs/sql/select)
* [joins](/docs/sql/joins)
* [cte](/docs/sql/cte)
* [transactions](/docs/sql/transactions)
* [window\_functions](/docs/sql/window-functions)
* [where\_having](/docs/sql/where-having)


# Hello World (/docs/sql/hello-world)



# Hello World [#hello-world]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

SQL Hello World is usually a `SELECT` that returns a constant, or creating a one-column table and reading it back. It proves your client can connect and run statements.

## 🔧 Core concepts [#-core-concepts]

| Piece      | Role                                  |
| ---------- | ------------------------------------- |
| `SELECT`   | Read data / expressions               |
| `AS`       | Alias a column name in the result     |
| Statement  | One SQL command (often ends with `;`) |
| Result set | Table-like output of a query          |

Many tools (sqlite3, psql, GUI clients) show results as a grid.

## 💡 Examples [#-examples]

**Constant select:**

```sql
SELECT 'Hello, World!' AS greeting;
```

**Math and aliases:**

```sql
SELECT 2 + 2 AS four;
SELECT 'Ada' AS name, 1815 AS birth_year;
```

**Round-trip with a table (SQLite-friendly):**

```sql
CREATE TABLE hello (
  id INTEGER PRIMARY KEY,
  message TEXT NOT NULL
);

INSERT INTO hello (message) VALUES ('Hello, World!');
SELECT message FROM hello;
```

**Current time (Postgres example):**

```sql
SELECT NOW() AS right_now;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `;` in interactive clients that require it.
* Connecting to the wrong database/schema and thinking the query “failed.”
* `SELECT *` is fine for learning; be specific in real apps.
* Dialect functions differ (`NOW()`, `datetime('now')`, `GETDATE()`).

## 🔗 Related [#-related]

* [getting\_started.md](/docs/sql/getting-started)
* [tables\_basics.md](/docs/sql/tables-basics)
* [primary\_keys\_basics.md](/docs/sql/primary-keys-basics)
* [null\_basics.md](/docs/sql/null-basics)


# SQL (/docs/sql)



# SQL [#sql]

Queries, schema, advanced SQL.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# Indexes (/docs/sql/indexes)



# Indexes [#indexes]

**SQL · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Indexes speed lookups, joins, and sorts by maintaining ordered structures (commonly B-trees) over column values. They trade write overhead and storage for faster reads. Design indexes around real query predicates and join keys.

## 🧩 Core concepts [#-core-concepts]

* **B-tree** — default for equality and range (`=`, `&lt;`, `BETWEEN`, `ORDER BY`).
* **Unique / PK / FK** — uniqueness constraints create indexes; FKs often need supporting indexes on the child column.
* **Composite indexes** — leftmost prefix rule: `(a, b)` helps `a` and `a,b`, not `b` alone.
* **Covering / INCLUDE** — index-only scans when all needed columns are in the index.
* **Partial / filtered** — index a subset (`WHERE deleted_at IS NULL`).
* **Hash / GIN / GiST / columnstore** — engine-specific for equality-only, JSON, full-text, analytics.

## 💡 Examples [#-examples]

```sql
-- Single-column
CREATE INDEX idx_users_email ON users (email);

-- Unique
CREATE UNIQUE INDEX ux_users_email ON users (email);

-- Composite (status filtered lists by created_at)
CREATE INDEX idx_orders_status_created
  ON orders (status, created_at DESC);

-- Partial (PostgreSQL)
CREATE INDEX idx_users_active_email
  ON users (email)
  WHERE active = TRUE;

-- Covering-ish with INCLUDE (PostgreSQL)
CREATE INDEX idx_orders_user_covering
  ON orders (user_id)
  INCLUDE (status, total);

-- Inspect (examples)
-- PostgreSQL: EXPLAIN ANALYZE SELECT …;
-- MySQL:      EXPLAIN SELECT …;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Too many indexes slow `INSERT`/`UPDATE`/`DELETE` and bloat storage.
* Functions on columns (`WHERE LOWER(email) = …`) need matching expression indexes.
* Low-selectivity columns (`boolean`) rarely help alone — combine with selective columns.
* Unused indexes still cost writes — review with engine stats (`pg_stat_user_indexes`, etc.).

## 🔗 Related [#-related]

* [Select](/docs/sql/select)
* [Joins](/docs/sql/joins)
* [Transactions](/docs/sql/transactions)
* [Insert / Update / Delete](/docs/sql/insert-update-delete)


# Insert, Update, Delete (/docs/sql/insert-update-delete)



# Insert, Update, Delete [#insert-update-delete]

**SQL · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Data-modification statements change table contents: `INSERT` adds rows, `UPDATE` changes existing values, `DELETE` removes rows. Always scope `UPDATE`/`DELETE` with a precise `WHERE` (or use transactions and `RETURNING` where supported).

## 🧩 Core concepts [#-core-concepts]

* **INSERT** — single row, multi-row, or `INSERT … SELECT`.
* **UPSERT** — `ON CONFLICT` (Postgres) / `ON DUPLICATE KEY` (MySQL) / `MERGE`.
* **UPDATE** — set columns; optional `FROM`/`JOIN` in some dialects.
* **DELETE** — remove matching rows; `TRUNCATE` is bulk and minimally logged (dialect-specific).
* **RETURNING** — get affected rows back (Postgres, SQLite, …).
* **Constraints** — PK/FK/UNIQUE/CHECK can reject writes.

## 💡 Examples [#-examples]

```sql
-- Insert
INSERT INTO users (email, name)
VALUES ('ada@example.com', 'Ada');

INSERT INTO users (email, name)
VALUES
  ('al@example.com', 'Al'),
  ('bo@example.com', 'Bo');

INSERT INTO users (email, name)
SELECT email, full_name FROM staging_users
WHERE email IS NOT NULL;

-- Upsert (PostgreSQL)
INSERT INTO settings (user_id, theme)
VALUES (42, 'dark')
ON CONFLICT (user_id)
DO UPDATE SET theme = EXCLUDED.theme, updated_at = NOW();

-- Update
UPDATE orders
SET status = 'shipped', shipped_at = NOW()
WHERE id = 1001 AND status = 'paid'
RETURNING id, status;

-- Delete
DELETE FROM sessions
WHERE expires_at < NOW();

-- Careful bulk clear (cannot easily undo)
-- TRUNCATE TABLE sessions;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `WHERE` on `UPDATE`/`DELETE` can wipe the whole table — run inside a transaction first.
* Multi-row inserts may partially fail depending on constraints and dialect abort behavior.
* Triggers and cascading FKs can delete/update far more than the statement text suggests.
* `TRUNCATE` often cannot run inside the same transactional assumptions as `DELETE` (and may need privileges).

## 🔗 Related [#-related]

* [Select](/docs/sql/select)
* [Transactions](/docs/sql/transactions)
* [Joins](/docs/sql/joins)
* [Indexes](/docs/sql/indexes)


# Joins (/docs/sql/joins)



# Joins [#joins]

**SQL · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Joins combine rows from multiple tables using match conditions. Pick the join type based on whether unmatched rows from either side should appear. Prefer explicit `JOIN … ON` over old comma-style joins.

## 🧩 Core concepts [#-core-concepts]

* **INNER JOIN** — only matching pairs.
* **LEFT / RIGHT JOIN** — keep all rows from one side; pad the other with `NULL`.
* **FULL OUTER JOIN** — keep unmatched rows from both sides (not in MySQL historically).
* **CROSS JOIN** — Cartesian product.
* **Self join** — same table aliased twice (hierarchies, comparisons).
* **Anti/semi patterns** — `NOT EXISTS` / `LEFT JOIN … WHERE right.key IS NULL` for “missing” rows.

## 💡 Examples [#-examples]

```sql
-- Inner
SELECT o.id, u.email, o.total
FROM orders o
INNER JOIN users u ON u.id = o.user_id
WHERE o.status = 'paid';

-- Left: users even without orders
SELECT u.id, u.email, COUNT(o.id) AS order_count
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.id, u.email;

-- Anti-join: users with no orders
SELECT u.*
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE o.id IS NULL;

-- Equivalent anti-join
SELECT u.*
FROM users u
WHERE NOT EXISTS (
  SELECT 1 FROM orders o WHERE o.user_id = u.id
);

-- Multiple joins
SELECT o.id, u.email, p.sku
FROM orders o
JOIN users u ON u.id = o.user_id
JOIN order_items i ON i.order_id = o.id
JOIN products p ON p.id = i.product_id;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Filtering a `LEFT JOIN`ed table in `WHERE` can accidentally turn it into an inner join — put right-side filters in `ON` when you need outer semantics.
* Joining on non-unique keys multiplies rows (fan-out) and inflates aggregates.
* `SELECT *` with joins returns duplicate column names and wide rows.
* NULL-safe equality differs by dialect (`IS NOT DISTINCT FROM` in Postgres).

## 🔗 Related [#-related]

* [Select](/docs/sql/select)
* [Indexes](/docs/sql/indexes)
* [Insert / Update / Delete](/docs/sql/insert-update-delete)
* [Transactions](/docs/sql/transactions)


# Normalization (/docs/sql/normalization)



# Normalization [#normalization]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Normalization structures relational schemas to reduce redundancy and update anomalies (1NF → 2NF → 3NF / BCNF). Practical designs often normalize OLTP schemas and selectively denormalize for read-heavy analytics with clear sync rules.

## 🔧 Core concepts [#-core-concepts]

| Form        | Rule of thumb                                  |
| ----------- | ---------------------------------------------- |
| 1NF         | Atomic cells; no repeating groups              |
| 2NF         | 1NF + no partial dependency on a composite key |
| 3NF         | 2NF + no transitive dependency on non-keys     |
| BCNF        | Every determinant is a candidate key           |
| Denormalize | Controlled copies for performance / UX         |

* **Anomalies** — insert/update/delete anomalies from duplicated facts.
* **Keys** — primary, candidate, foreign keys define dependencies.
* **Join cost** — more normalization → more joins; index FKs.

## 💡 Examples [#-examples]

```plaintext
Bad (unnormalized orders):
order_id | customer_name | customer_email | item1 | item2

Better:
customers(id, name, email)
orders(id, customer_id, created_at)
order_items(order_id, product_id, qty, price_cents)
products(id, sku, title)
```

```sql
-- 3NF-ish: status lookup instead of repeating labels everywhere
CREATE TABLE order_statuses (
  id TEXT PRIMARY KEY,          -- 'paid', 'shipped'
  label TEXT NOT NULL
);

CREATE TABLE orders (
  id BIGSERIAL PRIMARY KEY,
  customer_id BIGINT NOT NULL REFERENCES customers(id),
  status_id TEXT NOT NULL REFERENCES order_statuses(id)
);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Over-normalization can make simple reads painful — balance with access patterns.
* Denormalized caches drift without triggers/jobs/events to refresh them.
* Storing JSON blobs for “flexibility” often recreates 1NF violations inside documents.
* Composite keys without care lead to 2NF violations (attributes of only part of the key).
* Surrogate keys don’t remove the need for unique business keys (`UNIQUE (sku)`).

## 🔗 Related [#-related]

* [foreign\_keys.md](/docs/sql/foreign-keys)
* [constraints.md](/docs/sql/constraints)
* [schemas.md](/docs/sql/schemas)
* [data\_types.md](/docs/sql/data-types)
* [joins.md](/docs/sql/joins)
* [create\_alter\_drop.md](/docs/sql/create-alter-drop)


# NULL Basics (/docs/sql/null-basics)



# NULL Basics [#null-basics]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`NULL` means **unknown / missing**, not the number zero and not an empty string. SQL uses three-valued logic (`TRUE`, `FALSE`, `UNKNOWN`), so comparisons with `NULL` need special operators.

## 🔧 Core concepts [#-core-concepts]

| Idea                      | Detail                    |
| ------------------------- | ------------------------- |
| `NULL`                    | Missing value             |
| `IS NULL` / `IS NOT NULL` | Correct null tests        |
| `=` with NULL             | Yields UNKNOWN, not TRUE  |
| `COALESCE(a, b)`          | First non-null among args |
| `NOT NULL` column         | Disallow missing values   |

Aggregates like `COUNT(column)` ignore nulls; `COUNT(*)` counts rows.

## 💡 Examples [#-examples]

**Insert and test nulls:**

```sql
CREATE TABLE tasks (
  id INTEGER PRIMARY KEY,
  title TEXT NOT NULL,
  due_date TEXT
);

INSERT INTO tasks (title, due_date) VALUES
  ('Write notes', '2026-07-12'),
  ('Review PR', NULL);

SELECT * FROM tasks WHERE due_date IS NULL;
SELECT * FROM tasks WHERE due_date IS NOT NULL;
```

**Why `=` fails:**

```sql
-- Usually returns no rows, even if due_date is NULL
SELECT * FROM tasks WHERE due_date = NULL;
```

**COALESCE for defaults:**

```sql
SELECT
  title,
  COALESCE(due_date, 'No due date') AS due_label
FROM tasks;
```

**Counts:**

```sql
SELECT COUNT(*) AS all_rows,
       COUNT(due_date) AS with_due_date
FROM tasks;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `NULL = NULL` is not true — use `IS NULL`.
* Empty string `''` is not NULL (unless your app treats them the same).
* `NOT IN (SELECT ...)` with nulls in the list can surprise you.
* Nullable foreign keys / optional fields are fine — document the meaning of “missing.”

## 🔗 Related [#-related]

* [tables\_basics.md](/docs/sql/tables-basics)
* [primary\_keys\_basics.md](/docs/sql/primary-keys-basics)
* [nulls.md](/docs/sql/nulls)
* [getting\_started.md](/docs/sql/getting-started)


# NULLs (/docs/sql/nulls)



# NULLs [#nulls]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`NULL` means unknown/missing. Any comparison with `NULL` yields unknown (not true), so filters need `IS NULL` / `IS NOT NULL`. Aggregates, unique constraints, and outer joins all have NULL-specific behavior.

## 🔧 Core concepts [#-core-concepts]

* **Three-valued logic** — TRUE / FALSE / UNKNOWN.
* **IS NULL** — only correct NULL test; `= NULL` never matches.
* **COALESCE / NULLIF** — substitute or nullify values.
* **Aggregates** — ignore NULLs (except `COUNT(*)`).
* **Outer joins** — non-matching side fills NULLs.
* **DISTINCT / UNIQUE** — NULL treatment differs by dialect.

## 💡 Examples [#-examples]

```sql
SELECT * FROM users WHERE deleted_at IS NULL;
SELECT * FROM users WHERE deleted_at IS NOT NULL;

SELECT COALESCE(display_name, email, 'unknown') AS label FROM users;
SELECT NULLIF(trim(name), '') AS name FROM users;  -- '' → NULL

SELECT COUNT(*) AS rows, COUNT(phone) AS with_phone FROM users;

-- NULL-safe equality (Postgres IS NOT DISTINCT FROM)
SELECT * FROM t WHERE a IS NOT DISTINCT FROM b;
-- MySQL: <=> null-safe equals

-- Sort NULLs
SELECT * FROM products ORDER BY rank NULLS LAST;     -- Postgres
-- MySQL: ORDER BY rank IS NULL, rank
```

## ⚠️ Pitfalls [#️-pitfalls]

* `NOT IN (1, 2, NULL)` never returns true — prefer `NOT EXISTS`.
* `UNIQUE` allowing multiple NULLs (Postgres) surprises people from other DBs.
* `OR col = NULL` is always unknown — use `IS NULL`.
* Expressions like `price + tax` become NULL if either is NULL — `COALESCE` to 0 when appropriate.
* CHECK constraints: `CHECK (price > 0)` allows NULL prices unless `NOT NULL`.

## 🔗 Related [#-related]

* [where\_having.md](/docs/sql/where-having)
* [constraints.md](/docs/sql/constraints)
* [aggregate.md](/docs/sql/aggregate)
* [joins.md](/docs/sql/joins)
* [order\_limit.md](/docs/sql/order-limit)
* [distinct\_group\_by.md](/docs/sql/distinct-group-by)


# ORDER BY and LIMIT (/docs/sql/order-limit)



# ORDER BY and LIMIT [#order-by-and-limit]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`ORDER BY` sorts result rows; `LIMIT`/`OFFSET` (or `FETCH FIRST` / `TOP`) page results. Stable pagination needs a deterministic order key. Dialects differ: Postgres/`MySQL` use `LIMIT`; SQL Server uses `TOP`/`OFFSET FETCH`.

## 🔧 Core concepts [#-core-concepts]

* **Sort keys** — columns or expressions; `ASC`/`DESC`; multi-key sorts.
* **NULL order** — Postgres `NULLS FIRST|LAST`; MySQL NULLs first in ASC by default.
* **LIMIT / OFFSET** — `LIMIT count OFFSET skip` (MySQL/Postgres).
* **FETCH** — standard: `OFFSET n ROWS FETCH NEXT m ROWS ONLY`.
* **Determinism** — add unique tie-breaker (e.g. `id`) for stable pages.

## 💡 Examples [#-examples]

```sql
SELECT id, email, created_at
FROM users
ORDER BY created_at DESC, id DESC
LIMIT 20 OFFSET 40;

-- Keyset pagination (preferred over deep OFFSET)
SELECT id, email, created_at
FROM users
WHERE (created_at, id) < ('2026-07-01 12:00:00+00', 12345)
ORDER BY created_at DESC, id DESC
LIMIT 20;

-- Standard FETCH (Postgres)
SELECT * FROM products
ORDER BY price
OFFSET 0 ROWS FETCH NEXT 10 ROWS ONLY;

-- MySQL
SELECT * FROM products ORDER BY price LIMIT 10 OFFSET 0;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Large `OFFSET` is slow — prefer keyset/seek pagination.
* `ORDER BY` without index can sort on disk — check `EXPLAIN`.
* Non-deterministic order without unique keys → duplicate/missing rows across pages.
* Selecting `*` with random order (`ORDER BY random()`) is expensive.
* `LIMIT` without `ORDER BY` returns an arbitrary set.

## 🔗 Related [#-related]

* [select.md](/docs/sql/select)
* [nulls.md](/docs/sql/nulls)
* [indexes.md](/docs/sql/indexes)
* [window\_functions.md](/docs/sql/window-functions)
* [explain\_analyze.md](/docs/sql/explain-analyze)
* [distinct\_group\_by.md](/docs/sql/distinct-group-by)


# Primary Keys Basics (/docs/sql/primary-keys-basics)



# Primary Keys Basics [#primary-keys-basics]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A &#x2A;*primary key (PK)** uniquely identifies each row in a table. Most tables use a single column (often `id`). Databases enforce uniqueness and non-null for primary keys.

## 🔧 Core concepts [#-core-concepts]

| Idea           | Meaning                                               |
| -------------- | ----------------------------------------------------- |
| Uniqueness     | No two rows share the same PK value                   |
| Not null       | PK columns cannot be NULL                             |
| Surrogate key  | Artificial `id` (common)                              |
| Natural key    | Real-world unique value (email, ISBN) — use carefully |
| Auto-increment | DB generates the next id                              |
| Composite key  | PK made of multiple columns                           |

Foreign keys in other tables often reference this primary key.

## 💡 Examples [#-examples]

**Integer primary key (SQLite style):**

```sql
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  email TEXT NOT NULL UNIQUE,
  name TEXT NOT NULL
);

INSERT INTO users (email, name) VALUES
  ('ada@example.com', 'Ada'),
  ('grace@example.com', 'Grace');

SELECT id, email FROM users;
```

**Explicit ids:**

```sql
INSERT INTO users (id, email, name)
VALUES (100, 'linus@example.com', 'Linus');
```

**Composite primary key:**

```sql
CREATE TABLE enrollment (
  student_id INTEGER NOT NULL,
  course_id INTEGER NOT NULL,
  enrolled_on TEXT NOT NULL,
  PRIMARY KEY (student_id, course_id)
);

INSERT INTO enrollment VALUES (1, 10, '2026-01-15');
-- INSERT INTO enrollment VALUES (1, 10, '2026-02-01'); -- would fail
```

**Lookup by primary key:**

```sql
SELECT name FROM users WHERE id = 1;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing primary key values later breaks references — treat ids as stable.
* Using mutable natural keys (email) as PK causes pain when they change.
* Forgetting a PK makes updates/deletes harder and invites duplicate rows.
* Auto-increment behavior and syntax differ (`SERIAL`, `IDENTITY`, `AUTO_INCREMENT`).

## 🔗 Related [#-related]

* [tables\_basics.md](/docs/sql/tables-basics)
* [null\_basics.md](/docs/sql/null-basics)
* [foreign\_keys.md](/docs/sql/foreign-keys)
* [constraints.md](/docs/sql/constraints)


# Schemas (/docs/sql/schemas)



# Schemas [#schemas]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Schemas namespace database objects (tables, views, functions). Postgres uses first-class schemas (`public`, custom); MySQL often treats database = schema. Use schemas to separate domains, tenants (carefully), or extension objects.

## 🔧 Core concepts [#-core-concepts]

* **Qualified names** — `schema.table` (Postgres); `db.table` (MySQL).
* **Search path** — Postgres `search_path` resolves unqualified names.
* **CREATE SCHEMA** — logical grouping; permissions per schema.
* **Ownership** — objects inherit owner; grants are schema + object level.
* **Extensions** — Postgres often installs into dedicated schemas.

## 💡 Examples [#-examples]

```sql
-- Postgres
CREATE SCHEMA app AUTHORIZATION app_user;
CREATE SCHEMA analytics;

CREATE TABLE app.users (
  id BIGSERIAL PRIMARY KEY,
  email TEXT NOT NULL UNIQUE
);

CREATE TABLE analytics.daily_active AS
SELECT CURRENT_DATE AS day, COUNT(*) AS n FROM app.users;

SET search_path TO app, public;
SELECT * FROM users;  -- resolves to app.users

GRANT USAGE ON SCHEMA app TO readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA app TO readonly;

-- MySQL: database as schema
CREATE DATABASE app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE app;
CREATE TABLE users (id BIGINT AUTO_INCREMENT PRIMARY KEY, email VARCHAR(255) NOT NULL);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Unqualified names + surprising `search_path` → wrong table (security risk with `SECURITY DEFINER`).
* Cross-schema FKs need privileges on both schemas.
* Dump/restore tools must include non-`public` schemas explicitly.
* MySQL “schema” wording ≠ Postgres schemas — don’t assume identical DDL.
* Overusing schemas for multi-tenant isolation is harder than row-level tenancy for many apps.

## 🔗 Related [#-related]

* [create\_alter\_drop.md](/docs/sql/create-alter-drop)
* [views.md](/docs/sql/views)
* [stored\_procedures.md](/docs/sql/stored-procedures)
* [permissions via constraints.md](/docs/sql/constraints)
* [normalization.md](/docs/sql/normalization)
* [data\_types.md](/docs/sql/data-types)


# SELECT (/docs/sql/select)



# SELECT [#select]

**SQL · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`SELECT` retrieves rows from one or more tables. Shape results with column lists, filters (`WHERE`), ordering, limits, and aggregates. Prefer explicit column names over `SELECT *` in application queries.

## 🧩 Core concepts [#-core-concepts]

* **Projection** — choose columns, aliases, expressions.
* **Filtering** — `WHERE` (row-level) vs `HAVING` (after `GROUP BY`).
* **Sorting / paging** — `ORDER BY`, `LIMIT`/`OFFSET` (or `FETCH FIRST` / `TOP`).
* **Aggregates** — `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` with `GROUP BY`.
* **DISTINCT** — deduplicate result rows.
* **Subqueries / CTEs** — nest logic with `(SELECT …)` or `WITH … AS`.

## 💡 Examples [#-examples]

```sql
-- Basic
SELECT id, email, created_at
FROM users
WHERE active = TRUE
ORDER BY created_at DESC
LIMIT 20 OFFSET 0;

-- Aliases & expressions
SELECT
  first_name || ' ' || last_name AS full_name,
  DATE_PART('year', AGE(born_at)) AS age
FROM people;

-- Aggregates
SELECT status, COUNT(*) AS total
FROM orders
WHERE created_at >= CURRENT_DATE - INTERVAL '30 days'
GROUP BY status
HAVING COUNT(*) > 10
ORDER BY total DESC;

-- CTE
WITH recent AS (
  SELECT user_id, COUNT(*) AS orders
  FROM orders
  WHERE created_at >= NOW() - INTERVAL '7 days'
  GROUP BY user_id
)
SELECT u.email, r.orders
FROM recent r
JOIN users u ON u.id = r.user_id
ORDER BY r.orders DESC;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `SELECT *` breaks when schemas change and transfers unused columns.
* Filtering on expressions (`WHERE YEAR(created_at) = 2026`) can prevent index use — prefer range predicates.
* `NULL` never equals anything — use `IS NULL` / `IS DISTINCT FROM`.
* Dialect differences: `LIMIT` (Postgres/MySQL) vs `TOP` (SQL Server) vs `FETCH` (standard).

## 🔗 Related [#-related]

* [Insert / Update / Delete](/docs/sql/insert-update-delete)
* [Joins](/docs/sql/joins)
* [Indexes](/docs/sql/indexes)
* [Transactions](/docs/sql/transactions)


# Stored procedures and functions (/docs/sql/stored-procedures)



# Stored procedures and functions [#stored-procedures-and-functions]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Stored procedures/functions encapsulate SQL and procedural logic in the database. Postgres distinguishes functions (`RETURNS`) and procedures (`CALL`, transaction control). MySQL uses `PROCEDURE` / `FUNCTION` with different syntax. Prefer app-layer services unless you need DB-local batching or security definer patterns.

## 🔧 Core concepts [#-core-concepts]

* **Function** — returns a value/table; usable in SQL expressions (with limits).
* **Procedure** — invoked with `CALL`; may manage transactions (Postgres).
* **Languages** — SQL, PL/pgSQL (PG), MySQL stored program language.
* **Volatility** — `IMMUTABLE` / `STABLE` / `VOLATILE` (Postgres optimizer).
* **Security** — `SECURITY DEFINER` vs invoker rights (careful with privileges).

## 💡 Examples [#-examples]

```sql
-- Postgres function
CREATE OR REPLACE FUNCTION user_order_count(p_user_id BIGINT)
RETURNS BIGINT
LANGUAGE sql
STABLE
AS $$
  SELECT COUNT(*) FROM orders WHERE user_id = p_user_id;
$$;

SELECT email, user_order_count(id) FROM users;

-- Postgres procedure
CREATE OR REPLACE PROCEDURE archive_old_orders(p_days INT)
LANGUAGE plpgsql
AS $$
BEGIN
  INSERT INTO orders_archive
  SELECT * FROM orders
  WHERE created_at < NOW() - (p_days || ' days')::INTERVAL;
  DELETE FROM orders
  WHERE created_at < NOW() - (p_days || ' days')::INTERVAL;
  COMMIT;  -- procedures can commit (PG)
END;
$$;

CALL archive_old_orders(365);
```

```sql
-- MySQL procedure sketch
DELIMITER //
CREATE PROCEDURE archive_old_orders(IN p_days INT)
BEGIN
  DELETE FROM orders WHERE created_at < NOW() - INTERVAL p_days DAY;
END //
DELIMITER ;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Business logic in the DB is harder to test/version than app code.
* `SECURITY DEFINER` can escalate privileges — lock search\_path and owners.
* MySQL `DELIMITER` is a client concept — needed for multi-statement bodies.
* Functions with side effects in `SELECT` surprise readers — mark volatility correctly.
* Portability between Postgres and MySQL stored programs is poor.

## 🔗 Related [#-related]

* [triggers.md](/docs/sql/triggers)
* [transactions.md](/docs/sql/transactions)
* [functions\_builtin.md](/docs/sql/functions-builtin)
* [schemas.md](/docs/sql/schemas)
* [insert\_update\_delete.md](/docs/sql/insert-update-delete)
* [explain\_analyze.md](/docs/sql/explain-analyze)


# Subqueries (/docs/sql/subquery)



# Subqueries [#subqueries]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Subqueries are nested `SELECT`s in `WHERE`, `FROM`, `SELECT`, or DML. Prefer joins or CTEs for readability when equivalent; use subqueries for existence checks, scalar lookups, and derived tables.

## 🔧 Core concepts [#-core-concepts]

* **Scalar** — returns one value; usable in expressions.
* **IN / NOT IN** — membership; watch NULLs with `NOT IN`.
* **EXISTS / NOT EXISTS** — semi-join; often best for existence.
* **Derived table** — subquery in `FROM` (must be aliased).
* **Correlated** — references outer row; runs per outer row (optimizer may rewrite).
* **LATERAL** — Postgres: correlated FROM subquery.

## 💡 Examples [#-examples]

```sql
-- Scalar
SELECT name,
       (SELECT COUNT(*) FROM orders o WHERE o.user_id = u.id) AS order_count
FROM users u;

-- EXISTS
SELECT u.id, u.email
FROM users u
WHERE EXISTS (
  SELECT 1 FROM orders o
  WHERE o.user_id = u.id AND o.total > 100
);

-- IN
SELECT * FROM products
WHERE category_id IN (SELECT id FROM categories WHERE active);

-- Derived table
SELECT c.customer_id, c.revenue
FROM (
  SELECT customer_id, SUM(total) AS revenue
  FROM orders
  GROUP BY customer_id
) AS c
WHERE c.revenue > 1000;

-- Postgres LATERAL
SELECT u.id, o.id AS last_order_id
FROM users u
LEFT JOIN LATERAL (
  SELECT id FROM orders
  WHERE user_id = u.id
  ORDER BY created_at DESC
  LIMIT 1
) o ON TRUE;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `NOT IN (SELECT col …)` yields unknown if the subquery returns NULL — prefer `NOT EXISTS`.
* Correlated subqueries can be slow without indexes on join keys.
* Scalar subquery that returns >1 row errors at runtime.
* MySQL historically limited subquery materialization — check `EXPLAIN`.
* Deep nesting hurts readability — use CTEs.

## 🔗 Related [#-related]

* [cte.md](/docs/sql/cte)
* [joins.md](/docs/sql/joins)
* [where\_having.md](/docs/sql/where-having)
* [select.md](/docs/sql/select)
* [explain\_analyze.md](/docs/sql/explain-analyze)
* [aggregate.md](/docs/sql/aggregate)


# Tables Basics (/docs/sql/tables-basics)



# Tables Basics [#tables-basics]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A **table** stores structured data in columns (schema) and rows (data). You define column names and types with `CREATE TABLE`, then add rows with `INSERT` and read them with `SELECT`.

## 🔧 Core concepts [#-core-concepts]

| Idea         | Meaning                                         |
| ------------ | ----------------------------------------------- |
| Column type  | `INTEGER`, `TEXT`, `REAL`, `BOOLEAN`, `DATE`, … |
| `NOT NULL`   | Column must have a value                        |
| `DEFAULT`    | Value used when insert omits the column         |
| `INSERT`     | Add row(s)                                      |
| `SELECT`     | Read row(s)                                     |
| `DROP TABLE` | Delete the table (destructive)                  |

Design tables around one clear entity (users, orders, products).

## 💡 Examples [#-examples]

**Create and inspect:**

```sql
CREATE TABLE books (
  id INTEGER PRIMARY KEY,
  title TEXT NOT NULL,
  pages INTEGER,
  read INTEGER DEFAULT 0
);

INSERT INTO books (title, pages) VALUES
  ('Dune', 412),
  ('Foundation', 255);

SELECT * FROM books;
```

**Select specific columns:**

```sql
SELECT title, pages
FROM books
ORDER BY pages DESC;
```

**Add a column later (shape varies by dialect):**

```sql
ALTER TABLE books ADD COLUMN author TEXT;
UPDATE books SET author = 'Unknown' WHERE author IS NULL;
SELECT title, author FROM books;
```

**Remove a practice table:**

```sql
DROP TABLE IF EXISTS books;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `DROP TABLE` deletes data permanently (unless you have backups).
* Types differ by database — check docs for Postgres vs SQLite vs MySQL.
* Wide “god tables” with dozens of unrelated columns become hard to query.
* Omitting `NOT NULL` on required fields allows incomplete rows.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/sql/getting-started)
* [hello\_world.md](/docs/sql/hello-world)
* [primary\_keys\_basics.md](/docs/sql/primary-keys-basics)
* [null\_basics.md](/docs/sql/null-basics)


# Transactions (/docs/sql/transactions)



# Transactions [#transactions]

**SQL · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Transactions group statements into an atomic unit: all commit or all roll back. Isolation levels control what concurrent sessions can see. Use them for multi-step writes that must stay consistent.

## 🧩 Core concepts [#-core-concepts]

* **ACID** — Atomicity, Consistency, Isolation, Durability.
* **BEGIN / COMMIT / ROLLBACK** — start, persist, or undo a unit of work.
* **Savepoints** — partial rollback inside a transaction.
* **Isolation levels** — `READ UNCOMMITTED`, `READ COMMITTED`, `REPEATABLE READ`, `SERIALIZABLE`.
* **Locks** — row/table locks and deadlocks under contention.
* **Autocommit** — many clients commit each statement unless a transaction is open.

## 💡 Examples [#-examples]

```sql
BEGIN;

UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;

-- Optional check
SELECT balance FROM accounts WHERE id IN (1, 2);

COMMIT;
-- or: ROLLBACK;

-- Savepoint
BEGIN;
INSERT INTO orders (user_id, total) VALUES (9, 50) RETURNING id;
SAVEPOINT sp_items;
INSERT INTO order_items (order_id, product_id, qty) VALUES (currval('orders_id_seq'), 55, 1);
-- on failure:
ROLLBACK TO SAVEPOINT sp_items;
COMMIT;

-- Isolation (PostgreSQL example)
BEGIN ISOLATION LEVEL SERIALIZABLE;
-- critical reads/writes
COMMIT;
```

Application pattern (pseudocode):

```plaintext
BEGIN
  write A
  write B
COMMIT  -- or ROLLBACK on error
```

## ⚠️ Pitfalls [#️-pitfalls]

* Long transactions hold locks and inflate MVCC bloat — keep them short.
* Ignoring errors and still committing can persist partial logical work if statements were autocommitted.
* Deadlocks: engines abort one session — retry the whole transaction.
* Isolation defaults differ (e.g. Postgres `READ COMMITTED` vs MySQL InnoDB `REPEATABLE READ`) — don’t assume anomaly behavior.

## 🔗 Related [#-related]

* [Insert / Update / Delete](/docs/sql/insert-update-delete)
* [Select](/docs/sql/select)
* [Indexes](/docs/sql/indexes)
* [Joins](/docs/sql/joins)


# Triggers (/docs/sql/triggers)



# Triggers [#triggers]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Triggers run procedural logic on `INSERT`/`UPDATE`/`DELETE` (and some DDL). Use sparingly for auditing, derived columns, or enforcing rules that constraints can’t express. Prefer application transactions + constraints when possible — triggers are easy to overlook.

## 🔧 Core concepts [#-core-concepts]

* **Timing** — `BEFORE` / `AFTER` (Postgres also `INSTEAD OF` on views).
* **Granularity** — `FOR EACH ROW` vs `FOR EACH STATEMENT`.
* **Transition rows** — `NEW` / `OLD` (row triggers).
* **Function body** — Postgres: trigger functions in PL/pgSQL; MySQL: inline `BEGIN … END`.
* **When** — optional `WHEN (condition)` (Postgres).

## 💡 Examples [#-examples]

```sql
-- Postgres
CREATE OR REPLACE FUNCTION set_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at := NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trg_users_updated
BEFORE UPDATE ON users
FOR EACH ROW
EXECUTE FUNCTION set_updated_at();  -- PG14+: EXECUTE FUNCTION; older: EXECUTE PROCEDURE

-- Audit log
CREATE TRIGGER trg_orders_audit
AFTER UPDATE ON orders
FOR EACH ROW
WHEN (OLD.status IS DISTINCT FROM NEW.status)
EXECUTE FUNCTION log_order_status_change();
```

```sql
-- MySQL
CREATE TRIGGER trg_users_updated
BEFORE UPDATE ON users
FOR EACH ROW
SET NEW.updated_at = CURRENT_TIMESTAMP;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hidden side effects surprise developers — document triggers next to the table.
* Mutating the same table in a row trigger can cause recursion / errors.
* Statement vs row triggers fire differently for multi-row SQL.
* Disabling triggers for bulk loads can leave data inconsistent if forgotten.
* Replication / logical decoding may need trigger design awareness.

## 🔗 Related [#-related]

* [stored\_procedures.md](/docs/sql/stored-procedures)
* [constraints.md](/docs/sql/constraints)
* [transactions.md](/docs/sql/transactions)
* [create\_alter\_drop.md](/docs/sql/create-alter-drop)
* [insert\_update\_delete.md](/docs/sql/insert-update-delete)
* [foreign\_keys.md](/docs/sql/foreign-keys)


# UPSERT (/docs/sql/upsert)



# UPSERT [#upsert]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

UPSERT inserts a row or updates it when a conflict occurs (unique/PK violation). Postgres uses `INSERT … ON CONFLICT`; MySQL uses `ON DUPLICATE KEY UPDATE` or `REPLACE`. Choose conflict targets carefully to avoid silent wrong updates.

## 🔧 Core concepts [#-core-concepts]

* **Conflict target** — constraint name or column list that defines uniqueness.
* **DO NOTHING / DO UPDATE** — ignore vs merge (Postgres).
* **Excluded row** — Postgres `EXCLUDED.col` is the would-be insert.
* **MySQL** — `VALUES(col)` (older) / aliases (8.0.19+) for new values.
* **Idempotency** — natural keys + upsert for retries.

## 💡 Examples [#-examples]

```sql
-- Postgres
INSERT INTO users (email, name)
VALUES ('ada@example.com', 'Ada')
ON CONFLICT (email)
DO UPDATE SET
  name = EXCLUDED.name,
  updated_at = NOW()
RETURNING id, email;

INSERT INTO hits (slug, n)
VALUES ('home', 1)
ON CONFLICT (slug)
DO UPDATE SET n = hits.n + 1;

INSERT INTO users (email, name)
VALUES ('ada@example.com', 'Ada')
ON CONFLICT DO NOTHING;
```

```sql
-- MySQL
INSERT INTO users (email, name)
VALUES ('ada@example.com', 'Ada')
ON DUPLICATE KEY UPDATE
  name = VALUES(name),
  updated_at = CURRENT_TIMESTAMP;

-- REPLACE INTO deletes then inserts (side effects on FKs/AI) — prefer ODKu
```

## ⚠️ Pitfalls [#️-pitfalls]

* Upsert updates only on the conflict you specify — wrong unique key → duplicate rows.
* `REPLACE INTO` (MySQL) deletes the old row → FK cascades / new auto-increment.
* Partial unique indexes (Postgres) need matching `ON CONFLICT` inference.
* Concurrent upserts need proper unique constraints or you’ll still race.
* Don’t use upsert to hide missing `WHERE` on updates — be explicit.

## 🔗 Related [#-related]

* [insert\_update\_delete.md](/docs/sql/insert-update-delete)
* [constraints.md](/docs/sql/constraints)
* [transactions.md](/docs/sql/transactions)
* [indexes.md](/docs/sql/indexes)
* [nulls.md](/docs/sql/nulls)
* [foreign\_keys.md](/docs/sql/foreign-keys)


# Views (/docs/sql/views)



# Views [#views]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Views are stored queries that act like virtual tables. Use them for reusable projections, security (column/row hiding), and simplifying joins. Materialized views store results physically (Postgres); MySQL has views but not native materialized views.

## 🔧 Core concepts [#-core-concepts]

* **CREATE VIEW** — non-materialized; runs underlying query on read.
* **REPLACE / OR REPLACE** — update definition.
* **Updatable views** — limited; simple views may allow `INSERT`/`UPDATE`.
* **Materialized** — Postgres `MATERIALIZED VIEW` + `REFRESH`.
* **Security** — grant on view without granting base tables (with caveats).

## 💡 Examples [#-examples]

```sql
CREATE VIEW active_users AS
SELECT id, email, created_at
FROM users
WHERE deleted_at IS NULL;

CREATE OR REPLACE VIEW order_summaries AS
SELECT o.id, u.email, o.total, o.status
FROM orders o
JOIN users u ON u.id = o.user_id;

SELECT * FROM active_users WHERE created_at > CURRENT_DATE - INTERVAL '7 days';

-- Postgres materialized
CREATE MATERIALIZED VIEW daily_revenue AS
SELECT DATE(created_at) AS day, SUM(total) AS revenue
FROM orders
GROUP BY DATE(created_at)
WITH DATA;

REFRESH MATERIALIZED VIEW CONCURRENTLY daily_revenue;  -- needs unique index

DROP VIEW IF EXISTS active_users;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Views don’t automatically speed queries — they can hide expensive joins.
* Nested views make `EXPLAIN` harder — flatten when debugging.
* `OR REPLACE` can break consumers if column names/types change.
* Materialized views go stale until refreshed — schedule carefully.
* MySQL: no `MATERIALIZED VIEW`; emulate with tables + jobs.

## 🔗 Related [#-related]

* [select.md](/docs/sql/select)
* [cte.md](/docs/sql/cte)
* [joins.md](/docs/sql/joins)
* [schemas.md](/docs/sql/schemas)
* [create\_alter\_drop.md](/docs/sql/create-alter-drop)
* [explain\_analyze.md](/docs/sql/explain-analyze)


# WHERE and HAVING (/docs/sql/where-having)



# WHERE and HAVING [#where-and-having]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`WHERE` filters rows before aggregation; `HAVING` filters groups after `GROUP BY`. Use `WHERE` for row predicates and `HAVING` for aggregate conditions (`COUNT`, `SUM`, …).

## 🔧 Core concepts [#-core-concepts]

* **Order** — `FROM` → `WHERE` → `GROUP BY` → `HAVING` → `SELECT` → `ORDER BY`.
* **Predicates** — `=`, `&lt;>`, `&lt;`, `IN`, `BETWEEN`, `LIKE`/`ILIKE`, `IS NULL`.
* **Boolean** — `AND` / `OR` / `NOT`; parentheses for clarity.
* **Aliases** — `HAVING` may allow select aliases in some engines; don’t rely on it portably.
* **Sargability** — avoid wrapping indexed columns in functions in `WHERE`.

## 💡 Examples [#-examples]

```sql
SELECT id, email
FROM users
WHERE is_active = TRUE
  AND created_at >= DATE '2026-01-01'
  AND email LIKE '%@example.com';

SELECT customer_id, COUNT(*) AS order_count, SUM(total) AS revenue
FROM orders
WHERE status <> 'cancelled'
GROUP BY customer_id
HAVING COUNT(*) >= 3
   AND SUM(total) > 1000;

-- Prefer WHERE over HAVING when possible
SELECT customer_id, COUNT(*) AS c
FROM orders
WHERE region = 'EU'          -- row filter
GROUP BY customer_id
HAVING COUNT(*) >= 3;        -- group filter
```

```sql
-- NULL-safe checks
WHERE deleted_at IS NULL
-- NOT: WHERE deleted_at = NULL
```

## ⚠️ Pitfalls [#️-pitfalls]

* `WHERE COUNT(*) > 1` is invalid — aggregates belong in `HAVING` (or subquery).
* `OR` across columns often disables simple index use — consider `UNION`.
* `WHERE col = NULL` never matches — use `IS NULL`.
* MySQL `ONLY_FULL_GROUP_BY` rejects non-aggregated selected columns.
* Filtering on `SELECT` aliases in `WHERE` is invalid in standard SQL.

## 🔗 Related [#-related]

* [select.md](/docs/sql/select)
* [aggregate.md](/docs/sql/aggregate)
* [distinct\_group\_by.md](/docs/sql/distinct-group-by)
* [nulls.md](/docs/sql/nulls)
* [order\_limit.md](/docs/sql/order-limit)
* [subquery.md](/docs/sql/subquery)


# Window functions (/docs/sql/window-functions)



# Window functions [#window-functions]

*SQL · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Window functions compute values across related rows without collapsing them (`OVER (…)`) — ranking, running totals, lead/lag. Supported in Postgres and MySQL 8+. Prefer windows over self-joins for analytics.

## 🔧 Core concepts [#-core-concepts]

* **OVER** — `PARTITION BY`, `ORDER BY`, frame (`ROWS` / `RANGE`).
* **Ranking** — `ROW_NUMBER`, `RANK`, `DENSE_RANK`, `NTILE`.
* **Offset** — `LAG` / `LEAD`, `FIRST_VALUE` / `LAST_VALUE`.
* **Aggregates as windows** — `SUM(x) OVER (ORDER BY …)`.
* **Frame defaults** — with `ORDER BY`, default often `RANGE UNBOUNDED PRECEDING` → current row.

## 💡 Examples [#-examples]

```sql
SELECT
  customer_id,
  created_at,
  total,
  ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY created_at) AS rn,
  SUM(total) OVER (
    PARTITION BY customer_id
    ORDER BY created_at
    ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
  ) AS running_total,
  LAG(total) OVER (PARTITION BY customer_id ORDER BY created_at) AS prev_total
FROM orders;

-- Top-N per group
SELECT * FROM (
  SELECT
    *,
    ROW_NUMBER() OVER (PARTITION BY category_id ORDER BY score DESC) AS rn
  FROM products
) t
WHERE rn <= 3;
```

```sql
-- Percent of total
SELECT
  sku,
  revenue,
  revenue / SUM(revenue) OVER () AS share
FROM sku_revenue;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting frame clauses makes `LAST_VALUE` surprising — set explicit frames.
* `RANK` leaves gaps; `DENSE_RANK` does not; `ROW_NUMBER` never ties.
* Windows can’t appear directly in `WHERE` — wrap in subquery/CTE.
* Large partitions + sorts are memory/disk heavy — index partition/order keys.
* MySQL \< 8 lacks window functions.

## 🔗 Related [#-related]

* [aggregate.md](/docs/sql/aggregate)
* [cte.md](/docs/sql/cte)
* [order\_limit.md](/docs/sql/order-limit)
* [select.md](/docs/sql/select)
* [subquery.md](/docs/sql/subquery)
* [explain\_analyze.md](/docs/sql/explain-analyze)


# Colors (/docs/tailwind/colors)



# Colors [#colors]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Tailwind ships a palette of named colors with numeric shades. Apply via `text-*`, `bg-*`, `border-*`, `ring-*`, `fill-*`, and `stroke-*`.

## 🔧 Core concepts [#-core-concepts]

| Prefix                       | Applies to       |
| ---------------------------- | ---------------- |
| `text-\{color\}-\{shade\}`   | color            |
| `bg-\{color\}-\{shade\}`     | background-color |
| `border-\{color\}-\{shade\}` | border-color     |
| `ring-\{color\}-\{shade\}`   | box-shadow ring  |
| `from-*` / `via-*` / `to-*`  | gradients        |

| Shade                             | Typical use                 |
| --------------------------------- | --------------------------- |
| 50–200                            | Backgrounds, subtle borders |
| 400–600                           | Accents, interactive        |
| 700–950                           | Text, strong emphasis       |
| `white` / `black` / `transparent` | Special keywords            |

## 💡 Examples [#-examples]

**Palette usage:**

```html
<div class="bg-sky-50 text-sky-950 border border-sky-200">Info</div>
<button class="bg-emerald-600 hover:bg-emerald-500 text-white">Go</button>
```

**Gradient:**

```html
<div class="bg-gradient-to-r from-orange-400 to-rose-500"></div>
```

**Opacity modifier:**

```html
<div class="bg-black/50 text-white">Overlay</div>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Low-contrast text fails a11y — check `text-*` on `bg-*` pairs.
* Custom brand colors belong in `theme.extend.colors`, not one-off arbitrary hex everywhere.
* Printing / forced-colors modes may need extra CSS beyond utilities.

## 🔗 Related [#-related]

* [dark\_mode.md](/docs/tailwind/dark-mode)
* [typography.md](/docs/tailwind/typography)
* [custom\_config.md](/docs/tailwind/custom-config)
* [utility\_classes.md](/docs/tailwind/utility-classes)


# Custom Config (/docs/tailwind/custom-config)



# Custom Config [#custom-config]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Customize Tailwind via `theme.extend` (preserve defaults) or replace theme keys. Content paths, plugins, and dark mode strategy live in the same config (v3) or CSS-first config (v4).

## 🔧 Core concepts [#-core-concepts]

| Key               | Purpose                             |
| ----------------- | ----------------------------------- |
| `content`         | Files to scan for classes           |
| `theme.extend`    | Add tokens without wiping defaults  |
| `theme` (replace) | Override entire scales              |
| `plugins`         | Register official/community plugins |
| `prefix`          | Namespace classes (`tw-`)           |
| `corePlugins`     | Disable built-ins                   |

| Extend examples      | Adds               |
| -------------------- | ------------------ |
| `colors.brand`       | Brand palette      |
| `fontFamily.display` | Custom font stack  |
| `spacing['18']`      | Extra spacing step |
| `screens.3xl`        | Extra breakpoint   |

## 💡 Examples [#-examples]

**Extend theme (v3):**

```js
export default {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {
      colors: {
        brand: { DEFAULT: "#0F766E", light: "#5EEAD4" },
      },
      fontFamily: {
        display: ["\"Fraunces\"", "serif"],
      },
    },
  },
};
```

**Use tokens:**

```html
<h1 class="font-display text-brand">Hello</h1>
```

**Prefix:**

```js
export default { prefix: "tw-", content: ["./src/**/*.{html,js}"] };
// classes become tw-flex, tw-p-4, ...
```

## ⚠️ Pitfalls [#️-pitfalls]

* Replacing `theme.colors` entirely removes the default palette — use `extend`.
* Wrong `content` globs silently drop utilities.
* Arbitrary values don't need config — but shared brand tokens should be themed.

## 🔗 Related [#-related]

* [plugins.md](/docs/tailwind/plugins)
* [getting\_started.md](/docs/tailwind/getting-started)
* [colors.md](/docs/tailwind/colors)
* [responsive.md](/docs/tailwind/responsive)


# Dark Mode (/docs/tailwind/dark-mode)



# Dark Mode [#dark-mode]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Dark mode uses the `dark:` variant. Strategy is either media-based (`prefers-color-scheme`) or class-based (`class="dark"` on a root element).

## 🔧 Core concepts [#-core-concepts]

| Strategy        | Config                 | Toggle                        |
| --------------- | ---------------------- | ----------------------------- |
| `media`         | default in many setups | OS preference                 |
| `class`         | `darkMode: 'class'`    | Add/remove `dark` on `<html>` |
| `selector` (v4) | custom selector        | Framework-specific            |

| Pair     | Example                                |
| -------- | -------------------------------------- |
| Surfaces | `bg-white dark:bg-zinc-900`            |
| Text     | `text-zinc-900 dark:text-zinc-100`     |
| Borders  | `border-zinc-200 dark:border-zinc-700` |

## 💡 Examples [#-examples]

**Class strategy config (v3):**

```js
export default {
  darkMode: "class",
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
};
```

**Markup:**

```html
<html class="dark">
  <body class="bg-white text-zinc-900 dark:bg-zinc-950 dark:text-zinc-50">
    ...
  </body>
</html>
```

**Toggle sketch:**

```js
document.documentElement.classList.toggle("dark");
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting to set `darkMode: 'class'` while toggling a class does nothing.
* Flash of wrong theme on first paint — set class early (inline script) before CSS paints.
* Not all colors need inversion; keep brand accents consistent.

## 🔗 Related [#-related]

* [colors.md](/docs/tailwind/colors)
* [custom\_config.md](/docs/tailwind/custom-config)
* [typography.md](/docs/tailwind/typography)
* [getting\_started.md](/docs/tailwind/getting-started)


# Getting Started with Tailwind CSS (/docs/tailwind/getting-started)



# Getting Started with Tailwind CSS [#getting-started-with-tailwind-css]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Tailwind CSS is a utility-first framework: you compose small classes (`flex`, `p-4`, `text-sm`) in markup instead of writing bespoke CSS for every component.

## 🔧 Core concepts [#-core-concepts]

| Idea                    | Meaning                                      |
| ----------------------- | -------------------------------------------- |
| Utility class           | Single-purpose class (`mt-4`, `bg-blue-600`) |
| Design tokens           | Spacing, colors, fonts from the theme        |
| Variants                | Prefixes like `hover:`, `md:`, `dark:`       |
| Content scan            | Tailwind finds class names in template files |
| `@tailwind` / `@import` | CSS entry depending on v3 vs v4              |

**Install (v3 typical):**

```shellscript
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```

## 💡 Examples [#-examples]

**HTML utilities:**

```html
<button class="rounded-lg bg-slate-900 px-4 py-2 text-sm text-white hover:bg-slate-700">
  Save
</button>
```

**`tailwind.config.js` content paths:**

```js
export default {
  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
  theme: { extend: {} },
  plugins: [],
};
```

**CSS entry (v3):**

```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```

## ⚠️ Pitfalls [#️-pitfalls]

* If classes are built via string concatenation, the scanner may miss them — use complete class names or safelist.
* Missing `content` paths → empty CSS output.
* Mixing Tailwind versions (v3 PostCSS vs v4 Vite plugin) without matching docs causes broken builds.

## 🔗 Related [#-related]

* [utility\_classes.md](/docs/tailwind/utility-classes)
* [responsive.md](/docs/tailwind/responsive)
* [custom\_config.md](/docs/tailwind/custom-config)
* [Comparisons/tailwind\_vs\_css.md](/docs/tailwind/../comparisons/tailwind-vs-css)


# Glossary (/docs/tailwind/glossary)



# Glossary [#glossary]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of Tailwind CSS utility-first and configuration terms.

## 🔧 Core concepts [#-core-concepts]

| Term               | Definition                                                  |
| ------------------ | ----------------------------------------------------------- |
| Arbitrary value    | Bracket syntax like `w-[14ch]` for one-off CSS values.      |
| Content paths      | Glob list of files Tailwind scans for class names.          |
| Core plugin        | Built-in feature group that can be disabled.                |
| Design token       | Named theme value for spacing, color, font, etc.            |
| JIT                | Just-in-time generation of only used utilities.             |
| Modifier / variant | Prefix such as `hover:`, `md:`, `dark:`.                    |
| Preflight          | Tailwind’s base/reset styles.                               |
| Purge (legacy)     | Old name for removing unused CSS; replaced by content scan. |
| Safelist           | Explicit classes always included in the CSS output.         |
| Theme              | Config object defining design scales.                       |
| Utility            | Single-purpose class mapping to one CSS declaration set.    |
| `@apply`           | Directive to inline utilities inside custom CSS.            |
| `@layer`           | Places custom CSS into base/components/utilities layers.    |

## 💡 Examples [#-examples]

**Variant stack:**

```html
<button class="bg-zinc-900 hover:bg-zinc-700 md:px-6 dark:bg-zinc-100">
  OK
</button>
```

**Safelist sketch:**

```js
export default {
  safelist: ["bg-red-500", "bg-green-500"],
};
```

## ⚠️ Pitfalls [#️-pitfalls]

* Dynamic class construction often breaks scanning — prefer complete strings.
* `@apply` can recreate the specificity fights utilities were meant to avoid.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/tailwind/getting-started)
* [utility\_classes.md](/docs/tailwind/utility-classes)
* [custom\_config.md](/docs/tailwind/custom-config)
* [README.md](/docs/tailwind)


# Tailwind (/docs/tailwind)



# Tailwind [#tailwind]

Utility-first CSS.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Layout: Flex & Grid (/docs/tailwind/layout-flex-grid)



# Layout: Flex & Grid [#layout-flex--grid]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Flexbox and CSS Grid utilities cover most app layouts: toolbars, sidebars, card grids, and centering.

## 🔧 Core concepts [#-core-concepts]

| Flex                         | Grid                         |
| ---------------------------- | ---------------------------- |
| `flex`, `inline-flex`        | `grid`, `inline-grid`        |
| `flex-row` / `flex-col`      | `grid-cols-*`                |
| `items-*` / `justify-*`      | `gap-*`, `col-span-*`        |
| `flex-1`, `grow`, `shrink-0` | `grid-rows-*`, `row-span-*`  |
| `flex-wrap`                  | `auto-rows-*`, `auto-cols-*` |

| Alignment            | Meaning                       |
| -------------------- | ----------------------------- |
| `items-center`       | Cross-axis center (flex)      |
| `justify-between`    | Main-axis space between       |
| `place-items-center` | Grid item centering shorthand |

## 💡 Examples [#-examples]

**Centered hero content:**

```html
<div class="flex min-h-screen items-center justify-center">
  <p>Centered</p>
</div>
```

**Sidebar + main:**

```html
<div class="flex min-h-screen">
  <aside class="w-64 shrink-0 border-r">Sidebar</aside>
  <main class="flex-1 p-6">Main</main>
</div>
```

**Responsive grid:**

```html
<div class="grid grid-cols-1 gap-4 sm:grid-cols-2 xl:grid-cols-4">
  <div>1</div><div>2</div><div>3</div><div>4</div>
</div>
```

## ⚠️ Pitfalls [#️-pitfalls]

* `flex-1` children can overflow — add `min-w-0` for truncating text in flex rows.
* Mixing heavy nested grids without `gap` becomes brittle — prefer simpler structures.
* Absolute positioning (`absolute inset-0`) escapes flex/grid flow — intentional only.

## 🔗 Related [#-related]

* [responsive.md](/docs/tailwind/responsive)
* [spacing\_sizing.md](/docs/tailwind/spacing-sizing)
* [utility\_classes.md](/docs/tailwind/utility-classes)
* [getting\_started.md](/docs/tailwind/getting-started)


# Plugins (/docs/tailwind/plugins)



# Plugins [#plugins]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Plugins add new utilities, components, or variants. Official plugins cover typography, forms, and aspect-ratio (some now built-in depending on version).

## 🔧 Core concepts [#-core-concepts]

| Plugin                           | Adds                                  |
| -------------------------------- | ------------------------------------- |
| `@tailwindcss/typography`        | `prose` styles for rich text          |
| `@tailwindcss/forms`             | Sensible form element base styles     |
| `@tailwindcss/container-queries` | `@min-*` / `@max-*` variants (v3 era) |
| `@tailwindcss/aspect-ratio`      | Legacy aspect utilities               |

| API                                                          | Role                       |
| ------------------------------------------------------------ | -------------------------- |
| `plugin(function(\{ addUtilities, addComponents, theme \}))` | Author plugins             |
| `addVariant`                                                 | Custom variants            |
| `matchUtilities`                                             | Dynamic utility generation |

## 💡 Examples [#-examples]

**Register plugins (v3):**

```js
import typography from "@tailwindcss/typography";
import forms from "@tailwindcss/forms";

export default {
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
  plugins: [typography, forms],
};
```

**Prose article:**

```html
<article class="prose dark:prose-invert max-w-none">
  <h1>Doc title</h1>
  <p>Markdown-rendered content…</p>
</article>
```

**Tiny custom utility plugin:**

```js
import plugin from "tailwindcss/plugin";

export default {
  plugins: [
    plugin(({ addUtilities }) => {
      addUtilities({
        ".content-auto": { "content-visibility": "auto" },
      });
    }),
  ],
};
```

## ⚠️ Pitfalls [#️-pitfalls]

* Duplicate functionality between Tailwind core and old plugins wastes CSS.
* Plugin order can matter when multiple plugins define the same utility.
* Always install matching plugin majors for your Tailwind major.

## 🔗 Related [#-related]

* [custom\_config.md](/docs/tailwind/custom-config)
* [typography.md](/docs/tailwind/typography)
* [getting\_started.md](/docs/tailwind/getting-started)
* [dark\_mode.md](/docs/tailwind/dark-mode)


# Responsive Design (/docs/tailwind/responsive)



# Responsive Design [#responsive-design]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Tailwind uses mobile-first breakpoint variants. Unprefixed utilities apply from `0` up; `md:` and larger override at that minimum width.

## 🔧 Core concepts [#-core-concepts]

| Variant (default) | Min width |
| ----------------- | --------- |
| `sm:`             | 640px     |
| `md:`             | 768px     |
| `lg:`             | 1024px    |
| `xl:`             | 1280px    |
| `2xl:`            | 1536px    |

| Pattern                      | Meaning                      |
| ---------------------------- | ---------------------------- |
| `w-full md:w-1/2`            | Full on mobile, half from md |
| `hidden md:block`            | Show starting at md          |
| `grid-cols-1 lg:grid-cols-3` | Stack then 3 columns         |
| `max-md:`                    | Only below md (v3.2+)        |

## 💡 Examples [#-examples]

**Stack → row:**

```html
<div class="flex flex-col gap-4 md:flex-row md:items-center">
  <nav class="w-full md:w-64">Nav</nav>
  <main class="flex-1">Content</main>
</div>
```

**Responsive type:**

```html
<h1 class="text-2xl md:text-4xl lg:text-5xl font-bold">Headline</h1>
```

**Hide on small screens:**

```html
<aside class="hidden lg:block">Desktop sidebar</aside>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Thinking desktop-first and writing `md:` as “mobile only” — it's min-width.
* Custom breakpoints must be extended in theme config to stay consistent.
* Container queries use `@min-*` / `@max-*` variants when enabled — different from viewport breakpoints.

## 🔗 Related [#-related]

* [layout\_flex\_grid.md](/docs/tailwind/layout-flex-grid)
* [utility\_classes.md](/docs/tailwind/utility-classes)
* [custom\_config.md](/docs/tailwind/custom-config)
* [dark\_mode.md](/docs/tailwind/dark-mode)


# Spacing & Sizing (/docs/tailwind/spacing-sizing)



# Spacing & Sizing [#spacing--sizing]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Spacing and sizing scales are theme tokens (usually 4px units). Prefer the scale for consistency; use arbitrary values when the design demands it.

## 🔧 Core concepts [#-core-concepts]

| Prefix                            | CSS                     |
| --------------------------------- | ----------------------- |
| `p-*` / `px-*` / `py-*` / `pt-*`… | padding                 |
| `m-*` / negative `-m-*`           | margin                  |
| `gap-*`                           | flex/grid gap           |
| `space-x-*` / `space-y-*`         | child margins           |
| `w-*` / `h-*`                     | width / height          |
| `min-*` / `max-*`                 | min/max size            |
| `size-*`                          | width + height together |

| Scale tip        | Example              |
| ---------------- | -------------------- |
| `4` → 1rem       | `p-4`                |
| `0.5` → 0.125rem | `gap-0.5`            |
| `full`           | `100%`               |
| `screen`         | `100vh` (`h-screen`) |

## 💡 Examples [#-examples]

**Padding + gap:**

```html
<section class="p-6">
  <div class="flex gap-3">
    <button class="px-3 py-2">A</button>
    <button class="px-3 py-2">B</button>
  </div>
</section>
```

**Width constraints:**

```html
<div class="mx-auto w-full max-w-3xl px-4">Readable measure</div>
```

**Square icon button:**

```html
<button class="size-10 rounded-full">♪</button>
```

## ⚠️ Pitfalls [#️-pitfalls]

* `space-y-*` + `gap-*` together can double spacing.
* `h-screen` ignores mobile browser chrome — `min-h-dvh` is often better when available.
* Collapsing margins still exist for non-flex block layout — prefer `gap` in flex/grid.

## 🔗 Related [#-related]

* [layout\_flex\_grid.md](/docs/tailwind/layout-flex-grid)
* [utility\_classes.md](/docs/tailwind/utility-classes)
* [custom\_config.md](/docs/tailwind/custom-config)
* [typography.md](/docs/tailwind/typography)


# Typography (/docs/tailwind/typography)



# Typography [#typography]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Typography utilities control font family, size, weight, line-height, letter-spacing, alignment, and text decoration.

## 🔧 Core concepts [#-core-concepts]

| Utility                                  | Role                              |
| ---------------------------------------- | --------------------------------- |
| `font-sans` / `font-serif` / `font-mono` | Family                            |
| `text-xs` … `text-9xl`                   | Font size (+ default line-height) |
| `font-thin` … `font-black`               | Weight                            |
| `leading-*`                              | Line height                       |
| `tracking-*`                             | Letter spacing                    |
| `text-left` / `center` / `right`         | Alignment                         |
| `truncate` / `line-clamp-*`              | Overflow                          |
| `underline` / `no-underline`             | Decoration                        |

| Prose                     | Notes                              |
| ------------------------- | ---------------------------------- |
| `@tailwindcss/typography` | Beautiful markdown/`prose` classes |
| `prose dark:prose-invert` | Article styling                    |

## 💡 Examples [#-examples]

**Heading + body:**

```html
<h1 class="text-3xl font-bold tracking-tight text-zinc-900">Title</h1>
<p class="mt-2 text-base leading-7 text-zinc-600">Supporting paragraph.</p>
```

**Truncate:**

```html
<p class="max-w-xs truncate">A very long single-line label that will ellipsis</p>
```

**Clamp lines:**

```html
<p class="line-clamp-3">Multi-line preview text…</p>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Default `text-*` sizes include line-height — overriding only size can look uneven.
* System font stacks may not match brand — extend `theme.fontFamily`.
* `truncate` requires overflow hidden + width constraint to take effect.

## 🔗 Related [#-related]

* [colors.md](/docs/tailwind/colors)
* [plugins.md](/docs/tailwind/plugins)
* [spacing\_sizing.md](/docs/tailwind/spacing-sizing)
* [custom\_config.md](/docs/tailwind/custom-config)


# Utility Classes (/docs/tailwind/utility-classes)



# Utility Classes [#utility-classes]

*Tailwind · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Utilities map to CSS properties. Compose many utilities on one element; extract components only when repetition hurts readability.

## 🔧 Core concepts [#-core-concepts]

| Category   | Examples                                          |
| ---------- | ------------------------------------------------- |
| Layout     | `block`, `flex`, `grid`, `hidden`                 |
| Spacing    | `p-4`, `px-2`, `mt-6`, `gap-3`                    |
| Sizing     | `w-full`, `h-10`, `max-w-lg`, `min-h-screen`      |
| Typography | `text-sm`, `font-medium`, `leading-6`, `truncate` |
| Color      | `text-red-600`, `bg-zinc-100`, `border-slate-300` |
| Border     | `border`, `rounded-md`, `ring-2`                  |
| Effects    | `shadow`, `opacity-50`, `blur`                    |

| Pattern         | Example                            |
| --------------- | ---------------------------------- |
| State variant   | `hover:bg-blue-600`                |
| Important       | `!flex` (escape hatch)             |
| Arbitrary value | `w-[320px]`, `top-[var(--header)]` |

## 💡 Examples [#-examples]

**Card-ish layout without a “card” abstraction:**

```html
<article class="max-w-md rounded-xl border border-zinc-200 p-6 shadow-sm">
  <h2 class="text-lg font-semibold text-zinc-900">Title</h2>
  <p class="mt-2 text-sm text-zinc-600">Body copy</p>
</article>
```

**Arbitrary property:**

```html
<div class="[mask-image:linear-gradient(black,transparent)]"></div>
```

**Space between children:**

```html
<ul class="space-y-2">
  <li>One</li>
  <li>Two</li>
</ul>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Extremely long `class` attributes — extract a component or `@apply` sparingly.
* Conflicting utilities: later rules in generated CSS win, not necessarily left-to-right in the attribute.
* Inline styles still override utilities depending on specificity.

## 🔗 Related [#-related]

* [spacing\_sizing.md](/docs/tailwind/spacing-sizing)
* [typography.md](/docs/tailwind/typography)
* [colors.md](/docs/tailwind/colors)
* [layout\_flex\_grid.md](/docs/tailwind/layout-flex-grid)


# CLI Basics (/docs/redis/cli-basics)



# CLI Basics [#cli-basics]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`redis-cli` is the standard admin and debugging client: run commands, monitor traffic, check latency, and inspect keys safely with `SCAN`.

## 🔧 Core concepts [#-core-concepts]

| Command / flag                   | Purpose                        |
| -------------------------------- | ------------------------------ |
| `redis-cli`                      | Interactive REPL               |
| `redis-cli -u redis://host:6379` | URL connect                    |
| `redis-cli CMD …`                | One-shot command               |
| `INFO`                           | Sections of server info        |
| `MONITOR`                        | Stream commands (prod caution) |
| `SCAN`                           | Iterate keys safely            |
| `--latency`                      | Latency sampler                |

| Key inspection     | Notes                |
| ------------------ | -------------------- |
| `TYPE key`         | Data structure       |
| `EXISTS key`       | 0/1                  |
| `MEMORY USAGE key` | Bytes (if available) |
| `OBJECT ENCODING`  | Internal encoding    |

## 💡 Examples [#-examples]

**Connect and ping:**

```shellscript
redis-cli -h 127.0.0.1 -p 6379 PING
```

**Scan keys by prefix:**

```shellscript
redis-cli --scan --pattern 'user:*'
```

**Info memory:**

```shellscript
redis-cli INFO memory
```

## ⚠️ Pitfalls [#️-pitfalls]

* `KEYS *` blocks — never on busy production instances.
* `MONITOR` is expensive and leaks command data (including values).
* Auth: use `AUTH` / ACL users — don't put passwords in shell history casually.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/redis/getting-started)
* [strings.md](/docs/redis/strings)
* [expiry\_ttl.md](/docs/redis/expiry-ttl)
* [persistence.md](/docs/redis/persistence)


# Expiry & TTL (/docs/redis/expiry-ttl)



# Expiry & TTL [#expiry--ttl]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Keys can expire automatically. TTL powers caches, sessions, and ephemeral locks. Expiry is per key (not per hash field).

## 🔧 Core concepts [#-core-concepts]

| Command              | Role                                          |
| -------------------- | --------------------------------------------- |
| `EXPIRE key seconds` | Set TTL                                       |
| `PEXPIRE`            | TTL in ms                                     |
| `TTL` / `PTTL`       | Remaining time (`-1` no expire, `-2` missing) |
| `PERSIST`            | Remove expiry                                 |
| `SET … EX`           | Set value + TTL atomically                    |
| `EXPIREAT`           | Expire at unix time                           |

| Eviction (when maxmemory) | Examples                  |
| ------------------------- | ------------------------- |
| `volatile-lru`            | Evict expiring keys LRU   |
| `allkeys-lru`             | Evict any key LRU         |
| `noeviction`              | Errors on write when full |

## 💡 Examples [#-examples]

**Session TTL:**

```shellscript
SET sess:abc123 '{"userId":42}' EX 1800
TTL sess:abc123
```

**Refresh TTL:**

```shellscript
EXPIRE sess:abc123 1800
```

**Lock with auto-expiry:**

```shellscript
SET lock:migrate 1 NX EX 60
```

## ⚠️ Pitfalls [#️-pitfalls]

* Expired keys may still appear briefly until lazy/active expiration removes them.
* Writing a key with `SET` without TTL removes any previous expiry unless using keep-ttl options.
* Relying on TTL for correctness without handling miss paths causes subtle bugs.

## 🔗 Related [#-related]

* [strings.md](/docs/redis/strings)
* [persistence.md](/docs/redis/persistence)
* [getting\_started.md](/docs/redis/getting-started)
* [cli\_basics.md](/docs/redis/cli-basics)


# Getting Started with Redis (/docs/redis/getting-started)



# Getting Started with Redis [#getting-started-with-redis]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Redis is an in-memory data structure server used for caching, sessions, queues, rate limits, and pub/sub. Data structures are first-class (strings, hashes, lists, sets, sorted sets).

## 🔧 Core concepts [#-core-concepts]

| Idea                              | Meaning                                   |
| --------------------------------- | ----------------------------------------- |
| Key                               | String name for a value                   |
| TTL                               | Optional expiry on keys                   |
| Single-threaded command execution | Commands are atomic per command           |
| Persistence                       | Optional RDB/AOF durability               |
| DB index                          | Logical keyspaces `0–15` (default config) |

| Command     | Purpose               |
| ----------- | --------------------- |
| `redis-cli` | Interactive client    |
| `PING`      | Health check → `PONG` |
| `INFO`      | Server stats          |
| `SELECT n`  | Switch DB index       |

## 💡 Examples [#-examples]

**Run Redis (Docker):**

```shellscript
docker run --rm -p 6379:6379 redis:7-alpine
```

**First commands:**

```shellscript
redis-cli
> PING
PONG
> SET greeting "hello"
OK
> GET greeting
"hello"
```

**From Node sketch:**

```js
import { createClient } from "redis";
const client = createClient({ url: "redis://127.0.0.1:6379" });
await client.connect();
await client.set("greeting", "hello");
```

## ⚠️ Pitfalls [#️-pitfalls]

* Memory is finite — without eviction policy + TTLs, Redis can OOM.
* Treating Redis as the only source of truth without persistence/HA is risky.
* Key naming collisions across features — use prefixes (`app:session:`).

## 🔗 Related [#-related]

* [strings.md](/docs/redis/strings)
* [expiry\_ttl.md](/docs/redis/expiry-ttl)
* [cli\_basics.md](/docs/redis/cli-basics)
* [Comparisons/redis\_vs\_postgres.md](/docs/redis/../comparisons/redis-vs-postgres)


# Glossary (/docs/redis/glossary)



# Glossary [#glossary]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of Redis data structures, durability, and client terms.

## 🔧 Core concepts [#-core-concepts]

| Term       | Definition                                            |
| ---------- | ----------------------------------------------------- |
| AOF        | Append-only file persistence log of write operations. |
| Eviction   | Removing keys under `maxmemory` per policy.           |
| Hash       | Field-value map stored at a single key.               |
| Keyspace   | The set of keys in a selected logical database.       |
| List       | Ordered sequence supporting push/pop at ends.         |
| Pub/Sub    | Fire-and-forget channel messaging.                    |
| RDB        | Snapshot persistence format.                          |
| Replica    | Read copy of a primary for HA/scale-out reads.        |
| Set        | Unordered collection of unique members.               |
| Sorted set | Unique members ordered by score.                      |
| Stream     | Append-only log with consumer groups.                 |
| TTL        | Time-to-live before a key expires.                    |
| `SCAN`     | Cursor-based incremental iteration.                   |

## 💡 Examples [#-examples]

**Type check:**

```shellscript
TYPE session:abc
TTL session:abc
```

**Logical DB:**

```shellscript
SELECT 0
```

## ⚠️ Pitfalls [#️-pitfalls]

* “Persistent Redis” still needs backup/HA design — persistence ≠ full DR plan.
* Mixing cache and primary data on one instance without key discipline causes pain.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/redis/getting-started)
* [persistence.md](/docs/redis/persistence)
* [expiry\_ttl.md](/docs/redis/expiry-ttl)
* [README.md](/docs/redis)


# Hashes (/docs/redis/hashes)



# Hashes [#hashes]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Hashes map field → value under one key. Ideal for objects (user profiles, config bags) without serializing a whole JSON blob for every field update.

## 🔧 Core concepts [#-core-concepts]

| Command                | Role                    |
| ---------------------- | ----------------------- |
| `HSET key field value` | Set field               |
| `HGET key field`       | Get field               |
| `HGETALL key`          | All fields              |
| `HMGET`                | Multiple fields         |
| `HDEL`                 | Delete fields           |
| `HEXISTS`              | Field exists?           |
| `HINCRBY`              | Increment integer field |
| `HKEYS` / `HVALS`      | List fields/values      |

| When hash vs string JSON | Prefer hash when                 |
| ------------------------ | -------------------------------- |
| Partial updates          | Frequent single-field writes     |
| Memory                   | Many small fields (with caveats) |
| Atomic field incr        | `HINCRBY`                        |

## 💡 Examples [#-examples]

**User object:**

```shellscript
HSET user:42 name Ada email ada@example.com
HGET user:42 email
HGETALL user:42
```

**Increment field:**

```shellscript
HINCRBY user:42 login_count 1
```

**Delete field:**

```shellscript
HDEL user:42 email
```

## ⚠️ Pitfalls [#️-pitfalls]

* `HGETALL` on huge hashes is expensive — prefer `HSCAN`.
* Nested structures aren't native — store JSON in a field or use separate keys.
* TTL is on the whole hash key, not per field.

## 🔗 Related [#-related]

* [strings.md](/docs/redis/strings)
* [lists\_sets.md](/docs/redis/lists-sets)
* [expiry\_ttl.md](/docs/redis/expiry-ttl)
* [getting\_started.md](/docs/redis/getting-started)


# Redis (/docs/redis)



# Redis [#redis]

Cache, data structures, pub/sub.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Lists & Sets (/docs/redis/lists-sets)



# Lists & Sets [#lists--sets]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Lists are ordered sequences (queues, timelines). Sets are unordered unique collections (tags, membership). Both are foundational for queues and relationships.

## 🔧 Core concepts [#-core-concepts]

| List commands     | Role            |
| ----------------- | --------------- |
| `LPUSH` / `RPUSH` | Push left/right |
| `LPOP` / `RPOP`   | Pop left/right  |
| `LRANGE`          | Slice           |
| `LLEN`            | Length          |
| `BLPOP` / `BRPOP` | Blocking pop    |

| Set commands                  | Role               |
| ----------------------------- | ------------------ |
| `SADD` / `SREM`               | Add/remove members |
| `SISMEMBER`                   | Membership test    |
| `SMEMBERS`                    | All members        |
| `SINTER` / `SUNION` / `SDIFF` | Set algebra        |
| `SCARD`                       | Count              |

## 💡 Examples [#-examples]

**Simple queue:**

```shellscript
LPUSH jobs '{"id":1}'
BRPOP jobs 5
```

**Tags set:**

```shellscript
SADD post:9:tags redis cache
SISMEMBER post:9:tags redis
SINTER user:1:tags user:2:tags
```

**Recent items (list trim):**

```shellscript
LPUSH feed:42 itemA
LTRIM feed:42 0 99
```

## ⚠️ Pitfalls [#️-pitfalls]

* `SMEMBERS` / large `LRANGE` can block — use `SSCAN` / limit ranges.
* Lists allow duplicates; sets do not — pick the right structure.
* Blocking pops need careful timeouts in app servers to avoid stuck workers.

## 🔗 Related [#-related]

* [sorted\_sets.md](/docs/redis/sorted-sets)
* [hashes.md](/docs/redis/hashes)
* [pubsub.md](/docs/redis/pubsub)
* [strings.md](/docs/redis/strings)


# Persistence (/docs/redis/persistence)



# Persistence [#persistence]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Redis can persist in-memory data via RDB snapshots, AOF logs, or both. Persistence improves durability but is not a substitute for backups and replication strategy.

## 🔧 Core concepts [#-core-concepts]

| Mode           | How                               |
| -------------- | --------------------------------- |
| RDB            | Point-in-time `.rdb` snapshots    |
| AOF            | Append-only log of write commands |
| RDB+AOF        | Common hybrid                     |
| No persistence | Pure cache (accept data loss)     |

| Knob          | Meaning                      |
| ------------- | ---------------------------- |
| `save`        | RDB schedule                 |
| `appendonly`  | Enable AOF                   |
| `appendfsync` | `always` / `everysec` / `no` |
| Replica       | Continuity via replication   |

## 💡 Examples [#-examples]

**Check persistence config:**

```shellscript
redis-cli CONFIG GET save
redis-cli CONFIG GET appendonly
```

**Manual save:**

```shellscript
BGSAVE
LASTSAVE
```

**AOF rewrite:**

```shellscript
BGREWRITEAOF
```

## ⚠️ Pitfalls [#️-pitfalls]

* `appendfsync always` is safest and slowest — usually `everysec` is the compromise.
* Forking for `BGSAVE` on large datasets needs free memory headroom.
* Restoring from outdated RDB after a crash still loses recent writes if AOF is off.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/redis/getting-started)
* [expiry\_ttl.md](/docs/redis/expiry-ttl)
* [cli\_basics.md](/docs/redis/cli-basics)
* [Comparisons/redis\_vs\_postgres.md](/docs/redis/../comparisons/redis-vs-postgres)


# Pub/Sub (/docs/redis/pubsub)



# Pub/Sub [#pubsub]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Pub/Sub broadcasts messages to subscribers on channels. Fire-and-forget: if no subscriber is listening, messages are not queued (unlike Streams/lists).

## 🔧 Core concepts [#-core-concepts]

| Command                   | Role                        |
| ------------------------- | --------------------------- |
| `PUBLISH channel message` | Send message                |
| `SUBSCRIBE channel…`      | Subscribe (enters sub mode) |
| `PSUBSCRIBE pattern`      | Pattern subscribe           |
| `UNSUBSCRIBE`             | Leave channels              |
| `PUBSUB CHANNELS`         | List active channels        |

| vs alternatives | When                                   |
| --------------- | -------------------------------------- |
| Pub/Sub         | Live fan-out, presence                 |
| Lists           | Work queues with persistence in memory |
| Streams         | Consumer groups, replay                |

## 💡 Examples [#-examples]

**Publisher:**

```shellscript
PUBLISH news:alerts "deploy started"
```

**Subscriber (blocks):**

```shellscript
SUBSCRIBE news:alerts
```

**Pattern:**

```shellscript
PSUBSCRIBE news:*
```

## ⚠️ Pitfalls [#️-pitfalls]

* Subscribers must be connected at publish time — no backlog.
* A connection in subscribe mode cannot run normal commands until unsubscribed.
* For reliable messaging, prefer Streams or an external broker.

## 🔗 Related [#-related]

* [lists\_sets.md](/docs/redis/lists-sets)
* [getting\_started.md](/docs/redis/getting-started)
* [cli\_basics.md](/docs/redis/cli-basics)
* [persistence.md](/docs/redis/persistence)


# Sorted Sets (/docs/redis/sorted-sets)



# Sorted Sets [#sorted-sets]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Sorted sets (ZSETs) store unique members with a floating-point score. Ideal for leaderboards, time indexes, and range queries by score or rank.

## 🔧 Core concepts [#-core-concepts]

| Command                 | Role               |
| ----------------------- | ------------------ |
| `ZADD key score member` | Add/update         |
| `ZRANGE`                | By rank (low→high) |
| `ZREVRANGE`             | By rank high→low   |
| `ZRANGEBYSCORE`         | By score range     |
| `ZRANK` / `ZREVRANK`    | Rank of member     |
| `ZSCORE`                | Score of member    |
| `ZINCRBY`               | Increment score    |
| `ZREM`                  | Remove member      |
| `ZCARD` / `ZCOUNT`      | Counts             |

| Use case    | Score idea     |
| ----------- | -------------- |
| Leaderboard | Points         |
| Schedule    | Unix timestamp |
| Rate window | Event time     |

## 💡 Examples [#-examples]

**Leaderboard:**

```shellscript
ZADD lb:game 100 alice 250 bob 180 cara
ZREVRANGE lb:game 0 2 WITHSCORES
ZINCRBY lb:game 20 alice
```

**Due jobs by time:**

```shellscript
ZADD queue:due 1735689600 job:1
ZRANGEBYSCORE queue:due -inf +inf LIMIT 0 10
```

## ⚠️ Pitfalls [#️-pitfalls]

* Members are unique — re-`ZADD` updates the score.
* Large ranges without `LIMIT` can return huge payloads.
* Lexicographical commands (`ZRANGEBYLEX`) require same score — easy to misuse.

## 🔗 Related [#-related]

* [lists\_sets.md](/docs/redis/lists-sets)
* [expiry\_ttl.md](/docs/redis/expiry-ttl)
* [cli\_basics.md](/docs/redis/cli-basics)
* [getting\_started.md](/docs/redis/getting-started)


# Strings (/docs/redis/strings)



# Strings [#strings]

*Redis · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Strings are the simplest Redis values: text, integers (for counters), or binary blobs (up to 512 MB theoretically; keep small in practice).

## 🔧 Core concepts [#-core-concepts]

| Command                    | Role              |
| -------------------------- | ----------------- |
| `SET key value`            | Set string        |
| `GET key`                  | Get string        |
| `MSET` / `MGET`            | Multi set/get     |
| `SETNX`                    | Set if not exists |
| `INCR` / `DECR`            | Integer increment |
| `APPEND`                   | Append to string  |
| `GETRANGE` / `SETRANGE`    | Substring ops     |
| `SET key value EX seconds` | Set with TTL      |

| Option          | Meaning                          |
| --------------- | -------------------------------- |
| `EX` / `PX`     | Expire seconds / ms              |
| `NX` / `XX`     | Only if missing / only if exists |
| `GET` (SET GET) | Return old value (Redis 6.2+)    |

## 💡 Examples [#-examples]

**Cache entry:**

```shellscript
SET user:42:profile '{"name":"Ada"}' EX 3600
GET user:42:profile
```

**Counter:**

```shellscript
INCR page:home:views
GET page:home:views
```

**Lock-style NX:**

```shellscript
SET lock:job1 1 NX EX 30
```

## ⚠️ Pitfalls [#️-pitfalls]

* `INCR` fails if the value is not an integer string.
* Huge strings block peers longer during ops — split or use other structures.
* `KEYS *` in production is dangerous — use `SCAN`.

## 🔗 Related [#-related]

* [hashes.md](/docs/redis/hashes)
* [expiry\_ttl.md](/docs/redis/expiry-ttl)
* [cli\_basics.md](/docs/redis/cli-basics)
* [getting\_started.md](/docs/redis/getting-started)


# Annotating Basics (/docs/typescript/annotating-basics)



# Annotating Basics [#annotating-basics]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Type annotations tell TypeScript what shape a value should have. You can annotate variables, parameters, and return types. Often TS **infers** types, so you only annotate where it helps clarity or catches mistakes.

## 🔧 Core concepts [#-core-concepts]

| Place     | Example                          | Notes                                   |
| --------- | -------------------------------- | --------------------------------------- |
| Variable  | `let n: number = 1`              | Often inferred from the right-hand side |
| Parameter | `function f(x: string)`          | Annotate public function inputs         |
| Return    | `function f(): boolean`          | Optional but useful for exports         |
| Array     | `number[]` or `Array<number>`    | Same idea                               |
| Object    | `\{ id: number; name: string \}` | Or a `type` / `interface` alias         |
| Union     | `string \| null`                 | One of several types                    |

Start with primitives, arrays, and simple object types before generics.

## 💡 Examples [#-examples]

**Variables and inference:**

```ts
const count: number = 3;
const label = "docs"; // inferred as string
// label = 1; // Error
console.log(count, label);
```

**Functions:**

```ts
function clamp(n: number, min: number, max: number): number {
  return Math.min(max, Math.max(min, n));
}

console.log(clamp(15, 0, 10)); // 10
```

**Objects and arrays:**

```ts
type Point = { x: number; y: number };

const origin: Point = { x: 0, y: 0 };
const path: Point[] = [origin, { x: 1, y: 1 }];
console.log(path.length);
```

**Union and optional:**

```ts
function titleCase(text: string | null): string {
  if (text == null || text.length === 0) return "";
  return text[0].toUpperCase() + text.slice(1);
}

console.log(titleCase("ada"));
console.log(titleCase(null));
```

## ⚠️ Pitfalls [#️-pitfalls]

* Redundant annotations (`const x: number = 1`) are fine while learning; later prefer inference.
* `any` turns off checking — use `unknown` if you must accept “something.”
* Optional (`?`) and `| undefined` interact with `strictNullChecks`.
* Annotating the wrong type and forcing with `as` hides real bugs.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/typescript/hello-world)
* [why\_typescript.md](/docs/typescript/why-typescript)
* [tsconfig\_basics.md](/docs/typescript/tsconfig-basics)
* [getting\_started.md](/docs/typescript/getting-started)


# any, unknown, never (/docs/typescript/any-unknown-never)



# any, unknown, never [#any-unknown-never]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`any` disables checking; `unknown` is the safe top type (must narrow before use); `never` is the bottom type (no values). Prefer `unknown` over `any` at boundaries; use `never` for exhaustiveness and impossible states.

## 🔧 Core concepts [#-core-concepts]

| Type      | Assignability                                           | Use                             |
| --------- | ------------------------------------------------------- | ------------------------------- |
| `any`     | Assignable to/from almost everything                    | Escape hatch, gradual typing    |
| `unknown` | Accepts any value; not assignable out without narrowing | Untrusted input, JSON, catch    |
| `never`   | Assignable *to* every type; nothing assignable *to* it  | Exhaustive checks, empty unions |

* **`strict` / `noImplicitAny`** — missing annotations become errors, not implicit `any`.
* **Empty intersection** — `string & number` → `never`.
* **Functions that throw / infinite loop** — return type `never`.

## 💡 Examples [#-examples]

```ts
function parseJson(raw: string): unknown {
  return JSON.parse(raw);
}

const data = parseJson('{"n":1}');
if (
  typeof data === "object" &&
  data !== null &&
  "n" in data &&
  typeof (data as { n: unknown }).n === "number"
) {
  console.log((data as { n: number }).n);
}

function assertNever(x: never): never {
  throw new Error(`Unexpected: ${x}`);
}

type Shape = { kind: "circle"; r: number } | { kind: "square"; s: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle":
      return Math.PI * s.r ** 2;
    case "square":
      return s.s ** 2;
    default:
      return assertNever(s); // error if a variant is missing
  }
}

function fail(msg: string): never {
  throw new Error(msg);
}

// any: opt-out (avoid in new code)
function legacy(x: any) {
  return x.foo.bar; // no check
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `any` infects call sites — one `any` can silence whole chains.
* `catch (e)` is `unknown` under `useUnknownInCatchVariables` (recommended).
* `never[]` is assignable to any array type — don’t confuse with “empty array of T”.
* Returning `never` from a branch that can complete is a type error.
* Prefer typed Zod / validators over casting `unknown` to concrete types blindly.

## 🔗 Related [#-related]

* [type\_guards.md](/docs/typescript/type-guards)
* [type\_assertions.md](/docs/typescript/type-assertions)
* [discriminated\_unions.md](/docs/typescript/discriminated-unions)
* [strict\_options.md](/docs/typescript/strict-options)
* [zod\_integration.md](/docs/typescript/zod-integration)


# Branded types (/docs/typescript/branded-types)



# Branded types [#branded-types]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Branded (nominal) types make structurally identical primitives incompatible — e.g. `UserId` vs `OrderId` both based on `string`. Use an intersection with a unique phantom property so the compiler rejects accidental mixes.

## 🔧 Core concepts [#-core-concepts]

* **Brand** — `type UserId = string & \{ readonly __brand: "UserId" \}`.
* **Constructors** — small helpers / assertions to create branded values.
* **Erase at runtime** — brand exists only in the type system.
* **Zod** — `z.string().brand&lt;"UserId">()` (Zod 3+) for parse + brand.
* **vs enums** — brands keep primitive ergonomics without runtime objects.

## 💡 Examples [#-examples]

```ts
declare const __brand: unique symbol;
type Brand<T, B> = T & { readonly [__brand]: B };

type UserId = Brand<string, "UserId">;
type OrderId = Brand<string, "OrderId">;

function UserId(s: string): UserId {
  return s as UserId;
}
function OrderId(s: string): OrderId {
  return s as OrderId;
}

function loadUser(id: UserId) {
  /* ... */
}

const uid = UserId("u_1");
const oid = OrderId("o_9");
loadUser(uid);
// loadUser(oid); // error — OrderId not assignable to UserId
// loadUser("u_1"); // error — plain string rejected

type USD = Brand<number, "USD">;
type EUR = Brand<number, "EUR">;
const price = 10 as USD;
```

```ts
// Unique symbol brand (stronger uniqueness)
type Email = string & { readonly __email: unique symbol };
```

## ⚠️ Pitfalls [#️-pitfalls]

* Brands don’t validate format — pair with Zod / regex at boundaries.
* `as UserId` can forge invalid IDs — keep constructors in one module.
* Object brands with real `__brand` fields leak to runtime if you set them — use phantom types only.
* JSON / DB layers return plain strings — re-brand after validation.
* Excess structural typing still applies to non-branded object shapes.

## 🔗 Related [#-related]

* [zod\_integration.md](/docs/typescript/zod-integration)
* [type\_assertions.md](/docs/typescript/type-assertions)
* [literal\_types.md](/docs/typescript/literal-types)
* [interfaces.md](/docs/typescript/interfaces)
* [any\_unknown\_never.md](/docs/typescript/any-unknown-never)


# Class (/docs/typescript/class)



# Class [#class]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

TypeScript classes add parameter properties, visibility modifiers, `readonly`, `abstract`, and typed `implements`/`extends`. Emit targets and `useDefineForClassFields` affect field initialization semantics in TS 5.x.

## 🧩 Core concepts [#-core-concepts]

* **Visibility** — `public` (default), `protected`, `private` (compile-time); `#private` is true runtime privacy.
* **Parameter properties** — `constructor(private name: string)` declares and assigns in one step.
* **`readonly` / `static` / `abstract`** — immutability, class-level members, base-only APIs.
* **`implements`** — structural check against an interface; does not generate runtime artifacts.
* **`override`** — marks intentional overrides (`noImplicitOverride` recommended).
* **Generic classes** — `class Box<T> \{ ... \}`.

## 💡 Examples [#-examples]

```ts
interface Identifiable {
  id: string;
}

abstract class Entity implements Identifiable {
  constructor(public readonly id: string) {}
  abstract summarize(): string;
}

class User extends Entity {
  #passwordHash: string;

  constructor(id: string, public name: string, passwordHash: string) {
    super(id);
    this.#passwordHash = passwordHash;
  }

  override summarize(): string {
    return `${this.id}:${this.name}`;
  }

  static fromJson(json: { id: string; name: string }): User {
    return new User(json.id, json.name, "");
  }
}

class Repo<T extends Identifiable> {
  constructor(private items: T[] = []) {}
  get(id: string): T | undefined {
    return this.items.find((i) => i.id === id);
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `private` is erased at compile time — use `#fields` for runtime encapsulation.
* Class fields vs constructor assignment differ under `useDefineForClassFields` / target ES2022+.
* Implementing an interface does not copy default values or methods — only checks shape.
* Arrow-function class fields are not on the prototype (affects inheritance/`this` binding).

## 🔗 Related [#-related]

* [Object types](/docs/typescript/object-types)
* [Decorators](/docs/typescript/decorators)
* [Generic types](/docs/typescript/generic-types)
* [Type guards](/docs/typescript/type-guards)
* [Module](/docs/typescript/module)


# Command Line (/docs/typescript/commandline)



# Command Line [#command-line]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

The TypeScript compiler CLI (`tsc`) type-checks and optionally emits JavaScript. Install via `typescript` and run with `npx tsc` or a local `node_modules` binary. Most options mirror `tsconfig.json` compiler flags.

## 🧩 Core concepts [#-core-concepts]

* **Project mode** — `tsc -p tsconfig.json` (default: nearest/implicit config).
* **Emit vs check** — `noEmit` / `--noEmit` for CI typecheck; omit for JS output.
* **Watch** — `--watch` / `-w` rebuilds on change.
* **Incremental** — `--incremental` + `.tsbuildinfo` for faster rebuilds.
* **Build mode** — `tsc -b` for project references (`composite` projects).
* **Show config** — `--showConfig` prints the effective resolved config.

## 💡 Examples [#-examples]

```shellscript
# Install
npm install -D typescript
npx tsc --version

# Init a tsconfig
npx tsc --init

# Typecheck only (CI-friendly)
npx tsc -p tsconfig.json --noEmit

# Emit to outDir from config
npx tsc -p tsconfig.json

# Watch mode
npx tsc -p tsconfig.json --watch

# Build solution (project references)
npx tsc -b packages/utils packages/app --force

# One-off compile without relying on config paths
npx tsc src/index.ts --target ES2022 --module NodeNext --outdir dist

# Effective config
npx tsc --showConfig

# Common flags
npx tsc --strict --pretty false --listFiles false
```

`package.json` scripts:

```json
{
  "scripts": {
    "typecheck": "tsc -p tsconfig.json --noEmit",
    "build": "tsc -p tsconfig.json"
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* CLI flags override `tsconfig` when both are set — know which wins for CI.
* Compiling a single `.ts` file ignores most of your project `paths`/`include` setup.
* `tsc -b` requires `composite: true` (and usually `declaration: true`) on referenced projects.
* Global `tsc` may be an older version than the project’s local TypeScript — prefer `npx`/`npm exec`.

## 🔗 Related [#-related]

* [Config](/docs/typescript/config)
* [Module](/docs/typescript/module)
* [Types](/docs/typescript/types)
* [Decorators](/docs/typescript/decorators)
* [Class](/docs/typescript/class)


# Conditional Types (/docs/typescript/conditional-types)



# Conditional Types [#conditional-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Conditional types choose a type based on a check: `T extends U ? X : Y`. They power many built-in utilities and enable distributive logic over unions. Prefer them for type-level branching, not runtime control flow.

## 🧩 Core concepts [#-core-concepts]

* **Basic form** — `T extends U ? TrueBranch : FalseBranch`.
* **Distributive conditionals** — naked type params distribute over unions (`A | B` becomes two checks).
* **`infer`** — extract a type variable from a matched pattern (e.g. Promise payload, function return).
* **Non-distributive** — wrap in a tuple `[T] extends [U]` to disable distribution.
* **Filtering unions** — `T extends U ? T : never` keeps matching members.

## 💡 Examples [#-examples]

```ts
type IsString<T> = T extends string ? true : false;
type A = IsString<"hi">; // true
type B = IsString<42>; // false

// Distributive: applied per union member
type ToArray<T> = T extends unknown ? T[] : never;
type Arr = ToArray<string | number>; // string[] | number[]

// infer
type AwaitedLike<T> = T extends Promise<infer U> ? U : T;
type V = AwaitedLike<Promise<number>>; // number

type ReturnOf<F> = F extends (...args: never[]) => infer R ? R : never;
type R = ReturnOf<() => boolean>; // boolean

// Filter
type OnlyStrings<T> = T extends string ? T : never;
type S = OnlyStrings<"a" | 1 | "b">; // "a" | "b"

// Non-distributive
type IsUnion<T> = [T] extends [never]
  ? false
  : [T] extends [infer U]
    ? [U] extends [T]
      ? false
      : true
    : never;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting distribution leads to unexpected `never` or overly wide results.
* `infer` only works in the `extends` clause of a conditional.
* Deep recursive conditionals can hit instantiation depth limits — keep them shallow.
* Prefer built-ins (`Extract`, `Exclude`, `Awaited`) when they already express the idea.

## 🔗 Related [#-related]

* [Generic types](/docs/typescript/generic-types)
* [Mapped types](/docs/typescript/mapped-types)
* [Utility types](/docs/typescript/utility-types)
* [Union types](/docs/typescript/union-types)
* [Types](/docs/typescript/types)


# Config (/docs/typescript/config)



# Config [#config]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

`tsconfig.json` configures the TypeScript compiler: language target, module system, strictness, path aliases, and project references. Prefer a root config with `"include"`/`"exclude"` and extend shared bases in monorepos.

## 🧩 Core concepts [#-core-concepts]

* **`compilerOptions`** — core switches (`target`, `module`, `strict`, `jsx`, etc.).
* **`include` / `exclude` / `files`** — which sources participate in the program.
* **`extends`** — inherit from another config (npm packages like `@tsconfig/strictest`).
* **Project references** — `composite` + `references` for multi-package builds.
* **`moduleResolution`** — how imports resolve (`bundler`, `node16`, `nodenext`).
* **Strict family** — `strict` enables `strictNullChecks`, `noImplicitAny`, and related flags.

## 💡 Examples [#-examples]

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "DOM"],
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "rootDir": "src",
    "outDir": "dist",
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "dist"]
}
```

Bundler-oriented (Vite/Next-style):

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "moduleDetection": "force",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}
```

Extend + references sketch:

```json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": { "composite": true },
  "references": [{ "path": "../utils" }]
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `paths` aliases are not rewritten by `tsc` — align bundler/runtime resolvers.
* Mixing `module: CommonJS` with ESM `"type": "module"` causes runtime friction.
* `skipLibCheck` speeds builds but can hide `.d.ts` issues in dependencies.
* Forgetting `"include"` may pull unexpected files from the directory tree.

## 🔗 Related [#-related]

* [Command line](/docs/typescript/commandline)
* [Module](/docs/typescript/module)
* [Decorators](/docs/typescript/decorators)
* [Types](/docs/typescript/types)
* [Class](/docs/typescript/class)


# Const assertions (/docs/typescript/const-assertions)



# Const assertions [#const-assertions]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`as const` asserts a value is deeply readonly with the narrowest literal types. Use it for config objects, route tables, and tuple literals so `keyof` / indexed access stay precise. Pairs well with `satisfies`.

## 🔧 Core concepts [#-core-concepts]

* **Literals** — `"ok" as const` → type `"ok"` (not `string`).
* **Arrays → readonly tuples** — `[1, "a"] as const` → `readonly [1, "a"]`.
* **Objects** — all props `readonly`; nested values narrowed.
* **Enum alternative** — `as const` object + `(typeof O)[keyof typeof O]`.
* **Mutable copy** — spread or typed mutable alias when mutation is required.

## 💡 Examples [#-examples]

```ts
const status = "success" as const; // "success"

const point = [10, 20] as const;
// readonly [10, 20]
point[0]; // 10

const config = {
  host: "localhost",
  port: 5432,
  features: ["auth", "cache"],
} as const;

type Config = typeof config;
type Feature = (typeof config.features)[number]; // "auth" | "cache"

const Routes = {
  home: "/",
  user: "/users/:id",
} as const;
type RouteKey = keyof typeof Routes;
type RoutePath = (typeof Routes)[RouteKey];

// With satisfies — narrow + validate
type Theme = { primary: string; radius: number };
const theme = {
  primary: "#336699",
  radius: 8,
} as const satisfies Theme;

// Function args
function move(dir: "up" | "down") {}
const dirs = ["up", "down"] as const;
move(dirs[0]);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `as const` makes structures readonly — assigning to props fails.
* Widening returns if you annotate `: string[]` instead of using `as const`.
* `as const` on mutable class fields doesn’t freeze at runtime — only types.
* Large const objects can slow the checker — split modules if needed.
* Runtime still mutable unless you also `Object.freeze` (shallow).

## 🔗 Related [#-related]

* [satisfies.md](/docs/typescript/satisfies)
* [literal\_types.md](/docs/typescript/literal-types)
* [readonly.md](/docs/typescript/readonly)
* [keyof\_typeof.md](/docs/typescript/keyof-typeof)
* [tuple\_types.md](/docs/typescript/tuple-types)
* [enums.md](/docs/typescript/enums)


# Declaration files (.d.ts) (/docs/typescript/declaration-files)



# Declaration files (.d.ts) [#declaration-files-dts]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Declaration files describe types for JavaScript libraries and ambient globals without emitting runtime code. Use them for untyped deps, augmenting modules, and publishing typed packages (`types` / `exports` in `package.json`).

## 🔧 Core concepts [#-core-concepts]

| Pattern                       | Purpose                   |
| ----------------------------- | ------------------------- |
| `declare module "pkg"`        | Types for a module        |
| `declare module "*.css"`      | Wildcard asset modules    |
| `declare global \{ \}`        | Augment global scope      |
| `export \{\}`                 | Force file to be a module |
| `export as namespace`         | UMD / global + module     |
| Triple-slash `/// <reference` | Legacy refs / lib deps    |

* **DefinitelyTyped** — `@types/name` packages.
* **Bundled types** — library ships its own `.d.ts`.
* **`allowJs` + `checkJs` / JSDoc** — infer types from JS without hand-written d.ts.

## 💡 Examples [#-examples]

```ts
// types/shim.d.ts
declare module "legacy-lib" {
  export function doThing(x: string): number;
  const legacyLib: { version: string };
  export default legacyLib;
}

declare module "*.svg" {
  const url: string;
  export default url;
}

// Augment global
export {}; // make this a module
declare global {
  interface Window {
    APP_VERSION: string;
  }
  var APP_VERSION: string;
}

// Ambient namespace (older libs)
declare namespace MyLib {
  function init(opts: { debug?: boolean }): void;
}
```

```json
// package.json (publisher)
{
  "name": "my-lib",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `export \{\}` in an augment file can accidentally create a script global scope.
* Duplicate `@types` + bundled types cause conflicts — prefer package’s own types.
* `declare module` without proper exports leads to `any` default imports.
* Don’t commit generated `.d.ts` that drift from source — emit from `tsc` / bundler.
* Path mapping in `tsconfig` must resolve `.d.ts` consistently in editors and CI.

## 🔗 Related [#-related]

* [module.md](/docs/typescript/module)
* [namespaces.md](/docs/typescript/namespaces)
* [config.md](/docs/typescript/config)
* [types.md](/docs/typescript/types)
* [strict\_options.md](/docs/typescript/strict-options)


# Decorators (/docs/typescript/decorators)



# Decorators [#decorators]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Decorators wrap or annotate classes and members. TypeScript 5.0+ supports the Stage 3 ECMAScript decorator model when `experimentalDecorators` is off (default). Legacy decorators remain available via `experimentalDecorators: true` for older frameworks.

## 🧩 Core concepts [#-core-concepts]

* **ES decorators (TS 5.x default path)** — functions applied with `@dec` on class/methods/fields/getters/setters/accessors.
* **Context object** — receives `kind`, `name`, `addInitializer`, `access`, `private`, `static`.
* **Class decorators** — receive the class (or replace it) and optional context.
* **Member decorators** — wrap methods or initialize fields; return a replacement function/value where allowed.
* **Legacy mode** — `experimentalDecorators` + often `emitDecoratorMetadata` for Reflect metadata (NestJS, older Angular).
* **Composition** — multiple decorators apply bottom-up (nearest to the member first).

## 💡 Examples [#-examples]

```ts
// tsconfig: "experimentalDecorators": false (ES decorators)

function logged<This, Args extends unknown[], Return>(
  value: (this: This, ...args: Args) => Return,
  context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
  return function (this: This, ...args: Args): Return {
    console.log(`call ${String(context.name)}`);
    return value.apply(this, args);
  };
}

class Calculator {
  @logged
  add(a: number, b: number) {
    return a + b;
  }
}

function seal(value: Function, _context: ClassDecoratorContext) {
  Object.seal(value);
  Object.seal(value.prototype);
}

@seal
class Config {}
```

Legacy-style (when `experimentalDecorators: true`):

```ts
function deprecated(target: object, propertyKey: string | symbol) {
  console.warn(`${String(propertyKey)} is deprecated`);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* ES and legacy decorator APIs are incompatible — match your framework’s expected mode.
* `emitDecoratorMetadata` only applies to legacy decorators and emits design:type metadata.
* Decorators are not enabled for parameter decoration in the new ES model the same way as legacy.
* Order and replacement semantics differ between modes — test against your runtime.

## 🔗 Related [#-related]

* [Class](/docs/typescript/class)
* [Config](/docs/typescript/config)
* [Module](/docs/typescript/module)
* [Types](/docs/typescript/types)
* [Command line](/docs/typescript/commandline)


# Discriminated unions (/docs/typescript/discriminated-unions)



# Discriminated unions [#discriminated-unions]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A discriminated (tagged) union shares a common literal field (the discriminant). Narrowing on that field unlocks variant-specific properties. Prefer this pattern for results, events, and state machines over optional-field bags.

## 🔧 Core concepts [#-core-concepts]

* **Tag** — shared property with distinct string/number literals (`kind`, `type`, `status`).
* **Narrowing** — `switch` / `if` on the tag refines the union.
* **Exhaustiveness** — `never` check in `default` catches missing cases.
* **vs optionals** — `\{ error?: string; data?: T \}` is weaker than `\{ ok: true; data: T \} | \{ ok: false; error: string \}`.
* **Nested tags** — works with multiple levels if each level has a discriminant.

## 💡 Examples [#-examples]

```ts
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "rect"; w: number; h: number }
  | { kind: "triangle"; base: number; height: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle":
      return Math.PI * s.radius ** 2;
    case "rect":
      return s.w * s.h;
    case "triangle":
      return (s.base * s.height) / 2;
    default: {
      const _exhaustive: never = s;
      return _exhaustive;
    }
  }
}

type Result<T> =
  | { ok: true; value: T }
  | { ok: false; error: string };

function unwrap<T>(r: Result<T>): T {
  if (r.ok) return r.value;
  throw new Error(r.error);
}

type Event =
  | { type: "click"; x: number; y: number }
  | { type: "key"; key: string };
```

```ts
// Bad: optional soup — no reliable narrowing
type Loose = { kind?: string; radius?: number; w?: number };
```

## ⚠️ Pitfalls [#️-pitfalls]

* Discriminant must be a literal type — plain `string` won’t narrow.
* Mutating the tag after narrowing can confuse control flow (prefer immutable data).
* Overlapping tags (`kind: string` on one variant) break discrimination.
* Don’t put unrelated fields on all variants “just in case” — keep variants lean.
* JSON parse still needs runtime checks — types don’t validate tags.

## 🔗 Related [#-related]

* [union\_types.md](/docs/typescript/union-types)
* [type\_guards.md](/docs/typescript/type-guards)
* [any\_unknown\_never.md](/docs/typescript/any-unknown-never)
* [literal\_types.md](/docs/typescript/literal-types)
* [zod\_integration.md](/docs/typescript/zod-integration)


# Enums (/docs/typescript/enums)



# Enums [#enums]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Enums name a fixed set of related constants. Prefer string enums or union literals for most APIs; numeric enums are useful for bit flags and interop with C-style APIs. Const enums inline members at compile time.

## 🔧 Core concepts [#-core-concepts]

| Kind          | Shape                   | Notes                              |
| ------------- | ----------------------- | ---------------------------------- |
| Numeric       | `enum E \{ A, B = 2 \}` | Auto-increment; reverse mapping    |
| String        | `enum E \{ A = "a" \}`  | No reverse map; clearer logs       |
| Heterogeneous | mix number + string     | Avoid — confusing                  |
| `const enum`  | erased to literals      | Needs `preserveConstEnums` to keep |
| Ambient       | `declare enum`          | Types only, no emit                |

* **Union alternative** — `type Status = "ok" | "err"` is often enough (TS 5.x).
* **`as const` object** — `const Status = \{ Ok: "ok" \} as const` + `typeof` / `keyof`.

## 💡 Examples [#-examples]

```ts
enum Direction {
  Up,      // 0
  Down,    // 1
  Left = 10,
  Right,   // 11
}

Direction.Up;       // 0
Direction[0];       // "Up" (numeric reverse map)

enum Color {
  Red = "RED",
  Blue = "BLUE",
}

function paint(c: Color) {
  return c === Color.Red;
}

const enum Flag {
  Read = 1 << 0,
  Write = 1 << 1,
}
const mode = Flag.Read | Flag.Write; // inlined numbers

// Prefer unions for public APIs
type Role = "admin" | "user" | "guest";

const Http = {
  Ok: 200,
  NotFound: 404,
} as const;
type HttpCode = (typeof Http)[keyof typeof Http]; // 200 | 404
```

```ts
// IsolatedModules / erasableSyntaxOnly (TS 5.x): prefer
// `const enum` carefully or use unions — classic enums emit JS.
```

## ⚠️ Pitfalls [#️-pitfalls]

* Numeric enums are not a closed set at runtime — any `number` can be assigned unless you narrow.
* Reverse mapping only exists for numeric enums; `Color["RED"]` is undefined for string enums.
* `const enum` + `isolatedModules` / Babel can break if the enum isn’t preserved.
* Prefer string unions over enums when you don’t need a runtime object.
* Declaring members without initializers after a string member is an error.

## 🔗 Related [#-related]

* [literal\_types.md](/docs/typescript/literal-types)
* [const\_assertions.md](/docs/typescript/const-assertions)
* [union\_types.md](/docs/typescript/union-types)
* [keyof\_typeof.md](/docs/typescript/keyof-typeof)
* [namespaces.md](/docs/typescript/namespaces)


# Generic Types (/docs/typescript/generic-types)



# Generic Types [#generic-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Generics parameterize types and functions over other types (`<T>`), preserving relationships between inputs and outputs. Constraints (`extends`) limit what `T` may be; defaults provide fallbacks.

## 🧩 Core concepts [#-core-concepts]

* **Type parameters** — `function identity<T>(value: T): T`.
* **Constraints** — `T extends \{ id: string \}` requires a minimum shape.
* **Defaults** — `type Box<T = string> = \{ value: T \}`.
* **Generic interfaces / classes / type aliases** — same idea across constructs.
* **Inference** — usually from arguments; annotate when inference fails or is too wide.
* **`keyof` + indexed access** — `T[K]` pairs well with constrained keys.

## 💡 Examples [#-examples]

```ts
function identity<T>(value: T): T {
  return value;
}
const n = identity(42); // number

function pluck<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}
pluck({ name: "Ada", age: 36 }, "name"); // string

interface ApiResponse<T> {
  data: T;
  error?: string;
}

type Paginated<T> = {
  items: T[];
  total: number;
};

class Repo<T extends { id: string }> {
  constructor(private items: T[] = []) {}
  find(id: string): T | undefined {
    return this.items.find((i) => i.id === id);
  }
}

// Default type arg
type Result<T = unknown> = { ok: true; value: T } | { ok: false };
```

## ⚠️ Pitfalls [#️-pitfalls]

* Unconstrained `T` inside a function is treated like `unknown` for property access.
* Over-constraining (`T extends any`) adds noise without safety.
* Generic rest/tuple inference can surprise — add explicit type args when needed.
* Don’t use generics when a concrete union or overload is clearer.

## 🔗 Related [#-related]

* [Conditional types](/docs/typescript/conditional-types)
* [Mapped types](/docs/typescript/mapped-types)
* [Utility types](/docs/typescript/utility-types)
* [Class](/docs/typescript/class)
* [Types](/docs/typescript/types)


# Getting Started with TypeScript (/docs/typescript/getting-started)



# Getting Started with TypeScript [#getting-started-with-typescript]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

TypeScript (TS) is JavaScript plus a static type system. You write `.ts` / `.tsx` files; the compiler (`tsc`) checks types and emits plain JavaScript. Types exist at compile time — they are erased at runtime.

## 🔧 Core concepts [#-core-concepts]

| Idea            | Meaning                                          |
| --------------- | ------------------------------------------------ |
| Type checker    | Catches many bugs before running code            |
| `tsc`           | Official TypeScript compiler CLI                 |
| `tsconfig.json` | Project compiler options                         |
| Emit            | Output `.js` (and optional `.d.ts` declarations) |
| Gradual typing  | You can add types step by step                   |

**Prereqs:** Node.js installed. Then `npm install -D typescript` in a project (or use `npx tsc`).

## 💡 Examples [#-examples]

**Install and check version:**

```shellscript
npm install -D typescript
npx tsc --version
```

**Tiny file (`hello.ts`):**

```ts
const message: string = "Hello, TypeScript";
console.log(message);
```

**Compile and run:**

```shellscript
npx tsc hello.ts
node hello.js
```

**Minimal `tsconfig.json`:**

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "strict": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Running `.ts` directly needs `tsx`, `ts-node`, or a bundler — Node does not execute TS natively (without experimental flags).
* Types do not exist at runtime: `typeof` still sees JS values only.
* Skipping `"strict": true` hides the value of TypeScript.
* Editing emitted `.js` by hand will be overwritten on next compile.

## 🔗 Related [#-related]

* [hello\_world.md](/docs/typescript/hello-world)
* [why\_typescript.md](/docs/typescript/why-typescript)
* [tsconfig\_basics.md](/docs/typescript/tsconfig-basics)
* [annotating\_basics.md](/docs/typescript/annotating-basics)


# Glossary (/docs/typescript/glossary)



# Glossary [#glossary]

*Typescript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of core TypeScript terms for types, narrowing, generics, modules, and compiler options.

## 🔧 Core concepts [#-core-concepts]

| Term                | Definition                                                                      |     |
| ------------------- | ------------------------------------------------------------------------------- | --- |
| Any                 | An escape-hatch type that disables most type checking for a value.              |     |
| Assertion           | A `as Type` or angle-bracket cast that tells the checker to trust a type.       |     |
| Branded type        | A nominal-style type created by intersecting a primitive with a unique tag.     |     |
| Conditional type    | A type that chooses between alternatives with `T extends U ? X : Y`.            |     |
| Const assertion     | `as const` that infers the narrowest literal and readonly types.                |     |
| Declaration file    | A `.d.ts` file that describes types for JavaScript or ambient APIs.             |     |
| Discriminated union | A union of object types sharing a common literal “tag” property.                |     |
| Enum                | A named set of related constants, numeric or string-based.                      |     |
| Generic             | A type or function parameterized by one or more type variables.                 |     |
| Infer               | A keyword inside conditional types that extracts a nested type into a variable. |     |
| Interface           | A named object shape that can be extended and merged by declaration.            |     |
| Intersection        | A type combining members of several types with `&`.                             |     |
| Keyof               | An operator producing a union of an object type’s property names.               |     |
| Literal type        | A type that is exactly one specific string, number, or boolean value.           |     |
| Mapped type         | A type that transforms each property of another type via `[K in Keys]`.         |     |
| Module              | A file with import/export that creates its own scope and type namespace.        |     |
| Narrowing           | Refining a broad type to a more specific one via checks.                        |     |
| Never               | The empty type for values that never occur, such as exhausted switches.         |     |
| Readonly            | A modifier or utility that makes properties immutable at the type level.        |     |
| Satisfies           | An operator that checks a value against a type without widening inference.      |     |
| Strict mode         | Compiler flags like `strictNullChecks` that tighten soundness.                  |     |
| Tuple               | A fixed-length array type where each index may have its own type.               |     |
| Type alias          | A `type` name that refers to any type expression.                               |     |
| Type guard          | A check (including user-defined predicates) that narrows types.                 |     |
| Typeof              | An operator that produces the type of a value in type position.                 |     |
| Union               | A type that may be one of several alternatives joined with \`                   | \`. |
| Unknown             | A type-safe top type that must be narrowed before use.                          |     |
| Utility type        | Built-in helpers such as `Partial`, `Pick`, `Omit`, and `Record`.               |     |
| Zod                 | A popular runtime schema library often paired with TypeScript inference.        |     |

## 💡 Examples [#-examples]

**Discriminated union and narrowing:**

```ts
type Result =
  | { ok: true; data: string }
  | { ok: false; error: string };

function message(r: Result) {
  return r.ok ? r.data : r.error;
}
```

**Generics and utility types:**

```ts
function pickId<T extends { id: string }>(item: T): Pick<T, "id"> {
  return { id: item.id };
}
```

**Satisfies vs assertion:**

```ts
const routes = {
  home: "/",
  about: "/about",
} satisfies Record<string, `/${string}`>;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Confusing **any** (unchecked) with **unknown** (must narrow before use).
* Mixing **interface** and **type alias** — interfaces merge; aliases are more flexible for unions.
* Using a **type assertion** when a **type guard** or refactor would be safer.
* Treating **enum** and **union of literals** as interchangeable — emit and ergonomics differ.
* Assuming **satisfies** changes the value’s inferred type the same way `as` does — it validates without forcing the annotation type.

## 🔗 Related [#-related]

* [union\_types](/docs/typescript/union-types)
* [generic\_types](/docs/typescript/generic-types)
* [type\_guards](/docs/typescript/type-guards)
* [discriminated\_unions](/docs/typescript/discriminated-unions)
* [utility\_types](/docs/typescript/utility-types)
* [satisfies](/docs/typescript/satisfies)


# Hello World (/docs/typescript/hello-world)



# Hello World [#hello-world]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

A TypeScript Hello World is a tiny typed program that compiles to JavaScript and prints a message. It proves `tsc` (or your runner) is wired correctly.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                                          |
| --------------- | --------------------------------------------- |
| `.ts` file      | Source with types                             |
| Type annotation | Optional `: string` etc. on bindings          |
| Compile         | `tsc` → `.js`                                 |
| Run             | `node` on the emitted JS (or `npx tsx` on TS) |

Start simple: one file, one `console.log`, one annotation.

## 💡 Examples [#-examples]

**Minimal typed hello:**

```ts
const greeting: string = "Hello, World!";
console.log(greeting);
```

**Compile then run:**

```shellscript
npx tsc hello.ts --strict
node hello.js
```

**Function with typed params:**

```ts
function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("Ada"));
// greet(42); // Error: Argument of type 'number' is not assignable...
```

**Run without a separate emit step (dev convenience):**

```shellscript
npx tsx hello.ts
```

## ⚠️ Pitfalls [#️-pitfalls]

* If `tsc` is “not found,” use `npx tsc` or install TypeScript locally.
* Browser pages need a build step (Vite, etc.) — you cannot drop raw `.ts` in `<script>` without tooling.
* Forgetting to recompile after edits means you run stale `.js`.
* `any` silences errors — avoid it while learning.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/typescript/getting-started)
* [why\_typescript.md](/docs/typescript/why-typescript)
* [annotating\_basics.md](/docs/typescript/annotating-basics)
* [tsconfig\_basics.md](/docs/typescript/tsconfig-basics)


# Index signatures (/docs/typescript/index-signatures)



# Index signatures [#index-signatures]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Index signatures type objects used as maps: `\{ [key: string]: V \}`. Prefer `Record<K, V>`, `Map`, or explicit keys when the key set is known. Combine carefully with declared properties — values must be assignable to the index type.

## 🔧 Core concepts [#-core-concepts]

* **String / symbol / number / template** — `[k: string]: T`, `[k: number]: T`, ``[k: `id-$\{string\}`]: T``.
* **Compatibility** — every explicit property must match the index value type.
* **`Record<K, V>`** — mapped type sugar for key unions.
* **Readonly index** — `[k: string]: readonly T[]` / `Readonly<Record&lt;…>>`.
* **`noUncheckedIndexedAccess`** — indexed reads include `| undefined`.

## 💡 Examples [#-examples]

```ts
interface Dict {
  [key: string]: number;
  length: number; // OK — number assignable to number
  // name: string; // error — string not assignable to number
}

const scores: Record<string, number> = { alice: 10, bob: 8 };
scores.carol = 12;

type IdMap = { [id: `user-${string}`]: { name: string } };
const users: IdMap = {
  "user-1": { name: "Ada" },
};

// Number index (arrays / array-like)
interface StringArray {
  [index: number]: string;
}

// Prefer known keys when possible
type Role = "admin" | "user";
const permissions: Record<Role, string[]> = {
  admin: ["read", "write", "billing"],
  user: ["read"],
};

function get(map: Record<string, number>, key: string) {
  return map[key]; // number | undefined if noUncheckedIndexedAccess
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* String index signatures weaken `keyof` to include `string`.
* Mixing required props with a broad index often forces props to `string | …`.
* Prefer `Map<K, V>` for frequent add/delete and non-string keys.
* Empty object `\{\}` is not a safe “any key” type — use `Record` or index sig.
* Numeric keys are coerced to strings at runtime — type them intentionally.

## 🔗 Related [#-related]

* [object\_types.md](/docs/typescript/object-types)
* [interfaces.md](/docs/typescript/interfaces)
* [mapped\_types.md](/docs/typescript/mapped-types)
* [keyof\_typeof.md](/docs/typescript/keyof-typeof)
* [strict\_options.md](/docs/typescript/strict-options)


# TypeScript (/docs/typescript)



# TypeScript [#typescript]

Types, generics, tooling.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

* [Examples](./examples)


# infer keyword (/docs/typescript/infer)



# infer keyword [#infer-keyword]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`infer` introduces a type variable inside a conditional type’s `extends` clause. Use it to extract return types, element types, promise payloads, and pattern pieces from other types — the foundation of many utility types.

## 🔧 Core concepts [#-core-concepts]

* **Form** — `T extends … infer U … ? True : False`.
* **Scope** — `U` is only usable in the true branch.
* **Multiple `infer`** — can appear several times; each binds independently.
* **Variance** — position (covariant/contravariant) affects inference direction.
* **Distributive** — bare type params distribute over unions in conditionals.

## 💡 Examples [#-examples]

```ts
type ReturnOf<T> = T extends (...args: any) => infer R ? R : never;
type R = ReturnOf<() => Promise<number>>; // Promise<number>

type Awaited<T> = T extends PromiseLike<infer U> ? Awaited<U> : T;
type A = Awaited<Promise<Promise<string>>>; // string

type Head<T> = T extends [infer H, ...unknown[]] ? H : never;
type H = Head<[1, 2, 3]>; // 1

type Elem<T> = T extends (infer E)[] ? E : never;
type E = Elem<string[]>; // string

type PropType<T, K extends PropertyKey> =
  T extends { [P in K]: infer V } ? V : never;

// Template + infer
type StripPrefix<S> = S extends `id-${infer Rest}` ? Rest : S;
type X = StripPrefix<"id-42">; // "42"

// Contravariant infer in parameters (simplified)
type FirstArg<T> = T extends (arg: infer A, ...rest: any) => any ? A : never;
```

```ts
// Built-ins (prefer these): ReturnType, Parameters, Awaited, InstanceType
type RT = ReturnType<() => boolean>;
type P = Parameters<(a: string, b: number) => void>; // [string, number]
```

## ⚠️ Pitfalls [#️-pitfalls]

* `infer` only works in conditional `extends` clauses, not arbitrary positions.
* Distributive conditionals: wrap as `[T] extends […]` to disable distribution.
* Over-broad `any` in patterns weakens inference.
* Recursive `infer` / conditionals can hit instantiation depth limits.
* Prefer stdlib utilities when they already exist (`ReturnType`, etc.).

## 🔗 Related [#-related]

* [conditional\_types.md](/docs/typescript/conditional-types)
* [utility\_types.md](/docs/typescript/utility-types)
* [template\_literal\_types.md](/docs/typescript/template-literal-types)
* [generic\_types.md](/docs/typescript/generic-types)
* [tuple\_types.md](/docs/typescript/tuple-types)


# Interfaces (/docs/typescript/interfaces)



# Interfaces [#interfaces]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Interfaces declare the shape of objects, classes, and callables. They support declaration merging and `extends`. Prefer `interface` for object APIs that may grow; use `type` for unions, tuples, and mapped types.

## 🔧 Core concepts [#-core-concepts]

* **Object shape** — required / optional (`?`) / `readonly` properties.
* **Extends** — `interface B extends A` (multiple bases allowed).
* **Declaration merging** — same name in a scope merges members.
* **Index / call / construct** — `[k: string]: T`, `(x: T) => R`, `new (...) => T`.
* **Implements** — classes must satisfy the interface (structural check).
* **vs `type`** — `type` can alias any type; interfaces only describe object-like forms (plus callables).

## 💡 Examples [#-examples]

```ts
interface User {
  readonly id: string;
  name: string;
  email?: string;
}

interface Admin extends User {
  permissions: string[];
}

interface StringMap {
  [key: string]: string;
}

interface Comparator {
  (a: number, b: number): number;
}

interface Box<T> {
  value: T;
}

class Point implements User {
  readonly id = "p1";
  name = "origin";
}

// Declaration merging (e.g. augmenting libs)
interface Window {
  myAppConfig?: { debug: boolean };
}

// Hybrid: callable + properties
interface Counter {
  (start: number): number;
  reset(): void;
}
```

```ts
// Prefer interface for public object contracts
interface ApiResponse<T> {
  data: T;
  error: string | null;
}

// Prefer type for unions
type Result<T> = { ok: true; value: T } | { ok: false; error: string };
```

## ⚠️ Pitfalls [#️-pitfalls]

* Excess property checks apply to object *literals*, not variables with extra fields.
* Merged interfaces must be compatible — conflicting property types error.
* `implements` does not change the class’s inferred instance type beyond checking.
* Open-ended index signatures weaken property types (`string` index → all props assignable to that type).
* Don’t use empty interfaces as “branding” without a unique field — prefer branded types.

## 🔗 Related [#-related]

* [types.md](/docs/typescript/types)
* [object\_types.md](/docs/typescript/object-types)
* [index\_signatures.md](/docs/typescript/index-signatures)
* [readonly.md](/docs/typescript/readonly)
* [class.md](/docs/typescript/class)
* [branded\_types.md](/docs/typescript/branded-types)


# keyof and typeof (/docs/typescript/keyof-typeof)



# keyof and typeof [#keyof-and-typeof]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`typeof` (in type position) captures the type of a value. `keyof T` produces a union of `T`’s public property names. Together they type-safe key access, config maps, and derived APIs without duplicating shapes.

## 🔧 Core concepts [#-core-concepts]

* **`typeof value`** — type query from a runtime value / import.
* **`keyof T`** — `string | number | symbol` keys (often string literal unions).
* **Indexed access** — `T[K]` where `K extends keyof T`.
* **`keyof typeof obj`** — keys of a concrete object / const.
* **Mapped types** — `\{ [K in keyof T]: … \}` transform properties.

## 💡 Examples [#-examples]

```ts
const user = {
  id: 1,
  name: "Ada",
  active: true,
} as const;

type User = typeof user;
type UserKey = keyof typeof user; // "id" | "name" | "active"

function getProp<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

getProp(user, "name"); // "Ada"
// getProp(user, "email"); // error

type Person = { name: string; age: number };
type PersonKeys = keyof Person; // "name" | "age"
type NameType = Person["name"]; // string

// Enum-like object
const Roles = {
  Admin: "admin",
  User: "user",
} as const;
type Role = (typeof Roles)[keyof typeof Roles]; // "admin" | "user"

// typeof on functions / classes
function createId(): string {
  return crypto.randomUUID();
}
type IdFactory = typeof createId; // () => string
```

```ts
type ReadonlyProps<T> = { readonly [K in keyof T]: T[K] };
type OptionalProps<T> = { [K in keyof T]?: T[K] };
```

## ⚠️ Pitfalls [#️-pitfalls]

* `typeof` in *value* position is JS runtime; in *type* position it’s erased.
* `keyof` on arrays includes number-like keys and `"length"` / methods depending on type.
* `keyof any` is `string | number | symbol` — avoid `any` bases.
* String index signatures make `keyof` include `string`, weakening literals.
* `typeof` imports need `import type` / value import depending on emit settings.

## 🔗 Related [#-related]

* [mapped\_types.md](/docs/typescript/mapped-types)
* [utility\_types.md](/docs/typescript/utility-types)
* [const\_assertions.md](/docs/typescript/const-assertions)
* [index\_signatures.md](/docs/typescript/index-signatures)
* [literal\_types.md](/docs/typescript/literal-types)


# Literal Types (/docs/typescript/literal-types)



# Literal Types [#literal-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Literal types represent exact values (`"left"`, `42`, `true`) rather than the general primitive. Combined with unions they model finite sets of allowed values — ideal for flags, modes, and discriminants.

## 🧩 Core concepts [#-core-concepts]

* **String / number / boolean / bigint literals** — e.g. `"admin"`, `0`, `true`, `1n`.
* **Literal unions** — `"a" | "b" | "c"` as a closed set.
* **`as const`** — widens inference to the narrowest literal / readonly tuple / readonly object.
* **Template literal types** — pattern types like `` `on$\{Capitalize<S>\}` `` (TS 4.1+).
* **Widening** — `let x = "hi"` is `string`; `const x = "hi"` is `"hi"`.

## 💡 Examples [#-examples]

```ts
type Direction = "north" | "south" | "east" | "west";

function move(dir: Direction) {
  /* ... */
}
move("north");
// move("up"); // error

const role = "admin" as const; // type: "admin"

const config = {
  mode: "dark",
  retries: 3,
} as const;
// typeof config.mode → "dark"

// Template literal types
type EventName<T extends string> = `on${Capitalize<T>}`;
type ClickHandler = EventName<"click">; // "onClick"

// Numeric literals
type Dice = 1 | 2 | 3 | 4 | 5 | 6;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutable `let` widens literals to the base primitive unless annotated.
* Object properties widen unless `as const` or an explicit type is given.
* Excessively large literal unions hurt readability and editor performance.
* Template literal types can explode combinatorially — keep patterns small.

## 🔗 Related [#-related]

* [Union types](/docs/typescript/union-types)
* [Primitive types](/docs/typescript/primitive-types)
* [Conditional types](/docs/typescript/conditional-types)
* [Mapped types](/docs/typescript/mapped-types)
* [Types](/docs/typescript/types)


# Mapped Types (/docs/typescript/mapped-types)



# Mapped Types [#mapped-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Mapped types transform each property of an existing type: `\{ [K in keyof T]: ... \}`. They underpin `Partial`, `Readonly`, `Pick`-style utilities and custom key remapping with `as` (TS 4.1+).

## 🧩 Core concepts [#-core-concepts]

* **Basic map** — iterate `keyof T` and produce a new property type.
* **Modifiers** — add/remove `readonly` and `?` with `+`/`-` prefixes.
* **Key remapping** — `as NewKey` (or `as Exclude&lt;...>`) to rename or filter keys.
* **Homomorphic maps** — preserve optional/readonly modifiers when mapping from `keyof T` directly.
* **Template keys** — remap with template literal types for prefixed/suffixed names.

## 💡 Examples [#-examples]

```ts
type ReadonlyProps<T> = {
  readonly [K in keyof T]: T[K];
};

type OptionalProps<T> = {
  [K in keyof T]?: T[K];
};

type Mutable<T> = {
  -readonly [K in keyof T]: T[K];
};

type RequiredProps<T> = {
  [K in keyof T]-?: T[K];
};

// Key remapping
type Getters<T> = {
  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
};

type User = { name: string; age: number };
type UserGetters = Getters<User>;
// { getName: () => string; getAge: () => number }

// Filter keys via remapping to never
type PublicOnly<T> = {
  [K in keyof T as K extends `_${string}` ? never : K]: T[K];
};
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mapping over a union of keys vs a union of objects behaves differently — start from a single object type.
* Remapping to `never` removes the key; accidental `never` values wipe fields.
* Index signatures and mapped types interact carefully with excess property checks.
* Prefer composing built-in utilities before writing deep custom maps.

## 🔗 Related [#-related]

* [Utility types](/docs/typescript/utility-types)
* [Conditional types](/docs/typescript/conditional-types)
* [Object types](/docs/typescript/object-types)
* [Literal types](/docs/typescript/literal-types)
* [Generic types](/docs/typescript/generic-types)


# Mixins (/docs/typescript/mixins)



# Mixins [#mixins]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Mixins compose reusable behavior into classes via functions that take a constructor and return an extended class. TypeScript models them with generic constructors, intersection instance types, and constrained type parameters (TS 5.x).

## 🔧 Core concepts [#-core-concepts]

* **Constructor type** — `type Ctor<T = \{\}> = new (...args: any[]) => T`.
* **Mixin fn** — `function Timestamped<TBase extends Ctor>(Base: TBase) \{ return class extends Base \{ … \} \}`.
* **Constraint** — `TBase extends Ctor&lt;\{ id: string \}>` when the mixin needs base members.
* **Apply** — `class X extends Timestamped(Activatable(Base)) \{\}`.
* **Alternatives** — interfaces + delegation, HOFs, or composition over deep mixin chains.

## 💡 Examples [#-examples]

```ts
type Constructor<T = {}> = new (...args: any[]) => T;

function Timestamped<TBase extends Constructor>(Base: TBase) {
  return class extends Base {
    createdAt = new Date();
    touch() {
      this.createdAt = new Date();
    }
  };
}

function Activatable<TBase extends Constructor>(Base: TBase) {
  return class extends Base {
    active = false;
    activate() {
      this.active = true;
    }
  };
}

class Entity {
  constructor(public id: string) {}
}

const User = Timestamped(Activatable(Entity));
const u = new User("1");
u.activate();
u.touch();

// Constrained mixin — base must have `serialize`
function Logged<TBase extends Constructor<{ serialize(): string }>>(Base: TBase) {
  return class extends Base {
    log() {
      console.log(this.serialize());
    }
  };
}

class Doc {
  serialize() {
    return "{}";
  }
}
const LoggedDoc = Logged(Doc);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixin constructors often use `any[]` args — real ctor param typing is limited.
* Property initialization order across mixin layers can surprise you.
* Deep mixin stacks hurt readability — prefer composition for large features.
* Declaration emit / `instanceof` across mixin classes can be awkward.
* Decorators and mixins together increase complexity — pick one style.

## 🔗 Related [#-related]

* [class.md](/docs/typescript/class)
* [generic\_types.md](/docs/typescript/generic-types)
* [decorators.md](/docs/typescript/decorators)
* [interfaces.md](/docs/typescript/interfaces)
* [this\_types.md](/docs/typescript/this-types)


# Module (/docs/typescript/module)



# Module [#module]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

TypeScript modules follow ECMAScript `import`/`export` syntax. Compiler options (`module`, `moduleResolution`, `verbatimModuleSyntax`) control emit and how imports resolve in TS 5.x projects.

## 🧩 Core concepts [#-core-concepts]

* **ES modules** — `export` / `import` / `export default` / `export * from`.
* **Type-only imports** — `import type \{ User \} from "./user"` erases at compile time.
* **`verbatimModuleSyntax`** — requires type-only imports/exports to be marked; mirrors runtime ESM.
* **Resolution** — `moduleResolution: "bundler" | "node16" | "nodenext"` (avoid legacy `"node"` in new apps).
* **`paths` / `baseUrl`** — path aliases in `tsconfig` (bundler must mirror them).
* **CommonJS interop** — `esModuleInterop` / `allowSyntheticDefaultImports` smooth CJS default imports.

## 💡 Examples [#-examples]

```ts
// math.ts
export function add(a: number, b: number) {
  return a + b;
}
export type Sum = ReturnType<typeof add>;

// app.ts
import { add } from "./math.js"; // nodenext: include .js extension in relative paths
import type { Sum } from "./math.js";

const total: Sum = add(1, 2);

// Re-exports
export { add as sum } from "./math.js";
export type { Sum as Total } from "./math.js";

// Namespace import
import * as MathUtils from "./math.js";
MathUtils.add(1, 2);

// Dynamic import
const mod = await import("./math.js");
```

`package.json` for Node ESM:

```json
{
  "type": "module"
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Under `nodenext`/`node16`, relative imports often need the `.js` extension that will exist after emit.
* Mixing `export =` (CJS) with ESM requires `esModuleInterop` and careful defaults.
* Path aliases are not rewritten by `tsc` alone — configure the bundler/runtime.
* Side-effect imports (`import "./polyfill"`) must not be type-only.

## 🔗 Related [#-related]

* [Config](/docs/typescript/config)
* [Command line](/docs/typescript/commandline)
* [Types](/docs/typescript/types)
* [Object types](/docs/typescript/object-types)
* [Class](/docs/typescript/class)


# Namespaces (/docs/typescript/namespaces)



# Namespaces [#namespaces]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Namespaces (`namespace` / legacy `module`) group types and values in a named scope. Prefer ES modules for new code. Namespaces remain useful for declaration merging with classes/functions and for typing older UMD libraries.

## 🔧 Core concepts [#-core-concepts]

* **`namespace N \{ export … \}`** — nested scopes; need `export` for outer visibility.
* **Merging** — multiple `namespace` blocks with the same name merge.
* **Class + namespace** — add static-like nested types (`class C \{\}; namespace C \{ … \}`).
* **`declare namespace`** — ambient types for globals.
* **Aliases** — `import N = require("…")` / `import N = NS.Inner` (legacy).

## 💡 Examples [#-examples]

```ts
namespace Geometry {
  export interface Point {
    x: number;
    y: number;
  }
  export function distance(a: Point, b: Point) {
    return Math.hypot(a.x - b.x, a.y - b.y);
  }
  export namespace Polar {
    export type Coord = { r: number; theta: number };
  }
}

const p: Geometry.Point = { x: 0, y: 1 };

// Merge class + namespace (factory pattern)
class Alert {
  constructor(public msg: string) {}
}
namespace Alert {
  export function success(msg: string) {
    return new Alert(`✓ ${msg}`);
  }
}
Alert.success("saved");

// Ambient
declare namespace Chrome {
  function runtimeSend(msg: unknown): void;
}
```

```ts
// Prefer ES modules today
// export interface Point { … }
// export function distance(…) { … }
```

## ⚠️ Pitfalls [#️-pitfalls]

* Namespaces don’t map cleanly to bundlers / tree-shaking like ES modules.
* `namespace` + `"module": "ESNext"` can confuse tooling — prefer files as modules.
* Forgetting `export` inside a namespace hides members.
* Avoid new namespaces in app code; keep them for `.d.ts` augmentation patterns.
* Name collisions with merging can silently expand public API surface.

## 🔗 Related [#-related]

* [module.md](/docs/typescript/module)
* [declaration\_files.md](/docs/typescript/declaration-files)
* [enums.md](/docs/typescript/enums)
* [class.md](/docs/typescript/class)
* [config.md](/docs/typescript/config)


# Object Types (/docs/typescript/object-types)



# Object Types [#object-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Object types describe property names, optionality, readonly-ness, index signatures, and call/construct signatures. Use `interface` or `type` for named shapes; anonymous object types work inline.

## 🧩 Core concepts [#-core-concepts]

* **Properties** — required by default; `?` makes optional; `readonly` prevents reassignment.
* **Index signatures** — `[key: string]: T` / `[key: number]: T` for dynamic keys.
* **Excess property checks** — apply to fresh object literals assigned to typed targets.
* **Intersection (`&`)** — combine shapes; conflicting properties become `never` when incompatible.
* **`Record<K, V>`** — mapped object with keys `K` and values `V`.
* **`object` vs `\{\}` vs `Record<string, unknown>`** — prefer explicit shapes; `object` means non-primitive.

## 💡 Examples [#-examples]

```ts
interface Product {
  readonly id: string;
  name: string;
  price?: number;
}

const p: Product = { id: "sku-1", name: "Mug" };
// p.id = "x"; // error: readonly

type Dict = { [key: string]: number };
const scores: Dict = { alice: 10, bob: 8 };

// Nested + optional chaining-friendly shapes
type Config = {
  server: { host: string; port: number };
  features?: { darkMode?: boolean };
};

// Intersection
type Timestamped = { createdAt: Date };
type Entity = Product & Timestamped;

const item: Entity = {
  id: "1",
  name: "Tea",
  createdAt: new Date(),
};

// Prefer explicit over empty object
type JsonObject = Record<string, unknown>;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Optional props may be missing *or* explicitly `undefined` depending on `exactOptionalPropertyTypes`.
* String index signatures force all named props to be assignable to the index type.
* `\{\}` accepts almost everything except `null`/`undefined` — rarely what you want.
* Methods vs function properties differ under `strictFunctionTypes` / `this` typing.

## 🔗 Related [#-related]

* [Types](/docs/typescript/types)
* [Class](/docs/typescript/class)
* [Mapped types](/docs/typescript/mapped-types)
* [Utility types](/docs/typescript/utility-types)
* [Module](/docs/typescript/module)


# Primitive Types (/docs/typescript/primitive-types)



# Primitive Types [#primitive-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Primitives are the built-in scalar types: `string`, `number`, `bigint`, `boolean`, `symbol`, `null`, and `undefined`. TypeScript mirrors JavaScript’s runtime primitives and adds compile-time distinctions (e.g. literal types, `strictNullChecks`).

## 🧩 Core concepts [#-core-concepts]

* **`string` / `number` / `boolean`** — everyday scalars; `number` covers IEEE-754 floats (no separate `int`).
* **`bigint`** — arbitrary-precision integers (`100n`); not assignable to/from `number` without conversion.
* **`symbol`** — unique keys; `unique symbol` for singleton symbol types.
* **`null` / `undefined`** — with `strictNullChecks`, not assignable to other types unless unioned.
* **`void`** — function return with no useful value (usually `undefined` at runtime).
* **Boxed wrappers** — avoid `String`, `Number`, `Boolean` object types; use primitives.

## 💡 Examples [#-examples]

```ts
const name: string = "Ada";
const age: number = 36;
const ok: boolean = true;
const huge: bigint = 10n ** 20n;
const id: symbol = Symbol("id");

function log(msg: string): void {
  console.log(msg);
}

// strictNullChecks
let maybe: string | null = null;
maybe = "ready";

// Template / string primitives
const greeting: string = `Hello, ${name}`;

// Prefer primitives over wrappers
const bad: String = new String("no"); // avoid
const good: string = "yes";
```

## ⚠️ Pitfalls [#️-pitfalls]

* `typeof null === "object"` in JS — use `=== null` checks, not `typeof`.
* `NaN` is a `number`; use `Number.isNaN` for checks.
* Without `strictNullChecks`, `null`/`undefined` sneak into almost every type.
* `void` is not the same as `undefined` in all assignability positions (callback returns).

## 🔗 Related [#-related]

* [Types](/docs/typescript/types)
* [Literal types](/docs/typescript/literal-types)
* [Union types](/docs/typescript/union-types)
* [Type guards](/docs/typescript/type-guards)
* [Object types](/docs/typescript/object-types)


# readonly (/docs/typescript/readonly)



# readonly [#readonly]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`readonly` marks properties and array/tuple positions as immutable in the type system. It does not freeze values at runtime. Use `Readonly<T>`, `readonly T[]`, `ReadonlyArray<T>`, and `as const` for immutable APIs.

## 🔧 Core concepts [#-core-concepts]

* **Property** — `readonly id: string` — cannot reassign after init.
* **Arrays** — `readonly string[]` / `ReadonlyArray<string>` — no `push` / index write.
* **Tuples** — `readonly [string, number]`.
* **Mapped** — `Readonly<T>` adds `readonly` to all props (shallow).
* **`const` params** (TS 5.0+) — `function f(xs: const string[])` infers literal/readonly.

## 💡 Examples [#-examples]

```ts
interface User {
  readonly id: string;
  name: string;
}

const u: User = { id: "1", name: "Ada" };
// u.id = "2"; // error
u.name = "Grace"; // OK

function sum(nums: readonly number[]) {
  // nums.push(1); // error
  return nums.reduce((a, b) => a + b, 0);
}

type Point = readonly [number, number];
const p: Point = [0, 0];

type ReadonlyUser = Readonly<User>; // both fields readonly

// Shallow only
type Nested = Readonly<{ meta: { flag: boolean } }>;
const n: Nested = { meta: { flag: true } };
n.meta.flag = false; // allowed — inner object not readonly

// const type parameters (TS 5.0+)
function pair<const T>(x: T) {
  return [x, x] as const;
}
const pr = pair("hi"); // readonly ["hi", "hi"]
```

## ⚠️ Pitfalls [#️-pitfalls]

* `readonly` is compile-time — `Object.assign` / casts can still mutate.
* `Readonly<T>` is shallow; use deep helpers or `as const` for nested data.
* `readonly T[]` is not assignable to `T[]` (mutable); reverse often is OK.
* Class `readonly` fields can still be mutated via aliasing if typed loosely.
* Don’t confuse with JS `Object.freeze` — combine both when needed.

## 🔗 Related [#-related]

* [const\_assertions.md](/docs/typescript/const-assertions)
* [interfaces.md](/docs/typescript/interfaces)
* [utility\_types.md](/docs/typescript/utility-types)
* [tuple\_types.md](/docs/typescript/tuple-types)
* [object\_types.md](/docs/typescript/object-types)


# satisfies operator (/docs/typescript/satisfies)



# satisfies operator [#satisfies-operator]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`satisfies T` (TS 4.9+) checks that an expression is assignable to `T` while **preserving** the expression’s more specific inferred type. Use it for config objects, route maps, and `as const` data that must match a contract without widening.

## 🔧 Core concepts [#-core-concepts]

* **Check without widen** — validates against `T`, keeps literal / tuple detail.
* **vs annotation** — `const x: T = …` widens to `T`; `satisfies` keeps narrow type.
* **vs `as T`** — assertion skips checking; `satisfies` errors on mismatch.
* **Combines with `as const`** — deep readonly + literal types + shape check.

## 💡 Examples [#-examples]

```ts
type ColorMap = Record<string, string | RGB>;
type RGB = [number, number, number];

// Annotation widens values → string | RGB everywhere
const colorsAnnotated: ColorMap = {
  red: [255, 0, 0],
  green: "#00ff00",
};

// satisfies: red stays a tuple, green stays "#00ff00"
const colors = {
  red: [255, 0, 0],
  green: "#00ff00",
} satisfies ColorMap;

colors.red.map((n) => n / 255); // OK — tuple known
colors.green.toUpperCase();     // OK — string literal methods

const palette = {
  primary: "#336699",
  secondary: "#99cc33",
} as const satisfies Record<string, `#${string}`>;

type Route = { path: string; auth: boolean };
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

type RouteKey = keyof typeof routes; // "home" | "admin"
```

```ts
// Error: missing required field
// const bad = { path: "/" } satisfies Route;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `satisfies` does not change the runtime value — validation is type-only.
* Excess property checks still apply to fresh object literals against `T`.
* Nested objects may still widen unless you also use `as const`.
* Not a substitute for runtime validation of external input.
* Older TS (\<4.9) — use annotated helpers or dual variables instead.

## 🔗 Related [#-related]

* [const\_assertions.md](/docs/typescript/const-assertions)
* [literal\_types.md](/docs/typescript/literal-types)
* [keyof\_typeof.md](/docs/typescript/keyof-typeof)
* [type\_assertions.md](/docs/typescript/type-assertions)
* [object\_types.md](/docs/typescript/object-types)


# Strict compiler options (/docs/typescript/strict-options)



# Strict compiler options [#strict-compiler-options]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`strict: true` enables a suite of soundness checks. Turn it on for new projects; migrate incrementally with per-flag toggles. TS 5.x also adds related flags (`exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `verbatimModuleSyntax`).

## 🔧 Core concepts [#-core-concepts]

| Flag (under `strict`)          | Effect                                  |
| ------------------------------ | --------------------------------------- |
| `noImplicitAny`                | Error on implied `any`                  |
| `strictNullChecks`             | `null` / `undefined` not in every type  |
| `strictFunctionTypes`          | Contravariant params for function types |
| `strictBindCallApply`          | Typed `bind` / `call` / `apply`         |
| `strictPropertyInitialization` | Class props must be set                 |
| `noImplicitThis`               | `this` must be typed                    |
| `alwaysStrict`                 | Emit `"use strict"`                     |
| `useUnknownInCatchVariables`   | `catch (e)` → `unknown`                 |

**Extra (recommended):**

* `noUncheckedIndexedAccess` — `T[K]` includes `undefined`.
* `exactOptionalPropertyTypes` — distinguish missing vs `undefined`.
* `noImplicitReturns` / `noFallthroughCasesInSwitch`.
* `verbatimModuleSyntax` — type-only imports must use `import type`.

## 💡 Examples [#-examples]

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "useUnknownInCatchVariables": true,
    "verbatimModuleSyntax": true
  }
}
```

```ts
// strictNullChecks
function len(s: string | null) {
  // return s.length; // error
  return s?.length ?? 0;
}

// strictPropertyInitialization
class User {
  name!: string; // definite assignment assertion — use sparingly
  constructor(name: string) {
    this.name = name;
  }
}

try {
  /* ... */
} catch (e) {
  if (e instanceof Error) console.error(e.message);
}

import type { UserId } from "./ids"; // verbatimModuleSyntax
```

## ⚠️ Pitfalls [#️-pitfalls]

* Enabling `strict` on a large JS codebase surfaces many errors — fix by folder / flag.
* `noUncheckedIndexedAccess` adds `| undefined` everywhere — handle explicitly.
* `exactOptionalPropertyTypes` breaks `\{ prop?: T \}` assignability with `undefined`.
* `skipLibCheck: true` hides issues in `.d.ts` (common, but masks problems).
* Don’t disable `strict` to “save time” — prefer local `as` / narrowing.

## 🔗 Related [#-related]

* [config.md](/docs/typescript/config)
* [any\_unknown\_never.md](/docs/typescript/any-unknown-never)
* [commandline.md](/docs/typescript/commandline)
* [type\_guards.md](/docs/typescript/type-guards)
* [this\_types.md](/docs/typescript/this-types)


# Template literal types (/docs/typescript/template-literal-types)



# Template literal types [#template-literal-types]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Template literal types build string types from unions and literals using `` `$\{A\}$\{B\}` `` syntax. They power event names, CSS units, route paths, and string manipulation utilities (`Uppercase`, `Lowercase`, `Capitalize`, `Uncapitalize`).

## 🔧 Core concepts [#-core-concepts]

* **Interpolation** — unions distribute: `` `on$\{"Click" | "Focus"\}` `` → `"onClick" | "onFocus"`.
* **Intrinsic helpers** — `Uppercase<S>`, `Lowercase<S>`, `Capitalize<S>`, `Uncapitalize<S>`.
* **Inference** — pattern match with `infer` inside template positions.
* **Constraints** — `extends `$\{string}\`\` / branded path patterns.
* **Mapped keys** — ``\{ [K in keyof T as `get$\{Capitalize<K & string>\}`]: … \}``.

## 💡 Examples [#-examples]

```ts
type HttpMethod = "get" | "post" | "put";
type Endpoint = `/api/${string}`;
type Route = `${HttpMethod} ${Endpoint}`;
// "get /api/..." | "post /api/..." | ...

type EventName<T extends string> = `on${Capitalize<T>}`;
type ClickHandler = EventName<"click">; // "onClick"

type PropEvent<T> = {
  [K in keyof T & string as EventName<K>]?: (value: T[K]) => void;
};

type CssUnit = `${number}px` | `${number}rem` | `${number}%`;

type ExtractId<S extends string> =
  S extends `user:${infer Id}` ? Id : never;
type U = ExtractId<"user:42">; // "42"

type DotPath = `${string}.${string}`;
function getByPath(obj: object, path: DotPath) {
  /* ... */
}
```

```ts
// Widen carefully — plain string breaks literal unions
type Bad = `${string}-id`; // effectively string-ish patterns
```

## ⚠️ Pitfalls [#️-pitfalls]

* Large distributed unions explode compile time — keep unions small.
* `` `$\{number\}` `` allows any number string pattern, not only integers.
* Template types are erased — runtime strings still need validation.
* `Capitalize` only affects the first character type-wise.
* Don’t use for complex parsing — prefer Zod / regex at runtime.

## 🔗 Related [#-related]

* [literal\_types.md](/docs/typescript/literal-types)
* [infer.md](/docs/typescript/infer)
* [conditional\_types.md](/docs/typescript/conditional-types)
* [mapped\_types.md](/docs/typescript/mapped-types)
* [satisfies.md](/docs/typescript/satisfies)


# this types (/docs/typescript/this-types)



# this types [#this-types]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

TypeScript types the `this` context for methods, functions, and classes. Use explicit `this` parameters, polymorphic `this`, and `ThisParameterType` / `OmitThisParameter` for fluent APIs and correct callbacks under `strict` / `noImplicitThis`.

## 🔧 Core concepts [#-core-concepts]

* **`this` parameter** — fake first param: `function f(this: T, …)` (erased at emit).
* **Polymorphic `this`** — return `this` for subclass-preserving builders.
* **`ThisType<T>`** — contextual `this` in object literal helpers (e.g. Vue options).
* **Extractors** — `ThisParameterType<F>`, `OmitThisParameter<F>`.
* **Arrow vs method** — arrows capture lexical `this`; methods use call-site `this`.

## 💡 Examples [#-examples]

```ts
function setName(this: { name: string }, name: string) {
  this.name = name;
}
const obj = { name: "Ada", setName };
obj.setName("Grace");
// setName("x"); // error — needs this

class Builder {
  value = 0;
  add(n: number): this {
    this.value += n;
    return this;
  }
}
class FancyBuilder extends Builder {
  label = "";
  named(s: string): this {
    this.label = s;
    return this;
  }
}
new FancyBuilder().add(1).named("x"); // FancyBuilder

type Fn = (this: HTMLElement, ev: Event) => void;
type This = ThisParameterType<Fn>; // HTMLElement
type Bare = OmitThisParameter<Fn>; // (ev: Event) => void

// Object literal with ThisType
type Bag = {
  data: { count: number };
  methods: {
    inc(this: { data: { count: number } }): void;
  };
};
```

```ts
class Widget {
  id = 1;
  // Prefer arrow for callbacks passed to DOM/timers
  onClick = () => console.log(this.id);
  // Method needs bind / arrow if detached
  log() {
    console.log(this.id);
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Detaching methods (`const f = obj.method; f()`) loses `this` — bind or use arrows.
* `this` parameters are not allowed on arrow functions.
* `noImplicitThis` errors in non-method functions without annotation.
* Polymorphic `this` doesn’t work well with some aliasing / union returns.
* Mixing `function` callbacks in React class components is a classic `this` bug.

## 🔗 Related [#-related]

* [class.md](/docs/typescript/class)
* [strict\_options.md](/docs/typescript/strict-options)
* [utility\_types.md](/docs/typescript/utility-types)
* [tsx\_react.md](/docs/typescript/tsx-react)
* [interfaces.md](/docs/typescript/interfaces)


# tsconfig Basics (/docs/typescript/tsconfig-basics)



# tsconfig Basics [#tsconfig-basics]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`tsconfig.json` tells the TypeScript compiler how to check and emit your project. One config at the repo root (or package root) is the usual starting point.

## 🔧 Core concepts [#-core-concepts]

| Option area           | Examples                     | Role                    |
| --------------------- | ---------------------------- | ----------------------- |
| `compilerOptions`     | `strict`, `target`, `module` | How to check/emit       |
| `include` / `exclude` | `["src"]`                    | Which files belong      |
| `files`               | Rare                         | Explicit file list      |
| `extends`             | `"@tsconfig/node20"`         | Share base configs      |
| Project references    | Advanced                     | Multi-package monorepos |

Turn on **`strict`: true** early — it enables a bundle of safer checks.

## 💡 Examples [#-examples]

**Beginner-friendly Node config:**

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}
```

**Create a starter config via CLI:**

```shellscript
npx tsc --init
```

**Check without emitting JS:**

```shellscript
npx tsc --noEmit
```

**Browser / bundler-oriented snippet:**

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true
  },
  "include": ["src"]
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Wrong `rootDir` / `include` pulls in `node_modules` or test junk.
* `target` too old or too new can confuse beginners — ES2020+ is a solid default.
* Mixing `"module": "CommonJS"` with ESM `import` needs care.
* Editing `tsconfig` without restarting the editor language service can show stale errors.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/typescript/getting-started)
* [hello\_world.md](/docs/typescript/hello-world)
* [why\_typescript.md](/docs/typescript/why-typescript)
* [annotating\_basics.md](/docs/typescript/annotating-basics)


# TypeScript with React (TSX) (/docs/typescript/tsx-react)



# TypeScript with React (TSX) [#typescript-with-react-tsx]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

TSX adds type-safe props, events, and refs to React. Use `React.FC` sparingly; prefer explicit `props: Props` and `ReactElement` / JSX return types. Target React 18+ types (`@types/react`) with TS 5.x.

## 🔧 Core concepts [#-core-concepts]

* **Props** — `type Props = \{ … \}`; children via `React.ReactNode`.
* **Events** — `React.ChangeEvent<HTMLInputElement>`, `MouseEvent<HTMLButtonElement>`.
* **Refs** — `useRef<HTMLDivElement>(null)`; callback refs typed similarly.
* **Hooks** — generic `useState<T>`, `useReducer`, `useRef`.
* **Components** — function components; `ComponentType<P>`, `ElementType`.
* **Assertions** — use `as` in TSX (angle brackets conflict with JSX).

## 💡 Examples [#-examples]

```tsx
import { useRef, useState, type ReactNode, type FormEvent } from "react";

type ButtonProps = {
  label: string;
  onPress: () => void;
  children?: ReactNode;
  disabled?: boolean;
};

export function Button({ label, onPress, children, disabled }: ButtonProps) {
  return (
    <button type="button" disabled={disabled} onClick={onPress}>
      {label}
      {children}
    </button>
  );
}

export function NameForm() {
  const [name, setName] = useState("");
  const inputRef = useRef<HTMLInputElement>(null);

  function onSubmit(e: FormEvent<HTMLFormElement>) {
    e.preventDefault();
    console.log(name, inputRef.current?.value);
  }

  return (
    <form onSubmit={onSubmit}>
      <input
        ref={inputRef}
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <button type="submit">Save</button>
    </form>
  );
}

type Item = { id: string; title: string };
function List({ items }: { items: Item[] }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.title}</li>
      ))}
    </ul>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `React.FC` implicitly adds `children` in older typings and weakens generics — prefer plain functions.
* Event handler types differ (`ChangeEvent` vs native `Event`).
* Don’t assert props with `as` to silence missing fields — fix the type.
* `useRef(null)` needs a generic or starts as `null` union forever.
* Library components may need `ComponentProps<typeof X>` for wrapper props.

## 🔗 Related [#-related]

* [type\_assertions.md](/docs/typescript/type-assertions)
* [generic\_types.md](/docs/typescript/generic-types)
* [zod\_integration.md](/docs/typescript/zod-integration)
* [this\_types.md](/docs/typescript/this-types)
* [interfaces.md](/docs/typescript/interfaces)


# Tuple Types (/docs/typescript/tuple-types)



# Tuple Types [#tuple-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Tuples are fixed-length (or variadic) arrays where each position has its own type. Use them for ordered pairs/triples, rest argument lists, and labeled slots for clearer errors.

## 🧩 Core concepts [#-core-concepts]

* **Fixed tuples** — `[string, number]` means length 2 with those element types.
* **Optional elements** — `[string, number?]` allows length 1 or 2.
* **Rest elements** — `[string, ...number[]]` for a head plus homogeneous tail.
* **Labeled tuples** — `[x: number, y: number]` improves hover/error messages (TS 4.0+).
* **`readonly` tuples** — `readonly [string, number]` or `as const` inference.
* **Variadic tuple types** — spread other tuples in type positions (TS 4.0+).

## 💡 Examples [#-examples]

```ts
type Pair = [string, number];
const entry: Pair = ["age", 30];

type Point = [x: number, y: number, z?: number];
const p: Point = [1, 2];

type StringBools = [string, ...boolean[]];
const flags: StringBools = ["id", true, false];

function usePair([key, value]: Pair) {
  return `${key}=${value}`;
}

// as const → readonly tuple of literals
const rgb = [255, 128, 0] as const;
// typeof rgb → readonly [255, 128, 0]

// Variadic
type Concat<A extends unknown[], B extends unknown[]> = [...A, ...B];
type Both = Concat<[1, 2], [3]>; // [1, 2, 3]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Open-ended arrays (`string[]`) are not assignable to fixed tuples without care.
* Pushing to a mutable tuple can break length assumptions at runtime — prefer `readonly`.
* Optional tuple elements must appear at the end (before rest).
* Destructuring still needs runtime checks if data comes from untyped sources.

## 🔗 Related [#-related]

* [Primitive types](/docs/typescript/primitive-types)
* [Generic types](/docs/typescript/generic-types)
* [Literal types](/docs/typescript/literal-types)
* [Utility types](/docs/typescript/utility-types)
* [Types](/docs/typescript/types)


# Type assertions (/docs/typescript/type-assertions)



# Type assertions [#type-assertions]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Assertions (`as T` / `<T>value`) tell the compiler to treat a value as a related type. They do **not** change runtime values or perform checks. Prefer narrowing, guards, and validators; assert only when you have external proof.

## 🔧 Core concepts [#-core-concepts]

* **Syntax** — `value as T` (preferred in `.tsx`); `<T>value` (not in TSX).
* **Relatedness** — assertion must be to a sufficiently overlapping type (or via `unknown`/`any`).
* **Non-null** — `x!` asserts `x` is not `null` | `undefined`.
* **Const assertion** — `as const` widens to literal/readonly (see const\_assertions).
* **Double assert** — `as unknown as T` forces any target (last resort).

## 💡 Examples [#-examples]

```ts
const el = document.getElementById("app") as HTMLDivElement | null;
el?.classList.add("ready");

// From JSON / DOM when shape is known
const cfg = JSON.parse(raw) as { port: number };

// Non-null when you’ve just checked
function len(s: string | null) {
  if (s == null) return 0;
  return s!.length; // usually unnecessary after narrowing
}

// Force through unknown (dangerous)
const n = "42" as unknown as number; // still the string "42" at runtime!

// Prefer type guard
function isPort(x: unknown): x is { port: number } {
  return (
    typeof x === "object" &&
    x !== null &&
    "port" in x &&
    typeof (x as { port: unknown }).port === "number"
  );
}
```

```tsx
// In TSX, use `as` — angle brackets conflict with JSX
const node = <div /> as React.ReactElement;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Assertions are compile-time only — invalid casts crash at runtime.
* `as T` is not a cast like C++; no conversion of values.
* Overusing `as unknown as T` hides real bugs — fix types instead.
* `!` on possibly null values is a common source of production crashes.
* Prefer Zod / schema parse for untrusted data over `as`.

## 🔗 Related [#-related]

* [any\_unknown\_never.md](/docs/typescript/any-unknown-never)
* [type\_guards.md](/docs/typescript/type-guards)
* [const\_assertions.md](/docs/typescript/const-assertions)
* [satisfies.md](/docs/typescript/satisfies)
* [zod\_integration.md](/docs/typescript/zod-integration)
* [tsx\_react.md](/docs/typescript/tsx-react)


# Type Guards (/docs/typescript/type-guards)



# Type Guards [#type-guards]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

Type guards narrow a value’s type inside a control-flow branch. Built-ins include `typeof`, `instanceof`, and `in`; custom guards use `value is T` predicates or assertion functions (`asserts`).

## 🧩 Core concepts [#-core-concepts]

* **`typeof` guards** — narrow primitives (`string`, `number`, `boolean`, `symbol`, `bigint`, `function`).
* **`instanceof`** — narrow to class instances.
* **`in` operator** — check property presence on object unions.
* **User-defined predicates** — `function isFoo(x: unknown): x is Foo`.
* **Assertion functions** — `asserts x is T` or `asserts x` throw if invalid (TS 3.7+).
* **Discriminants** — literal fields are the most reliable narrowing strategy.

## 💡 Examples [#-examples]

```ts
function padLeft(value: string | number) {
  if (typeof value === "number") {
    return " ".repeat(value);
  }
  return value;
}

class Dog {
  bark() {}
}
function speak(animal: Dog | string) {
  if (animal instanceof Dog) {
    animal.bark();
  } else {
    console.log(animal.toUpperCase());
  }
}

type Fish = { swim: () => void };
type Bird = { fly: () => void };

function move(animal: Fish | Bird) {
  if ("swim" in animal) {
    animal.swim();
  } else {
    animal.fly();
  }
}

function isString(x: unknown): x is string {
  return typeof x === "string";
}

function assertDefined<T>(x: T | null | undefined): asserts x is T {
  if (x == null) throw new Error("Expected a value");
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Predicates must be truthful — a wrong `x is T` lies to the type checker.
* `typeof null` is `"object"` — handle `null` explicitly.
* Narrowing may be lost when assigning to a mutable variable and using it later (control-flow limits).
* Arrow functions as predicates need explicit return type annotations: `(x): x is T => ...`.

## 🔗 Related [#-related]

* [Union types](/docs/typescript/union-types)
* [Types](/docs/typescript/types)
* [Primitive types](/docs/typescript/primitive-types)
* [Class](/docs/typescript/class)
* [Literal types](/docs/typescript/literal-types)


# Types (/docs/typescript/types)



# Types [#types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

TypeScript adds a static type system on top of JavaScript. Types describe the shape of values so the compiler can catch mistakes before runtime. Prefer `type` aliases and `interface` for reusable shapes; use annotations where inference is unclear.

## 🧩 Core concepts [#-core-concepts]

* **Type annotations** — `let x: number = 1` declares the expected type.
* **Type inference** — TS often infers types from initializers; annotate public APIs.
* **`type` vs `interface`** — both name object shapes; `interface` supports declaration merging; `type` can express unions, intersections, and mapped forms.
* **Structural typing** — compatibility is by shape, not by nominal class name.
* **`any` / `unknown` / `never`** — escape hatch, safe top type, and bottom type respectively.
* **Type assertions** — `as T` or `<T>value` tell the compiler; they do not rewrite runtime values.

## 💡 Examples [#-examples]

```ts
// Annotation + inference
const count: number = 42;
const message = "hello"; // inferred as string

// type alias
type UserId = string;
type Point = { x: number; y: number };

// interface
interface User {
  id: UserId;
  name: string;
}

// Structural compatibility
const p: Point = { x: 1, y: 2 };
const alsoPoint = { x: 0, y: 0, z: 9 };
const ok: Point = alsoPoint; // extra props allowed when assigning from a variable

// unknown vs any
function parse(json: string): unknown {
  return JSON.parse(json);
}
const data = parse("{}");
if (typeof data === "object" && data !== null && "id" in data) {
  // narrowed
}

// Assertion (prefer narrowing when possible)
const el = document.querySelector("#app") as HTMLDivElement | null;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Overusing `any` disables checking; prefer `unknown` and narrow.
* Assertions lie to the compiler — invalid casts still compile.
* Fresh object literals are excess-property checked; variables are not.
* `interface` merging can surprise you across files; keep declarations intentional.

## 🔗 Related [#-related]

* [Primitive types](/docs/typescript/primitive-types)
* [Object types](/docs/typescript/object-types)
* [Union types](/docs/typescript/union-types)
* [Generic types](/docs/typescript/generic-types)
* [Utility types](/docs/typescript/utility-types)
* [Type guards](/docs/typescript/type-guards)


# Union Types (/docs/typescript/union-types)



# Union Types [#union-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

A union type (`A | B`) means a value may be one of several types. Narrow with control flow, discriminants, or type guards before using members unique to one branch.

## 🧩 Core concepts [#-core-concepts]

* **Union (`|`)** — value is one of the constituents.
* **Intersection (`&`)** — value must satisfy all constituents (often used with object shapes).
* **Discriminated unions** — shared literal field (e.g. `kind`) enables exhaustive narrowing.
* **Union of objects** — only common properties are accessible without narrowing.
* **`never` in switches** — use for exhaustiveness checks when all cases handled.

## 💡 Examples [#-examples]

```ts
type Id = string | number;

function printId(id: Id) {
  if (typeof id === "string") {
    console.log(id.toUpperCase());
  } else {
    console.log(id.toFixed(0));
  }
}

// Discriminated union
type Success = { ok: true; data: string };
type Failure = { ok: false; error: string };
type Result = Success | Failure;

function handle(r: Result) {
  if (r.ok) {
    console.log(r.data);
  } else {
    console.error(r.error);
  }
}

// Exhaustiveness
type Shape =
  | { kind: "circle"; radius: number }
  | { kind: "square"; size: number };

function area(s: Shape): number {
  switch (s.kind) {
    case "circle":
      return Math.PI * s.radius ** 2;
    case "square":
      return s.size ** 2;
    default: {
      const _exhaustive: never = s;
      return _exhaustive;
    }
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Accessing a property that exists on only one union member is an error until narrowed.
* `string | null` still needs null checks under `strictNullChecks`.
* Over-wide unions (`string | number | boolean | object`) defeat the purpose — prefer discriminants.
* Union of function types is contravariant in parameters under strict function checking.

## 🔗 Related [#-related]

* [Types](/docs/typescript/types)
* [Literal types](/docs/typescript/literal-types)
* [Type guards](/docs/typescript/type-guards)
* [Conditional types](/docs/typescript/conditional-types)
* [Primitive types](/docs/typescript/primitive-types)


# Utility Types (/docs/typescript/utility-types)



# Utility Types [#utility-types]

**TypeScript · Reference cheat sheet**

***

## 📖 Overview [#-overview]

TypeScript ships built-in utility types for common transformations: making props optional/required, picking keys, extracting from unions, and more. They are implemented with mapped and conditional types under the hood (TS 5.x).

## 🧩 Core concepts [#-core-concepts]

* **Object helpers** — `Partial`, `Required`, `Readonly`, `Pick`, `Omit`, `Record`.
* **Union helpers** — `Exclude`, `Extract`, `NonNullable`.
* **Function helpers** — `Parameters`, `ReturnType`, `ConstructorParameters`, `InstanceType`.
* **Async** — `Awaited<T>` unwraps nested Promises.
* **String helpers** — `Uppercase`, `Lowercase`, `Capitalize`, `Uncapitalize`.
* **`ThisType` / `NoInfer`** — advanced inference control (`NoInfer` in TS 5.4+).

## 💡 Examples [#-examples]

```ts
interface User {
  id: string;
  name: string;
  email?: string;
}

type UserPatch = Partial<User>;
type UserRequiredEmail = Required<Pick<User, "email">> & Omit<User, "email">;
type UserPreview = Pick<User, "id" | "name">;
type UserWithoutEmail = Omit<User, "email">;

type Role = "admin" | "user" | "guest";
type Staff = Exclude<Role, "guest">; // "admin" | "user"
type AdminOnly = Extract<Role, "admin">;

type Maybe = string | null | undefined;
type Sure = NonNullable<Maybe>; // string

function createUser(name: string, age: number) {
  return { name, age };
}
type Args = Parameters<typeof createUser>; // [string, number]
type Out = ReturnType<typeof createUser>;

type Payload = Awaited<Promise<Promise<number>>>; // number

type Event = `on${Capitalize<"click">}`; // "onClick"
```

## ⚠️ Pitfalls [#️-pitfalls]

* `Omit` is not type-safe for renaming/refactoring keys the way a constrained `Pick` can be.
* `Partial` makes every key optional, including nested objects (shallow only).
* `Record<string, T>` allows any string key — prefer string literal unions when the set is closed.
* Utility types operate at compile time only — they emit no runtime code.

## 🔗 Related [#-related]

* [Mapped types](/docs/typescript/mapped-types)
* [Conditional types](/docs/typescript/conditional-types)
* [Object types](/docs/typescript/object-types)
* [Generic types](/docs/typescript/generic-types)
* [Types](/docs/typescript/types)


# Why TypeScript? (/docs/typescript/why-typescript)



# Why TypeScript? [#why-typescript]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

TypeScript exists to make JavaScript safer and clearer at scale. Static types document intent, unlock editor autocomplete, and catch whole classes of bugs before users see them.

## 🔧 Core concepts [#-core-concepts]

| Benefit          | What you gain                                        |
| ---------------- | ---------------------------------------------------- |
| Early errors     | Typos, wrong args, null misuse flagged in the editor |
| Better tooling   | Jump-to-definition, rename, accurate autocomplete    |
| Living docs      | Signatures explain APIs without outdated comments    |
| Refactors        | Change a type and follow red squiggles               |
| Gradual adoption | Rename `.js` → `.ts` and tighten types over time     |

TypeScript is not a different runtime language — it compiles to JS that engines already understand.

## 💡 Examples [#-examples]

**Bug caught at compile time:**

```ts
function add(a: number, b: number): number {
  return a + b;
}

// add("2", "3"); // Error: string not assignable to number
console.log(add(2, 3));
```

**Autocomplete-friendly objects:**

```ts
type User = { id: number; name: string };

const user: User = { id: 1, name: "Sam" };
console.log(user.name.toUpperCase());
```

**Optional fields and null safety (with strict settings):**

```ts
type Profile = { bio?: string };

function bioLength(p: Profile): number {
  return p.bio?.length ?? 0;
}

console.log(bioLength({}));
console.log(bioLength({ bio: "hi" }));
```

**Same idea in plain JS (fails later):**

```js
function add(a, b) {
  return a + b;
}
console.log(add("2", "3")); // "23" — silent logic bug
```

## ⚠️ Pitfalls [#️-pitfalls]

* Types are not runtime validation — still validate untrusted input (APIs, forms).
* Over-complex types can obscure simple code; keep beginner types plain.
* `as` assertions and `any` defeat the purpose when overused.
* Build setup cost is real; for a one-line snippet, plain JS may be enough.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/typescript/getting-started)
* [hello\_world.md](/docs/typescript/hello-world)
* [annotating\_basics.md](/docs/typescript/annotating-basics)
* [tsconfig\_basics.md](/docs/typescript/tsconfig-basics)


# Zod integration (/docs/typescript/zod-integration)



# Zod integration [#zod-integration]

*TypeScript · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Zod defines runtime schemas that infer TypeScript types (`z.infer<typeof schema>`). Use it at trust boundaries (HTTP, forms, env, JSON) instead of assertions. Patterns below target Zod 3.x with TS 5.x.

## 🔧 Core concepts [#-core-concepts]

* **Single source** — schema → `z.infer` type; avoid duplicating interfaces.
* **Parse vs safeParse** — throw vs `\{ success, data | error \}`.
* **Compose** — `object`, `union`, `discriminatedUnion`, `array`, `optional`, `nullable`.
* **Transforms** — `.transform` / `.pipe` for coercion and branding.
* **Shared** — export schemas from a `packages/shared` or `lib/schemas` module.

## 💡 Examples [#-examples]

```ts
import { z } from "zod";

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(["admin", "user"]),
  age: z.number().int().positive().optional(),
});
type User = z.infer<typeof UserSchema>;

const raw: unknown = JSON.parse(body);
const user = UserSchema.parse(raw); // User or throw

const result = UserSchema.safeParse(raw);
if (!result.success) {
  console.error(result.error.flatten());
} else {
  console.log(result.data.email);
}

const ResultSchema = z.discriminatedUnion("ok", [
  z.object({ ok: z.literal(true), value: z.string() }),
  z.object({ ok: z.literal(false), error: z.string() }),
]);

const UserIdSchema = z.string().min(1).brand<"UserId">();
type UserId = z.infer<typeof UserIdSchema>;

// Env
const EnvSchema = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]),
  PORT: z.coerce.number().default(9000),
});
const env = EnvSchema.parse(process.env);
```

```ts
// Express / fetch handler
async function handler(req: Request) {
  const json: unknown = await req.json();
  const input = UserSchema.parse(json);
  return Response.json(input);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don’t `as User` after partial checks — parse the full schema.
* `.optional()` vs `.nullable()` vs `.nullish()` — pick intentionally.
* `z.coerce` can hide bad input (e.g. `Number("") === 0`).
* Huge nested schemas slow cold start — split and lazy-load if needed.
* Keep server and client schemas in sync via a shared package.

## 🔗 Related [#-related]

* [branded\_types.md](/docs/typescript/branded-types)
* [any\_unknown\_never.md](/docs/typescript/any-unknown-never)
* [discriminated\_unions.md](/docs/typescript/discriminated-unions)
* [type\_assertions.md](/docs/typescript/type-assertions)
* [tsx\_react.md](/docs/typescript/tsx-react)


# Arrays & Tuples (/docs/zod/arrays-tuples)



# Arrays & Tuples [#arrays--tuples]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Zod models homogeneous arrays with `z.array` and fixed-length positional collections with `z.tuple`. Useful for lists of DTOs and CSV-like rows.

## 🔧 Core concepts [#-core-concepts]

| Schema                      | Meaning                  |
| --------------------------- | ------------------------ |
| `z.array(T)`                | Array of T               |
| `z.tuple([A, B])`           | Fixed positions          |
| `.nonempty()`               | At least one element     |
| `.min` / `.max` / `.length` | Size constraints         |
| `z.record`                  | String-key map of values |
| `z.map` / `z.set`           | ES Map / Set             |

## 💡 Examples [#-examples]

**Array of objects:**

```ts
const Tag = z.string().min(1);
const Post = z.object({
  title: z.string(),
  tags: z.array(Tag).max(10),
});
```

**Tuple:**

```ts
const Pair = z.tuple([z.string(), z.number()]);
Pair.parse(["age", 30]);
```

**Nonempty:**

```ts
z.array(z.number()).nonempty().parse([1]);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Tuples reject extra elements unless you configure rest (version-dependent).
* Sparse arrays and holes are unusual — prefer dense JSON arrays.
* Very large arrays: validation is O(n); validate early at the boundary.

## 🔗 Related [#-related]

* [objects.md](/docs/zod/objects)
* [primitives.md](/docs/zod/primitives)
* [refinements.md](/docs/zod/refinements)
* [safeparse.md](/docs/zod/safeparse)


# Coerce (/docs/zod/coerce)



# Coerce [#coerce]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`z.coerce` converts inputs before validation — useful for query strings, form fields, and env vars where everything arrives as strings.

## 🔧 Core concepts [#-core-concepts]

| Schema               | Coerces via                   |
| -------------------- | ----------------------------- |
| `z.coerce.string()`  | `String(value)`               |
| `z.coerce.number()`  | `Number(value)`               |
| `z.coerce.boolean()` | Boolean conversion (careful!) |
| `z.coerce.bigint()`  | BigInt                        |
| `z.coerce.date()`    | `new Date(value)`             |

| Good fit         | Risky fit                              |
| ---------------- | -------------------------------------- |
| `"42"` → number  | Boolean: `"false"` is truthy in JS     |
| ISO date strings | Invalid dates becoming Invalid Date    |
| Env PORT         | Objects coerced to `"[object Object]"` |

## 💡 Examples [#-examples]

**Query params:**

```ts
const Query = z.object({
  page: z.coerce.number().int().min(1).default(1),
  q: z.string().optional(),
});
Query.parse({ page: "2", q: "zod" });
```

**Env:**

```ts
const Env = z.object({
  PORT: z.coerce.number().default(9000),
  DEBUG: z.coerce.boolean().default(false),
});
```

**Dates:**

```ts
z.coerce.date().parse("2026-07-11T00:00:00.000Z");
```

## ⚠️ Pitfalls [#️-pitfalls]

* `z.coerce.boolean()` treats any non-empty string as `true` — including `"false"`. Prefer `z.enum(['true','false'])` + transform for forms.
* Coercion can hide bugs by accepting unexpected types.
* Prefer explicit transforms when conversion rules are domain-specific.

## 🔗 Related [#-related]

* [primitives.md](/docs/zod/primitives)
* [transforms.md](/docs/zod/transforms)
* [safeparse.md](/docs/zod/safeparse)
* [getting\_started.md](/docs/zod/getting-started)


# Getting Started with Zod (/docs/zod/getting-started)



# Getting Started with Zod [#getting-started-with-zod]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Zod is a TypeScript-first schema library for parsing and validating data at runtime while inferring static types. Common for API payloads, env config, and forms.

## 🔧 Core concepts [#-core-concepts]

| Idea       | Meaning                                  |
| ---------- | ---------------------------------------- |
| Schema     | Declarative description of a value shape |
| Parse      | Validate + return typed data (or throw)  |
| Safe parse | Validate without throwing                |
| Infer      | Extract TS type from a schema            |
| Transform  | Map input → output during parse          |

**Install:**

```shellscript
npm install zod
```

| Entry   | Import                               |
| ------- | ------------------------------------ |
| Zod 3   | `import \{ z \} from "zod"`          |
| Schemas | `z.string()`, `z.object(\{...\})`, … |

## 💡 Examples [#-examples]

**First schema:**

```ts
import { z } from "zod";

const User = z.object({
  email: z.string().email(),
  age: z.number().int().positive(),
});

const user = User.parse({ email: "a@b.co", age: 30 });
```

**Type inference:**

```ts
type User = z.infer<typeof User>;
```

**Env-style parse:**

```ts
const Env = z.object({ PORT: z.coerce.number().default(9000) });
const env = Env.parse(process.env);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `parse` throws `ZodError` — use `safeParse` at trust boundaries if you prefer Result-style control flow.
* Zod validates runtime values; it does not replace compile-time TS checking alone.
* Major version APIs differ (Zod 3 vs 4) — match docs to your installed version.

## 🔗 Related [#-related]

* [primitives.md](/docs/zod/primitives)
* [objects.md](/docs/zod/objects)
* [safeparse.md](/docs/zod/safeparse)
* [infer\_types.md](/docs/zod/infer-types)
* [glossary.md](/docs/zod/glossary)


# Glossary (/docs/zod/glossary)



# Glossary [#glossary]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Alphabetical glossary of Zod schema, parsing, and type-inference terms.

## 🔧 Core concepts [#-core-concepts]

| Term                | Definition                                                |
| ------------------- | --------------------------------------------------------- |
| Coercion            | Converting input types before validation (`z.coerce`).    |
| Discriminated union | `z.discriminatedUnion` selecting a schema by a tag field. |
| Effect              | Pipeline step such as transform, refine, or preprocess.   |
| Infer               | Extracting a TypeScript type from a schema (`z.infer`).   |
| Issue               | Single validation problem inside a `ZodError`.            |
| Literal             | Schema matching one exact value.                          |
| Parse               | Validate and return data, throwing on failure.            |
| Pipe                | Connect schema output into another schema.                |
| Refine              | Custom predicate adding constraints beyond built-ins.     |
| Safe parse          | Non-throwing parse returning a result object.             |
| Schema              | Runtime validator object created by Zod builders.         |
| Strip               | Default object behavior removing unknown keys.            |
| Transform           | Map a validated value to a new output.                    |
| Tuple               | Fixed-length array schema with per-index types.           |
| ZodError            | Error class aggregating validation issues.                |

## 💡 Examples [#-examples]

**Discriminated union sketch:**

```ts
const Event = z.discriminatedUnion("type", [
  z.object({ type: z.literal("click"), x: z.number() }),
  z.object({ type: z.literal("nav"), href: z.string() }),
]);
```

**Result narrowing:**

```ts
const r = Event.safeParse(input);
if (r.success) console.log(r.data.type);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Glossary terms may differ slightly across Zod major versions.
* `z.any()` disables safety — prefer `z.unknown()` then narrow.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/zod/getting-started)
* [safeparse.md](/docs/zod/safeparse)
* [infer\_types.md](/docs/zod/infer-types)
* [README.md](/docs/zod)


# Zod (/docs/zod)



# Zod [#zod]

Schema validation & TypeScript inference.

Browse the sidebar for every cheat sheet in this section.

## Sections [#sections]

*All notes are listed in the sidebar.*


# Infer Types (/docs/zod/infer-types)



# Infer Types [#infer-types]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Zod schemas are a single source of truth: validate at runtime and derive TypeScript types with `z.infer`, `z.input`, and `z.output`.

## 🔧 Core concepts [#-core-concepts]

| Helper               | Yields                     |
| -------------------- | -------------------------- |
| `z.infer<typeof S>`  | Output type (usual choice) |
| `z.input<typeof S>`  | Type before transforms     |
| `z.output<typeof S>` | Type after transforms      |
| `z.infer` on objects | Nested object types        |

| Pattern           | Benefit                               |
| ----------------- | ------------------------------------- |
| Schema-first      | No drift between types and validators |
| Shared DTO module | API + client agree                    |
| Env schema        | Typed `process.env`                   |

## 💡 Examples [#-examples]

**Basic infer:**

```ts
const User = z.object({
  id: z.string(),
  email: z.string().email(),
});
type User = z.infer<typeof User>;
// { id: string; email: string }
```

**Input vs output:**

```ts
const S = z.string().transform((s) => s.length);
type In = z.input<typeof S>;   // string
type Out = z.output<typeof S>; // number
```

**Function boundary:**

```ts
function save(user: z.infer<typeof User>) {
  /* ... */
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don't hand-write a duplicate `interface` that can drift — infer from the schema.
* Optional fields (`?`) vs `| undefined` differ slightly in TS excess property checks.
* Circular types need `z.lazy` — plain infer won't recurse infinitely by itself.

## 🔗 Related [#-related]

* [transforms.md](/docs/zod/transforms)
* [objects.md](/docs/zod/objects)
* [safeparse.md](/docs/zod/safeparse)
* [getting\_started.md](/docs/zod/getting-started)


# Objects (/docs/zod/objects)



# Objects [#objects]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`z.object` defines keyed shapes with required/optional fields, nested objects, and helpers for picking, omitting, extending, and strictness.

## 🔧 Core concepts [#-core-concepts]

| API                 | Effect                      |
| ------------------- | --------------------------- |
| `z.object(\{...\})` | Define shape                |
| `.partial()`        | All keys optional           |
| `.required()`       | All keys required           |
| `.pick` / `.omit`   | Subset keys                 |
| `.extend`           | Add fields                  |
| `.merge`            | Combine objects             |
| `.strict()`         | Reject unknown keys         |
| `.passthrough()`    | Keep unknown keys           |
| `.strip()`          | Drop unknown keys (default) |

## 💡 Examples [#-examples]

**Nested object:**

```ts
const Address = z.object({
  city: z.string(),
  zip: z.string().min(3),
});

const Person = z.object({
  name: z.string(),
  address: Address,
});
```

**Strict vs strip:**

```ts
z.object({ id: z.string() }).strict().parse({ id: "1", extra: true });
// throws — unknown key
```

**Pick / extend:**

```ts
const User = z.object({
  id: z.string(),
  email: z.string().email(),
  password: z.string(),
});
const PublicUser = User.omit({ password: true });
const Admin = User.extend({ role: z.literal("admin") });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Default object schemas strip unknown keys — fine for DTOs, surprising for proxies.
* `.optional()` on a field allows missing key; distinguish from `.nullable()`.
* Deep partials need care — `.partial()` is shallow unless you build recursively.

## 🔗 Related [#-related]

* [primitives.md](/docs/zod/primitives)
* [arrays\_tuples.md](/docs/zod/arrays-tuples)
* [infer\_types.md](/docs/zod/infer-types)
* [transforms.md](/docs/zod/transforms)


# Primitives (/docs/zod/primitives)



# Primitives [#primitives]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Zod provides schemas for JS primitives and common string/number refinements (email, URL, int, min/max, etc.).

## 🔧 Core concepts [#-core-concepts]

| Schema                       | Validates                                       |
| ---------------------------- | ----------------------------------------------- |
| `z.string()`                 | string                                          |
| `z.number()`                 | number (not `NaN` by default in typical setups) |
| `z.boolean()`                | boolean                                         |
| `z.bigint()`                 | bigint                                          |
| `z.date()`                   | Date instance                                   |
| `z.undefined()` / `z.null()` | exact undefined / null                          |
| `z.any()` / `z.unknown()`    | anything / unknown                              |
| `z.literal(x)`               | exact value                                     |
| `z.enum([...])`              | string union                                    |

| String helpers              | Example           |
| --------------------------- | ----------------- |
| `.min` / `.max` / `.length` | Length bounds     |
| `.email` / `.url` / `.uuid` | Formats           |
| `.regex`                    | Custom pattern    |
| `.trim` / `.toLowerCase`    | String transforms |

## 💡 Examples [#-examples]

**Strings and numbers:**

```ts
const Password = z.string().min(8).max(72);
const Port = z.number().int().min(1).max(65535);
```

**Literals and enums:**

```ts
const Role = z.enum(["admin", "user"]);
const Ok = z.literal("ok");
```

**Optional / nullable:**

```ts
z.string().optional(); // string | undefined
z.string().nullable(); // string | null
z.string().nullish();  // string | null | undefined
```

## ⚠️ Pitfalls [#️-pitfalls]

* JSON has no `Date` — use `z.coerce.date()` or ISO strings + transform.
* Empty string is still a string; use `.min(1)` or `.trim().min(1)` for required text.
* `z.number()` rejects numeric strings unless you coerce.

## 🔗 Related [#-related]

* [objects.md](/docs/zod/objects)
* [coerce.md](/docs/zod/coerce)
* [refinements.md](/docs/zod/refinements)
* [getting\_started.md](/docs/zod/getting-started)


# Refinements (/docs/zod/refinements)



# Refinements [#refinements]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Refinements add custom predicates and cross-field checks that built-in validators cannot express — passwords match, date ranges, XOR fields, etc.

## 🔧 Core concepts [#-core-concepts]

| API                    | Role                               |
| ---------------------- | ---------------------------------- |
| `.refine(fn, message)` | Extra boolean check                |
| `.superRefine`         | Multiple issues via `ctx.addIssue` |
| `.refine` on objects   | Cross-field validation             |
| Second arg             | Custom error message / path        |

| Pattern              | Example use                      |
| -------------------- | -------------------------------- |
| Confirm password     | `password === confirm`           |
| Conditional required | If `type==='card'` require `cvv` |
| Business rules       | Unique SKU format                |

## 💡 Examples [#-examples]

**Simple refine:**

```ts
const Even = z.number().refine((n) => n % 2 === 0, {
  message: "Expected even number",
});
```

**Cross-field:**

```ts
const Signup = z
  .object({
    password: z.string().min(8),
    confirm: z.string(),
  })
  .refine((d) => d.password === d.confirm, {
    message: "Passwords must match",
    path: ["confirm"],
  });
```

**superRefine:**

```ts
z.string().superRefine((val, ctx) => {
  if (val.includes(" ")) {
    ctx.addIssue({ code: "custom", message: "No spaces" });
  }
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Refinements run after base parsing — coercions/transforms order matters.
* Forgetting `path` makes UI error mapping harder.
* Heavy async refinements (DB uniqueness) belong in an app layer; keep schemas fast when possible (Zod supports async refine carefully).

## 🔗 Related [#-related]

* [transforms.md](/docs/zod/transforms)
* [objects.md](/docs/zod/objects)
* [safeparse.md](/docs/zod/safeparse)
* [primitives.md](/docs/zod/primitives)


# safeParse (/docs/zod/safeparse)



# safeParse [#safeparse]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`safeParse` returns a discriminated result instead of throwing. Prefer it at HTTP/form boundaries where invalid input is expected.

## 🔧 Core concepts [#-core-concepts]

| API                                    | Behavior                                        |
| -------------------------------------- | ----------------------------------------------- |
| `schema.parse(data)`                   | Returns value or throws `ZodError`              |
| `schema.safeParse(data)`               | `\{ success, data \}` or `\{ success, error \}` |
| `schema.parseAsync` / `safeParseAsync` | Async refinements/transforms                    |
| `error.flatten()`                      | Field errors for forms                          |
| `error.format()`                       | Nested error tree                               |

## 💡 Examples [#-examples]

**Branch on success:**

```ts
const result = User.safeParse(payload);
if (!result.success) {
  console.error(result.error.flatten());
  return;
}
console.log(result.data.email);
```

**HTTP handler style:**

```ts
const parsed = Body.safeParse(await req.json());
if (!parsed.success) {
  return Response.json(parsed.error.flatten(), { status: 400 });
}
```

**flatten for UI:**

```ts
const { fieldErrors, formErrors } = error.flatten();
```

## ⚠️ Pitfalls [#️-pitfalls]

* After `success === true`, TypeScript narrows `data` — don't access `data` on the failure branch.
* Swallowing `error` without logging loses diagnostics.
* `parse` in a hot request path without try/catch can crash the process if unhandled.

## 🔗 Related [#-related]

* [getting\_started.md](/docs/zod/getting-started)
* [refinements.md](/docs/zod/refinements)
* [objects.md](/docs/zod/objects)
* [infer\_types.md](/docs/zod/infer-types)


# Transforms (/docs/zod/transforms)



# Transforms [#transforms]

*Zod · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Transforms change values during parsing: trim strings, normalize casing, map DTOs, or convert types. Output types can differ from input types.

## 🔧 Core concepts [#-core-concepts]

| API              | Role                                       |
| ---------------- | ------------------------------------------ |
| `.transform(fn)` | Map value after validation                 |
| `.pipe(schema)`  | Feed output into another schema            |
| `z.preprocess`   | Run before validation                      |
| Input vs output  | `z.input<typeof S>` / `z.output<typeof S>` |

| Use         | Example                |
| ----------- | ---------------------- |
| Normalize   | trim + lowercase email |
| Defaults    | fill missing fields    |
| DTO mapping | rename keys            |

## 💡 Examples [#-examples]

**Trim email:**

```ts
const Email = z
  .string()
  .trim()
  .toLowerCase()
  .email();
```

**Transform shape:**

```ts
const Raw = z.object({ user_id: z.string() }).transform((d) => ({
  userId: d.user_id,
}));
```

**Pipe:**

```ts
const IsoDate = z.string().datetime().pipe(z.coerce.date());
```

## ⚠️ Pitfalls [#️-pitfalls]

* Transforms run on success path — failed refinements skip later transforms.
* Inferred `z.infer` is the *output* type; use `z.input` when typing forms that submit raw values.
* Overusing preprocess can hide invalid data instead of failing loudly.

## 🔗 Related [#-related]

* [coerce.md](/docs/zod/coerce)
* [infer\_types.md](/docs/zod/infer-types)
* [refinements.md](/docs/zod/refinements)
* [objects.md](/docs/zod/objects)


# Backup Script (/docs/bash/examples/backup-script)



# Backup Script [#backup-script]

*Bash · Example / how-to*

***

## 📋 Overview [#-overview]

Create a dated tar.gz backup of a directory with `set -euo pipefail`, logging, and retention cleanup.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                |
| ------------------- | ------------------- |
| `set -euo pipefail` | Fail fast on errors |
| `tar`               | Archive + compress  |
| Date stamp          | Unique backup names |
| Retention           | Delete old archives |

## 💡 Examples [#-examples]

**backup\_script.sh:**

```shellscript
#!/usr/bin/env bash
set -euo pipefail

SRC_DIR="${1:-./data}"
DEST_DIR="${2:-./backups}"
KEEP="${KEEP:-7}"
STAMP="$(date +%Y%m%d-%H%M%S)"
NAME="backup-${STAMP}.tar.gz"

mkdir -p "$DEST_DIR"

if [[ ! -d "$SRC_DIR" ]]; then
  echo "error: source not found: $SRC_DIR" >&2
  exit 1
fi

echo "backing up $SRC_DIR -> $DEST_DIR/$NAME"
tar -czf "$DEST_DIR/$NAME" -C "$(dirname "$SRC_DIR")" "$(basename "$SRC_DIR")"

# keep newest $KEEP archives
mapfile -t OLD < <(ls -1t "$DEST_DIR"/backup-*.tar.gz 2>/dev/null | tail -n +"$((KEEP + 1))" || true)
if ((${#OLD[@]})); then
  printf 'removing %s\n' "${OLD[@]}"
  rm -f -- "${OLD[@]}"
fi

echo "done"
```

**Usage:**

```shellscript
chmod +x backup_script.sh
./backup_script.sh ./project ./backups
KEEP=14 ./backup_script.sh ./project ./backups
```

## ⚠️ Pitfalls [#️-pitfalls]

* Unquoted variables break on spaces — always quote `"$SRC_DIR"`.
* `tar` paths: `-C` + basename avoids nesting absolute paths oddly.
* Test restores periodically; a backup you cannot extract is useless.

## 🔗 Related [#-related]

* [Find and replace](/docs/bash/examples/find-and-replace)
* [Healthcheck loop](/docs/bash/examples/healthcheck-loop)


# Find and Replace (/docs/bash/examples/find-and-replace)



# Find and Replace [#find-and-replace]

*Bash · Example / how-to*

***

## 📋 Overview [#-overview]

Recursively find text files and apply a safe in-place string replacement with `find` + `sed` (or `perl`).

## 🔧 Core concepts [#-core-concepts]

| Piece    | Role                         |
| -------- | ---------------------------- |
| `find`   | Select files by name/type    |
| `sed -i` | In-place edit                |
| Excludes | Skip `.git` / `node_modules` |
| Dry run  | Preview before write         |

## 💡 Examples [#-examples]

**find\_and\_replace.sh:**

```shellscript
#!/usr/bin/env bash
set -euo pipefail

ROOT="${1:-.}"
OLD="${2:?usage: $0 ROOT OLD NEW}"
NEW="${3:?usage: $0 ROOT OLD NEW}"

echo "dry run matches:"
grep -RIn --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=.venv \
  --include='*.md' --include='*.py' --include='*.ts' --include='*.tsx' \
  -- "$OLD" "$ROOT" || true

read -r -p "Apply replacement? [y/N] " ans
[[ "${ans:-}" =~ ^[Yy]$ ]] || exit 0

# portable-ish in-place with perl
find "$ROOT" \
  \( -path '*/.git/*' -o -path '*/node_modules/*' -o -path '*/.venv/*' \) -prune -o \
  -type f \( -name '*.md' -o -name '*.py' -o -name '*.ts' -o -name '*.tsx' \) \
  -print0 |
  xargs -0 perl -pi -e "s/\Q$OLD\E/$NEW/g"

echo "done"
```

**One-off GNU sed (Linux):**

```shellscript
find . -name '*.md' -print0 | xargs -0 sed -i 's/foo/bar/g'
```

## ⚠️ Pitfalls [#️-pitfalls]

* macOS `sed -i` needs `sed -i ''` — prefer `perl -pi` for portability.
* Binary files can be corrupted — limit by extension.
* Always dry-run with `grep` before mass edits; commit first.

## 🔗 Related [#-related]

* [Backup script](/docs/bash/examples/backup-script)
* [Healthcheck loop](/docs/bash/examples/healthcheck-loop)


# Healthcheck Loop (/docs/bash/examples/healthcheck-loop)



# Healthcheck Loop [#healthcheck-loop]

*Bash · Example / how-to*

***

## 📋 Overview [#-overview]

Poll an HTTP health endpoint until it succeeds or a timeout expires — useful for deploy wait scripts.

## 🔧 Core concepts [#-core-concepts]

| Piece        | Role                       |
| ------------ | -------------------------- |
| Loop + sleep | Retry with backoff gap     |
| `curl -fsS`  | Fail on HTTP errors        |
| Deadline     | Absolute timeout           |
| Exit codes   | `0` healthy, `1` timed out |

## 💡 Examples [#-examples]

**healthcheck\_loop.sh:**

```shellscript
#!/usr/bin/env bash
set -euo pipefail

URL="${1:-http://127.0.0.1:8000/health}"
TIMEOUT_SEC="${TIMEOUT_SEC:-60}"
INTERVAL_SEC="${INTERVAL_SEC:-2}"
START="$(date +%s)"

echo "waiting for $URL (timeout ${TIMEOUT_SEC}s)"

while true; do
  if curl -fsS --max-time 5 "$URL" >/dev/null; then
    echo "healthy"
    exit 0
  fi

  NOW="$(date +%s)"
  ELAPSED="$((NOW - START))"
  if ((ELAPSED >= TIMEOUT_SEC)); then
    echo "error: timed out after ${TIMEOUT_SEC}s" >&2
    exit 1
  fi

  echo "not ready (${ELAPSED}s)…"
  sleep "$INTERVAL_SEC"
done
```

**Usage:**

```shellscript
chmod +x healthcheck_loop.sh
./healthcheck_loop.sh http://127.0.0.1:9000/healthz
TIMEOUT_SEC=120 INTERVAL_SEC=3 ./healthcheck_loop.sh https://example.com/health
```

## ⚠️ Pitfalls [#️-pitfalls]

* `curl` without `-f` treats 500 as success — always use `-f` or check status.
* Infinite loops without a deadline hang CI jobs.
* DNS/TLS failures need clear stderr; avoid swallowing curl errors silently.

## 🔗 Related [#-related]

* [Backup script](/docs/bash/examples/backup-script)
* [Find and replace](/docs/bash/examples/find-and-replace)


# Examples (/docs/bash/examples)



# Examples [#examples]

Bash notes in **Examples**.


# Card Layout (/docs/css/examples/card-layout)



# Card Layout [#card-layout]

*CSS · Example / how-to*

***

## 📋 Overview [#-overview]

Lay out a responsive card grid with CSS Grid, consistent gaps, and a flexible media + body structure inside each card.

## 🔧 Core concepts [#-core-concepts]

| Piece                   | Role                     |
| ----------------------- | ------------------------ |
| `grid-template-columns` | Auto-fit columns         |
| `minmax`                | Fluid card width         |
| Flex column card        | Media on top, body grows |
| Aspect ratio            | Stable image boxes       |

## 💡 Examples [#-examples]

```html
<section class="card-grid">
  <article class="card">
    <img class="card-media" src="/img/a.jpg" alt="" />
    <div class="card-body">
      <h2>Title A</h2>
      <p>Short description.</p>
      <a href="/a">Read more</a>
    </div>
  </article>
  <article class="card">
    <img class="card-media" src="/img/b.jpg" alt="" />
    <div class="card-body">
      <h2>Title B</h2>
      <p>Short description.</p>
      <a href="/b">Read more</a>
    </div>
  </article>
</section>
```

```css
.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
  gap: 1.25rem;
}

.card {
  display: flex;
  flex-direction: column;
  border: 1px solid #ddd;
  border-radius: 0.5rem;
  overflow: hidden;
  background: #fff;
}

.card-media {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
  display: block;
}

.card-body {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
  padding: 1rem;
  flex: 1;
}

.card-body a {
  margin-top: auto;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Fixed pixel columns break on small phones — prefer `minmax` + `auto-fit`.
* Missing `alt` on meaningful images hurts accessibility; decorative images use `alt=""`.
* Uneven text lengths: push CTAs with `margin-top: auto` in a flex column.

## 🔗 Related [#-related]

* [Responsive nav](/docs/css/examples/responsive-nav)
* [Dark mode toggle](/docs/css/examples/dark-mode-toggle)


# Dark Mode Toggle (/docs/css/examples/dark-mode-toggle)



# Dark Mode Toggle [#dark-mode-toggle]

*CSS · Example / how-to*

***

## 📋 Overview [#-overview]

Implement light/dark themes with CSS custom properties, `prefers-color-scheme`, and a class or `data-theme` override.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                  |
| ---------------------- | --------------------- |
| Custom properties      | Tokenize colors       |
| `prefers-color-scheme` | System default        |
| `data-theme`           | Manual override       |
| Cascade                | Override beats system |

## 💡 Examples [#-examples]

```html
<html lang="en" data-theme="system">
  <body>
    <button type="button" id="theme-toggle">Toggle theme</button>
  </body>
</html>
```

```css
:root,
[data-theme="light"] {
  --bg: #f7f7f5;
  --fg: #1a1a1a;
  --accent: #0b6e4f;
}

[data-theme="dark"] {
  --bg: #121212;
  --fg: #f0f0f0;
  --accent: #5eead4;
}

@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --bg: #121212;
    --fg: #f0f0f0;
    --accent: #5eead4;
  }
}

body {
  background: var(--bg);
  color: var(--fg);
}

a {
  color: var(--accent);
}
```

```javascript
const root = document.documentElement;
const btn = document.querySelector("#theme-toggle");

btn.addEventListener("click", () => {
  const next = root.dataset.theme === "dark" ? "light" : "dark";
  root.dataset.theme = next;
  localStorage.setItem("theme", next);
});

const saved = localStorage.getItem("theme");
if (saved === "light" || saved === "dark") {
  root.dataset.theme = saved;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hard-coded colors bypass tokens and break dark mode.
* Flash of wrong theme: set `data-theme` in a tiny inline script in `<head>`.
* Contrast: check WCAG for accent on both backgrounds.

## 🔗 Related [#-related]

* [Responsive nav](/docs/css/examples/responsive-nav)
* [Card layout](/docs/css/examples/card-layout)


# Examples (/docs/css/examples)



# Examples [#examples]

CSS notes in **Examples**.


# Responsive Nav (/docs/css/examples/responsive-nav)



# Responsive Nav [#responsive-nav]

*CSS · Example / how-to*

***

## 📋 Overview [#-overview]

Build a horizontal nav that collapses behind a details/summary (or checkbox) toggle on small screens using only CSS.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                   |
| ---------------------- | ---------------------- |
| Flexbox                | Align brand + links    |
| Media queries          | Switch layout by width |
| `:checked` / `details` | Toggle without JS      |
| `gap` / `wrap`         | Spacing without hacks  |

## 💡 Examples [#-examples]

**responsive\_nav.html + CSS:**

```html
<header class="site-header">
  <a class="brand" href="/">Docs</a>
  <details class="nav">
    <summary class="nav-toggle">Menu</summary>
    <ul class="nav-list">
      <li><a href="/guides">Guides</a></li>
      <li><a href="/api">API</a></li>
      <li><a href="/blog">Blog</a></li>
    </ul>
  </details>
</header>
```

```css
.site-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 1rem;
  padding: 0.75rem 1rem;
}

.nav-list {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
  list-style: none;
  margin: 0.5rem 0 0;
  padding: 0;
}

.nav-toggle {
  cursor: pointer;
  list-style: none;
}

.nav-toggle::-webkit-details-marker {
  display: none;
}

@media (min-width: 720px) {
  .nav {
    display: contents;
  }

  .nav-toggle {
    display: none;
  }

  .nav-list {
    flex-direction: row;
    margin: 0;
    align-items: center;
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `display: contents` removes the details box from layout — test focus order.
* Tiny tap targets on mobile — give summary enough padding.
* Fixed headers need `scroll-padding-top` so in-page anchors are not hidden.

## 🔗 Related [#-related]

* [Card layout](/docs/css/examples/card-layout)
* [Dark mode toggle](/docs/css/examples/dark-mode-toggle)


# CRUD CBV (/docs/django/examples/crud-cbv)



# CRUD CBV [#crud-cbv]

*Django · Example / how-to*

***

## 📋 Overview [#-overview]

Implement list/create/update/delete for a model with Django class-based views and a simple URL conf.

## 🔧 Core concepts [#-core-concepts]

| Piece                       | Role                 |
| --------------------------- | -------------------- |
| `ListView` / `CreateView`   | Read + create        |
| `UpdateView` / `DeleteView` | Edit + remove        |
| `get_success_url`           | Post-action redirect |
| `LoginRequiredMixin`        | Gate mutations       |

## 💡 Examples [#-examples]

**models.py:**

```python
from django.db import models

class Note(models.Model):
    title = models.CharField(max_length=200)
    body = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self) -> str:
        return self.title
```

**views.py:**

```python
from django.contrib.auth.mixins import LoginRequiredMixin
from django.urls import reverse_lazy
from django.views.generic import (
    CreateView,
    DeleteView,
    ListView,
    UpdateView,
)

from .models import Note


class NoteListView(ListView):
    model = Note
    paginate_by = 20


class NoteCreateView(LoginRequiredMixin, CreateView):
    model = Note
    fields = ["title", "body"]
    success_url = reverse_lazy("note-list")


class NoteUpdateView(LoginRequiredMixin, UpdateView):
    model = Note
    fields = ["title", "body"]
    success_url = reverse_lazy("note-list")


class NoteDeleteView(LoginRequiredMixin, DeleteView):
    model = Note
    success_url = reverse_lazy("note-list")
```

**urls.py:**

```python
from django.urls import path
from .views import NoteCreateView, NoteDeleteView, NoteListView, NoteUpdateView

urlpatterns = [
    path("", NoteListView.as_view(), name="note-list"),
    path("new/", NoteCreateView.as_view(), name="note-create"),
    path("<int:pk>/edit/", NoteUpdateView.as_view(), name="note-update"),
    path("<int:pk>/delete/", NoteDeleteView.as_view(), name="note-delete"),
]
```

## ⚠️ Pitfalls [#️-pitfalls]

* CBVs need templates named `<app>/<model>_form.html` etc. unless you set `template_name`.
* Always authorize object ownership for multi-user data — mixin alone is not enough.
* Prefer `reverse_lazy` at class level; `reverse` needs a request/ready URLconf.

## 🔗 Related [#-related]

* [DRF list create](/docs/django/examples/drf-list-create)
* [Custom user snippet](/docs/django/examples/custom-user-snippet)


# Custom User Snippet (/docs/django/examples/custom-user-snippet)



# Custom User Snippet [#custom-user-snippet]

*Django · Example / how-to*

***

## 📋 Overview [#-overview]

Swap in a custom user model early with email as the username field using `AbstractUser` and `AUTH_USER_MODEL`.

## 🔧 Core concepts [#-core-concepts]

| Piece             | Role                            |
| ----------------- | ------------------------------- |
| `AbstractUser`    | Keep Django auth features       |
| `USERNAME_FIELD`  | Login identifier                |
| `AUTH_USER_MODEL` | Project-wide reference          |
| Migrations        | Must exist before first migrate |

## 💡 Examples [#-examples]

**accounts/models.py:**

```python
from django.contrib.auth.models import AbstractUser
from django.db import models


class User(AbstractUser):
    email = models.EmailField(unique=True)

    USERNAME_FIELD = "email"
    REQUIRED_FIELDS = ["username"]

    def __str__(self) -> str:
        return self.email
```

**settings.py:**

```python
INSTALLED_APPS = [
    # ...
    "accounts",
    "django.contrib.auth",
    # ...
]

AUTH_USER_MODEL = "accounts.User"
```

**Foreign keys elsewhere:**

```python
from django.conf import settings
from django.db import models

class Profile(models.Model):
    user = models.OneToOneField(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="profile",
    )
    bio = models.TextField(blank=True)
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing `AUTH_USER_MODEL` after migrations is painful — set it on day one.
* Always reference `settings.AUTH_USER_MODEL`, never hard-code `auth.User`.
* Admin / forms may need a custom user admin when fields change.

## 🔗 Related [#-related]

* [CRUD CBV](/docs/django/examples/crud-cbv)
* [DRF list create](/docs/django/examples/drf-list-create)


# DRF List Create (/docs/django/examples/drf-list-create)



# DRF List Create [#drf-list-create]

*Django · Example / how-to*

***

## 📋 Overview [#-overview]

Expose a JSON list + create endpoint with Django REST Framework `ListCreateAPIView` and a ModelSerializer.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                  |
| ------------------- | --------------------- |
| `ModelSerializer`   | Map model ↔ JSON      |
| `ListCreateAPIView` | GET list, POST create |
| Permissions         | Who can write         |
| Pagination          | Bound list size       |

## 💡 Examples [#-examples]

**serializers.py:**

```python
from rest_framework import serializers
from .models import Note


class NoteSerializer(serializers.ModelSerializer):
    class Meta:
        model = Note
        fields = ["id", "title", "body", "created_at"]
        read_only_fields = ["id", "created_at"]
```

**views.py:**

```python
from rest_framework import generics, permissions
from .models import Note
from .serializers import NoteSerializer


class NoteListCreateView(generics.ListCreateAPIView):
    queryset = Note.objects.all().order_by("-created_at")
    serializer_class = NoteSerializer
    permission_classes = [permissions.IsAuthenticatedOrReadOnly]

    def perform_create(self, serializer):
        serializer.save()
```

**urls.py:**

```python
from django.urls import path
from .views import NoteListCreateView

urlpatterns = [
    path("api/notes/", NoteListCreateView.as_view(), name="api-note-list"),
]
```

**curl:**

```shellscript
curl -s http://127.0.0.1:8000/api/notes/
curl -s -X POST http://127.0.0.1:8000/api/notes/ \
  -H "Content-Type: application/json" \
  -H "Authorization: Token <token>" \
  -d '{"title":"Hello","body":"World"}'
```

## ⚠️ Pitfalls [#️-pitfalls]

* Default permissions may be wide open — set project defaults in settings.
* N+1 queries: use `select_related` / `prefetch_related` on the queryset.
* Validation errors return 400 with field keys — match your client expectations.

## 🔗 Related [#-related]

* [CRUD CBV](/docs/django/examples/crud-cbv)
* [Custom user snippet](/docs/django/examples/custom-user-snippet)


# Examples (/docs/django/examples)



# Examples [#examples]

Django notes in **Examples**.


# Fix Last Commit (/docs/git/examples/fix-last-commit)



# Fix Last Commit [#fix-last-commit]

*Git · Example / how-to*

***

## 📋 Overview [#-overview]

Amend the most recent commit to fix the message or add forgotten files — only when it is safe (not pushed, or you own the branch).

## 🔧 Core concepts [#-core-concepts]

| Piece                | Role                             |
| -------------------- | -------------------------------- |
| `git commit --amend` | Rewrite HEAD commit              |
| Staged changes       | Fold into last commit            |
| Message edit         | `--amend -m` or editor           |
| Safety               | Avoid amending published history |

## 💡 Examples [#-examples]

**Fix message only:**

```shellscript
git commit --amend -m "fix: correct typo in changelog"
```

**Add forgotten files:**

```shellscript
git add path/to/missed_file.ts
git commit --amend --no-edit
```

**Check before amending:**

```shellscript
git status
git log -1 --format='%an %ae %s'
git status -sb   # look for "ahead" vs tracking remote
```

## ⚠️ Pitfalls [#️-pitfalls]

* Never amend commits already pushed to a shared branch unless the team agrees (needs force-push).
* `--no-edit` keeps the old message; use an editor/`-m` when the message should change.
* Hooks may rewrite files on amend — review `git status` after.

## 🔗 Related [#-related]

* [Undo local changes](/docs/git/examples/undo-local-changes)
* [Sync fork branch](/docs/git/examples/sync-fork-branch)


# Examples (/docs/git/examples)



# Examples [#examples]

Git notes in **Examples**.


# Sync Fork Branch (/docs/git/examples/sync-fork-branch)



# Sync Fork Branch [#sync-fork-branch]

*Git · Example / how-to*

***

## 📋 Overview [#-overview]

Update your fork’s branch from the upstream repository using remotes, fetch, and rebase or merge.

## 🔧 Core concepts [#-core-concepts]

| Piece              | Role                   |
| ------------------ | ---------------------- |
| `upstream` remote  | Original repo          |
| `origin` remote    | Your fork              |
| `fetch`            | Download without merge |
| `rebase` / `merge` | Integrate upstream     |

## 💡 Examples [#-examples]

**One-time remote setup:**

```shellscript
git remote add upstream https://github.com/ORG/REPO.git
git remote -v
```

**Sync main, then update feature branch:**

```shellscript
git fetch upstream
git checkout main
git merge --ff-only upstream/main
git push origin main

git checkout feature/my-work
git rebase main
# or: git merge main
git push origin feature/my-work
```

**If rebase rewrote commits already on the fork:**

```shellscript
git push --force-with-lease origin feature/my-work
```

## ⚠️ Pitfalls [#️-pitfalls]

* Prefer `--force-with-lease` over `--force` to avoid clobbering others’ pushes.
* Confusing `origin` and `upstream` pushes updates to the wrong place.
* Long-lived forks: sync often to reduce conflict size.

## 🔗 Related [#-related]

* [Fix last commit](/docs/git/examples/fix-last-commit)
* [Undo local changes](/docs/git/examples/undo-local-changes)


# Undo Local Changes (/docs/git/examples/undo-local-changes)



# Undo Local Changes [#undo-local-changes]

*Git · Example / how-to*

***

## 📋 Overview [#-overview]

Discard or unstage local work safely: restore files, unstage the index, or reset unpushed commits without rewriting remote history.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                             |
| --------------- | -------------------------------- |
| `restore`       | Discard working tree / unstage   |
| `reset --soft`  | Move HEAD, keep changes staged   |
| `reset --mixed` | Move HEAD, keep changes unstaged |
| `clean`         | Remove untracked files           |

## 💡 Examples [#-examples]

**Unstage a file (keep edits):**

```shellscript
git restore --staged path/to/file.ts
```

**Discard unstaged edits to a file:**

```shellscript
git restore path/to/file.ts
```

**Undo last local commit, keep changes staged:**

```shellscript
git reset --soft HEAD~1
```

**Undo last local commit, keep changes unstaged:**

```shellscript
git reset HEAD~1
```

**Remove untracked files (dry run first):**

```shellscript
git clean -nd
git clean -fd
```

## ⚠️ Pitfalls [#️-pitfalls]

* `git restore` / `clean -fd` permanently deletes uncommitted work — dry-run first.
* `reset --hard` is destructive; avoid unless you truly want a clean tree.
* Do not reset commits that exist on the remote shared branch.

## 🔗 Related [#-related]

* [Fix last commit](/docs/git/examples/fix-last-commit)
* [Sync fork branch](/docs/git/examples/sync-fork-branch)


# Examples (/docs/github-actions/examples)



# Examples [#examples]

GitHub Actions notes in **Examples**.


# Node CI (/docs/github-actions/examples/node-ci)



# Node CI [#node-ci]

*Github Actions · Example / how-to*

***

## 📋 Overview [#-overview]

Run install, lint, typecheck, and tests for a Node project on pull requests with caching and a fixed Node version.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role         |
| ---------------------- | ------------ |
| `actions/checkout`     | Fetch repo   |
| `actions/setup-node`   | Node + cache |
| Job steps              | Lint → test  |
| `pull_request` trigger | Gate merges  |

## 💡 Examples [#-examples]

**.github/workflows/node\_ci.yml:**

```yaml
name: Node CI

on:
  pull_request:
  push:
    branches: [main]

concurrency:
  group: node-ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: site
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
          cache-dependency-path: site/package-lock.json

      - name: Install
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Typecheck
        run: npm run typecheck

      - name: Test
        run: npm test --if-present
```

## ⚠️ Pitfalls [#️-pitfalls]

* `npm install` in CI drifts locks — prefer `npm ci`.
* Wrong `cache-dependency-path` disables caching silently.
* Fail fast: put cheap lint/typecheck before heavy e2e.

## 🔗 Related [#-related]

* [Path filters](/docs/github-actions/examples/path-filters)


# Path Filters (/docs/github-actions/examples/path-filters)



# Path Filters [#path-filters]

*Github Actions · Example / how-to*

***

## 📋 Overview [#-overview]

Skip or select jobs based on which paths changed using `paths` / `paths-ignore` filters (and optional path-filter actions).

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                            |
| --------------- | ------------------------------- |
| `on.push.paths` | Only run when paths match       |
| `paths-ignore`  | Skip doc-only changes           |
| Multiple jobs   | Different filters per area      |
| Fork PRs        | Filters still apply to PR files |

## 💡 Examples [#-examples]

**.github/workflows/path\_filters.yml:**

```yaml
name: Path filters

on:
  pull_request:
    paths-ignore:
      - "**/*.md"
      - "docs/**"
  push:
    branches: [main]
    paths:
      - "site/**"
      - ".github/workflows/path_filters.yml"

jobs:
  site:
    if: github.event_name == 'pull_request' || contains(join(github.event.commits.*.modified, ','), 'site/') || true
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: npm
          cache-dependency-path: site/package-lock.json
      - run: npm ci
        working-directory: site
      - run: npm run lint
        working-directory: site

  python:
    runs-on: ubuntu-latest
    # Alternative: dorny/paths-filter for multi-job path detection
    steps:
      - uses: actions/checkout@v4
      - uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            python:
              - 'Python/**'
              - '**/requirements*.txt'
      - if: steps.filter.outputs.python == 'true'
        run: echo "Run Python checks here"
```

**Simple docs skip:**

```yaml
on:
  pull_request:
    paths-ignore:
      - "**/*.md"
```

## ⚠️ Pitfalls [#️-pitfalls]

* Workflow file changes should be included in `paths` or the workflow never updates.
* `paths-ignore` on the whole workflow skips all jobs — use job-level filters for mixed repos.
* Required checks that never run can block merges — configure branch protection carefully.

## 🔗 Related [#-related]

* [Node CI](/docs/github-actions/examples/node-ci)


# Accessible Form (/docs/html/examples/accessible-form)



# Accessible Form [#accessible-form]

*Html · Example / how-to*

***

## 📋 Overview [#-overview]

Build a contact form with proper labels, error association, required fields, and keyboard-friendly controls.

## 🔧 Core concepts [#-core-concepts]

| Piece              | Role                |
| ------------------ | ------------------- |
| `<label for>`      | Name the control    |
| `aria-describedby` | Link help / errors  |
| `aria-invalid`     | Mark failed fields  |
| Native types       | `email`, `required` |

## 💡 Examples [#-examples]

```html
<form action="/contact" method="post" novalidate>
  <fieldset>
    <legend>Contact us</legend>

    <div>
      <label for="email">Email</label>
      <input
        id="email"
        name="email"
        type="email"
        autocomplete="email"
        required
        aria-describedby="email-hint email-error"
        aria-invalid="true"
      />
      <p id="email-hint">We never share your email.</p>
      <p id="email-error" role="alert">Enter a valid email address.</p>
    </div>

    <div>
      <label for="message">Message</label>
      <textarea
        id="message"
        name="message"
        rows="5"
        required
        aria-describedby="message-hint"
      ></textarea>
      <p id="message-hint">Max 1000 characters.</p>
    </div>

    <div>
      <input id="consent" name="consent" type="checkbox" required />
      <label for="consent">I agree to the privacy policy</label>
    </div>
  </fieldset>

  <button type="submit">Send</button>
</form>
```

**Clear error state when valid (JS sketch):**

```javascript
input.setAttribute("aria-invalid", "false");
error.textContent = "";
```

## ⚠️ Pitfalls [#️-pitfalls]

* Placeholder is not a label — screen readers and recall suffer.
* Only using color for errors fails contrast / color-blind users.
* `novalidate` disables native checks — pair with your own accessible errors.

## 🔗 Related [#-related]

* [Semantic article](/docs/html/examples/semantic-article)


# Examples (/docs/html/examples)



# Examples [#examples]

HTML notes in **Examples**.


# Semantic Article (/docs/html/examples/semantic-article)



# Semantic Article [#semantic-article]

*Html · Example / how-to*

***

## 📋 Overview [#-overview]

Mark up a blog-style article with landmark regions, heading hierarchy, and meaningful time/author metadata.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                      |
| ---------------------- | ------------------------- |
| `<main>` / `<article>` | Primary content landmarks |
| Heading levels         | Outline without skipping  |
| `<time datetime>`      | Machine-readable dates    |
| `<nav>` / `<aside>`    | Related, not main story   |

## 💡 Examples [#-examples]

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Shipping notes for June</title>
  </head>
  <body>
    <header>
      <p><a href="/">Home</a></p>
    </header>

    <main>
      <article>
        <header>
          <h1>Shipping notes for June</h1>
          <p>
            By <span rel="author">Ada Lovelace</span> ·
            <time datetime="2026-06-10">June 10, 2026</time>
          </p>
        </header>

        <p>We tightened release checklists and cut rollback time.</p>

        <h2>What changed</h2>
        <ul>
          <li>Faster preview deploys</li>
          <li>Clearer error budgets</li>
        </ul>

        <h2>Next steps</h2>
        <p>Adopt the checklist on every service.</p>

        <footer>
          <p>Tags: <a href="/tags/ops">ops</a>, <a href="/tags/release">release</a></p>
        </footer>
      </article>

      <aside>
        <h2>Related</h2>
        <nav aria-label="Related articles">
          <ul>
            <li><a href="/posts/may">May notes</a></li>
          </ul>
        </nav>
      </aside>
    </main>
  </body>
</html>
```

## ⚠️ Pitfalls [#️-pitfalls]

* Multiple `<h1>` per page is usually confusing — one primary title is clearer.
* Div soup loses landmarks for screen-reader users.
* Decorative images need `alt=""`; informative images need real alt text.

## 🔗 Related [#-related]

* [Accessible form](/docs/html/examples/accessible-form)


# Async User Event (/docs/jest/examples/async-user-event)



# Async User Event [#async-user-event]

*Jest · Example / how-to*

***

## 📋 Overview [#-overview]

Test interactive React (or DOM) flows with `@testing-library/user-event` and async `findBy*` queries.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                   |
| ------------------- | ---------------------- |
| `userEvent.setup()` | Realistic interactions |
| `await user.click`  | Async event API        |
| `findBy*`           | Wait for UI updates    |
| `await` assertions  | Flush promises         |

## 💡 Examples [#-examples]

**AsyncSearch.tsx (component under test):**

```tsx
import { useState } from "react";

export function AsyncSearch({ onSearch }: { onSearch: (q: string) => Promise<string[]> }) {
  const [items, setItems] = useState<string[]>([]);
  const [status, setStatus] = useState("idle");

  async function handleClick() {
    setStatus("loading");
    const next = await onSearch("ada");
    setItems(next);
    setStatus("done");
  }

  return (
    <div>
      <button type="button" onClick={handleClick}>
        Search
      </button>
      <p>{status}</p>
      <ul>
        {items.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
    </div>
  );
}
```

**AsyncSearch.test.tsx:**

```tsx
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { AsyncSearch } from "./AsyncSearch";

test("loads results after click", async () => {
  const user = userEvent.setup();
  const onSearch = jest.fn().mockResolvedValue(["Ada Lovelace"]);

  render(<AsyncSearch onSearch={onSearch} />);
  await user.click(screen.getByRole("button", { name: "Search" }));

  expect(await screen.findByText("Ada Lovelace")).toBeInTheDocument();
  expect(screen.getByText("done")).toBeInTheDocument();
  expect(onSearch).toHaveBeenCalledWith("ada");
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Prefer `userEvent` over `fireEvent` for closer-to-real typing/clicking.
* Use `findBy*` for async UI; `getBy*` throws immediately if missing.
* Always `await` user-event methods in the v14+ async API.

## 🔗 Related [#-related]

* [Mock module](/docs/jest/examples/mock-module)


# Examples (/docs/jest/examples)



# Examples [#examples]

Jest notes in **Examples**.


# Mock Module (/docs/jest/examples/mock-module)



# Mock Module [#mock-module]

*Jest · Example / how-to*

***

## 📋 Overview [#-overview]

Replace a module dependency with `jest.mock` so unit tests control return values and assert call shapes.

## 🔧 Core concepts [#-core-concepts]

| Piece        | Role                    |
| ------------ | ----------------------- |
| `jest.mock`  | Hoisted module stub     |
| `jest.fn`    | Spy / stub function     |
| `mocked()`   | Typed mock helpers (TS) |
| `beforeEach` | Reset call history      |

## 💡 Examples [#-examples]

**api.ts:**

```typescript
export async function fetchUser(id: string) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error("fail");
  return res.json();
}
```

**userService.ts:**

```typescript
import { fetchUser } from "./api";

export async function getUserLabel(id: string) {
  const user = await fetchUser(id);
  return `${user.name} <${user.email}>`;
}
```

**userService.test.ts:**

```typescript
import { getUserLabel } from "./userService";
import { fetchUser } from "./api";

jest.mock("./api");

const fetchUserMock = fetchUser as jest.MockedFunction<typeof fetchUser>;

beforeEach(() => {
  fetchUserMock.mockReset();
});

test("formats label from API user", async () => {
  fetchUserMock.mockResolvedValue({
    name: "Ada",
    email: "ada@example.com",
  });

  await expect(getUserLabel("1")).resolves.toBe("Ada <ada@example.com>");
  expect(fetchUserMock).toHaveBeenCalledWith("1");
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* `jest.mock` is hoisted — keep factories self-contained.
* Forget `mockReset` / `clearAllMocks` and tests leak state.
* Mock the module boundary your unit owns; avoid mocking huge frameworks casually.

## 🔗 Related [#-related]

* [Async user event](/docs/jest/examples/async-user-event)


# Array Pipeline (/docs/javascript/examples/array-pipeline)



# Array Pipeline [#array-pipeline]

*Javascript · Example / how-to*

***

## 📋 Overview [#-overview]

Transform collections with a readable `filter` → `map` → `reduce` pipeline instead of nested loops.

## 🔧 Core concepts [#-core-concepts]

| Piece        | Role                          |
| ------------ | ----------------------------- |
| `filter`     | Keep matching items           |
| `map`        | Project shape                 |
| `reduce`     | Aggregate to one value        |
| Immutability | Prefer new arrays over mutate |

## 💡 Examples [#-examples]

**array\_pipeline.js:**

```javascript
const orders = [
  { id: 1, status: "paid", total: 42.5, tags: ["books"] },
  { id: 2, status: "pending", total: 10, tags: ["toys"] },
  { id: 3, status: "paid", total: 19.99, tags: ["books", "sale"] },
  { id: 4, status: "paid", total: 5, tags: ["sale"] },
];

const paidBookRevenue = orders
  .filter((o) => o.status === "paid")
  .filter((o) => o.tags.includes("books"))
  .map((o) => ({ id: o.id, total: o.total }))
  .reduce((sum, o) => sum + o.total, 0);

console.log(paidBookRevenue); // 62.49

const byTag = orders
  .flatMap((o) => o.tags.map((tag) => [tag, o.total]))
  .reduce((acc, [tag, total]) => {
    acc[tag] = (acc[tag] ?? 0) + total;
    return acc;
  }, {});

console.log(byTag);
```

**Readable helpers:**

```javascript
const isPaid = (o) => o.status === "paid";
const hasTag = (tag) => (o) => o.tags.includes(tag);

const total = orders.filter(isPaid).filter(hasTag("sale")).reduce((s, o) => s + o.total, 0);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Chaining many `filter`/`map` passes over large arrays — combine when hot.
* `reduce` without an initial value fails on empty arrays for objects.
* Mutating inside `map` surprises callers — return new objects.

## 🔗 Related [#-related]

* [Fetch JSON](/docs/javascript/examples/fetch-json)
* [Debounce input](/docs/javascript/examples/debounce-input)


# Debounce Input (/docs/javascript/examples/debounce-input)



# Debounce Input [#debounce-input]

*Javascript · Example / how-to*

***

## 📋 Overview [#-overview]

Debounce a search input so filtering runs after the user pauses typing, not on every keystroke.

## 🔧 Core concepts [#-core-concepts]

| Piece                         | Role                     |
| ----------------------------- | ------------------------ |
| Debounce                      | Delay until quiet period |
| `setTimeout` / `clearTimeout` | Schedule and cancel      |
| `input` event                 | Live typing              |
| Closure                       | Hold timer id            |

## 💡 Examples [#-examples]

**debounce\_input.js:**

```javascript
function debounce(fn, waitMs = 300) {
  let timer;
  return function debounced(...args) {
    clearTimeout(timer);
    timer = setTimeout(() => fn.apply(this, args), waitMs);
  };
}

const input = document.querySelector("#search");
const status = document.querySelector("#status");
const items = ["Apple", "Apricot", "Banana", "Blueberry", "Cherry"];

function filterItems(query) {
  const q = query.trim().toLowerCase();
  const matches = items.filter((item) => item.toLowerCase().includes(q));
  status.textContent = q
    ? `Matches: ${matches.join(", ") || "(none)"}`
    : "Type to filter…";
}

input.addEventListener(
  "input",
  debounce((event) => filterItems(event.target.value), 300),
);
```

**Cancel on blur (optional):**

```javascript
function debounceCancelable(fn, waitMs = 300) {
  let timer;
  const wrapped = (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), waitMs);
  };
  wrapped.cancel = () => clearTimeout(timer);
  return wrapped;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Debounce delays the last call; throttle limits rate — pick the right one.
* Always `clearTimeout` before scheduling again or timers stack.
* In SPAs, cancel pending timers on unmount to avoid setState-after-unmount.

## 🔗 Related [#-related]

* [DOM todo](/docs/javascript/examples/dom-todo)
* [LocalStorage prefs](/docs/javascript/examples/localstorage-prefs)


# DOM Todo (/docs/javascript/examples/dom-todo)



# DOM Todo [#dom-todo]

*Javascript · Example / how-to*

***

## 📋 Overview [#-overview]

Build a small todo list with vanilla DOM: add items, toggle done, and remove rows without a framework.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                   |
| --------------- | ---------------------- |
| `querySelector` | Find form / list roots |
| `createElement` | Build list items       |
| Event listeners | Submit, click, change  |
| `dataset`       | Store item ids         |

## 💡 Examples [#-examples]

**index.html (snippet):**

```html
<form id="todo-form">
  <input id="todo-input" name="title" required placeholder="New task" />
  <button type="submit">Add</button>
</form>
<ul id="todo-list"></ul>
```

**dom\_todo.js:**

```javascript
const form = document.querySelector("#todo-form");
const input = document.querySelector("#todo-input");
const list = document.querySelector("#todo-list");

let nextId = 1;

function createItem(title) {
  const id = String(nextId++);
  const li = document.createElement("li");
  li.dataset.id = id;

  const label = document.createElement("label");
  const checkbox = document.createElement("input");
  checkbox.type = "checkbox";
  checkbox.addEventListener("change", () => {
    li.classList.toggle("done", checkbox.checked);
  });

  const text = document.createElement("span");
  text.textContent = title;

  const remove = document.createElement("button");
  remove.type = "button";
  remove.textContent = "Remove";
  remove.addEventListener("click", () => li.remove());

  label.append(checkbox, text);
  li.append(label, remove);
  return li;
}

form.addEventListener("submit", (event) => {
  event.preventDefault();
  const title = input.value.trim();
  if (!title) return;
  list.append(createItem(title));
  input.value = "";
  input.focus();
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `preventDefault` reloads the page on submit.
* Building HTML with `innerHTML` + user text risks XSS — use `textContent`.
* Attaching listeners only on the form/list (delegation) scales better for many items.

## 🔗 Related [#-related]

* [Debounce input](/docs/javascript/examples/debounce-input)
* [LocalStorage prefs](/docs/javascript/examples/localstorage-prefs)


# Fetch JSON (/docs/javascript/examples/fetch-json)



# Fetch JSON [#fetch-json]

*Javascript · Example / how-to*

***

## 📋 Overview [#-overview]

Load JSON from an API with `fetch`, handle HTTP errors, and render a simple list in the DOM.

## 🔧 Core concepts [#-core-concepts]

| Piece             | Role              |
| ----------------- | ----------------- |
| `fetch`           | Network request   |
| `response.ok`     | Detect non-2xx    |
| `response.json()` | Parse body        |
| `async` / `await` | Linear async flow |

## 💡 Examples [#-examples]

**fetch\_json.js:**

```javascript
async function fetchJson(url, options = {}) {
  const response = await fetch(url, {
    headers: { Accept: "application/json", ...options.headers },
    ...options,
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status} for ${url}`);
  }
  return response.json();
}

async function loadPosts(target) {
  target.textContent = "Loading…";
  try {
    const posts = await fetchJson(
      "https://jsonplaceholder.typicode.com/posts?_limit=5",
    );
    target.replaceChildren();
    for (const post of posts) {
      const li = document.createElement("li");
      li.textContent = post.title;
      target.append(li);
    }
  } catch (err) {
    target.textContent = `Failed: ${err.message}`;
  }
}

const list = document.querySelector("#posts");
loadPosts(list);
```

**Abort on unmount / navigation:**

```javascript
const controller = new AbortController();
const data = await fetchJson(url, { signal: controller.signal });
// later: controller.abort();
```

## ⚠️ Pitfalls [#️-pitfalls]

* `fetch` only rejects on network failure — check `response.ok` yourself.
* Calling `.json()` twice on the same body fails; clone or read once.
* CORS blocks browser calls to many APIs — use a proxy or same-origin route.

## 🔗 Related [#-related]

* [Array pipeline](/docs/javascript/examples/array-pipeline)
* [DOM todo](/docs/javascript/examples/dom-todo)


# Examples (/docs/javascript/examples)



# Examples [#examples]

JavaScript notes in **Examples**.


# LocalStorage Prefs (/docs/javascript/examples/localstorage-prefs)



# LocalStorage Prefs [#localstorage-prefs]

*Javascript · Example / how-to*

***

## 📋 Overview [#-overview]

Persist simple user preferences (theme, density) in `localStorage` with JSON encode/decode and safe defaults.

## 🔧 Core concepts [#-core-concepts]

| Piece                      | Role                         |
| -------------------------- | ---------------------------- |
| `localStorage`             | Per-origin key/value strings |
| `JSON.stringify` / `parse` | Structured prefs             |
| Defaults merge             | Survive missing keys         |
| `storage` event            | Sync across tabs             |

## 💡 Examples [#-examples]

**localstorage\_prefs.js:**

```javascript
const STORAGE_KEY = "app.prefs.v1";

const DEFAULT_PREFS = {
  theme: "system",
  density: "comfortable",
};

function loadPrefs() {
  try {
    const raw = localStorage.getItem(STORAGE_KEY);
    if (!raw) return { ...DEFAULT_PREFS };
    const parsed = JSON.parse(raw);
    return { ...DEFAULT_PREFS, ...parsed };
  } catch {
    return { ...DEFAULT_PREFS };
  }
}

function savePrefs(prefs) {
  localStorage.setItem(STORAGE_KEY, JSON.stringify(prefs));
}

function applyTheme(theme) {
  const resolved =
    theme === "system"
      ? window.matchMedia("(prefers-color-scheme: dark)").matches
        ? "dark"
        : "light"
      : theme;
  document.documentElement.dataset.theme = resolved;
}

const prefs = loadPrefs();
applyTheme(prefs.theme);

document.querySelector("#theme").value = prefs.theme;
document.querySelector("#theme").addEventListener("change", (event) => {
  prefs.theme = event.target.value;
  savePrefs(prefs);
  applyTheme(prefs.theme);
});

window.addEventListener("storage", (event) => {
  if (event.key !== STORAGE_KEY || !event.newValue) return;
  const next = { ...DEFAULT_PREFS, ...JSON.parse(event.newValue) };
  applyTheme(next.theme);
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* `localStorage` is sync and string-only — always JSON round-trip objects.
* Quota / private mode can throw — wrap reads/writes in `try/catch`.
* Do not store secrets; anything in `localStorage` is readable by XSS.

## 🔗 Related [#-related]

* [DOM todo](/docs/javascript/examples/dom-todo)
* [Debounce input](/docs/javascript/examples/debounce-input)


# Attributes (/docs/javascript/dom/attributes)



# Attributes [#attributes]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

HTML attributes are reflected on elements as content attributes and often as IDL properties. Use `getAttribute` / `setAttribute` for the HTML attribute string; use properties (`el.id`, `el.href`) for typed live values. `data-*` maps to `dataset`.

## 🔧 Core concepts [#-core-concepts]

* **Attribute API**: `hasAttribute`, `getAttribute`, `setAttribute`, `removeAttribute`, `toggleAttribute`.
* **NamedNodeMap**: `el.attributes` — live list of `Attr` nodes.
* **Property vs attribute**: `el.value` (live) vs `getAttribute("value")` (initial HTML).
* **Boolean attributes**: presence means true (`disabled`, `checked`, `hidden`).
* **`dataset`**: `data-user-id` → `el.dataset.userId`.
* **Namespaces**: `getAttributeNS` / `setAttributeNS` for SVG/MathML.

```js
el.setAttribute("aria-label", "Close");
el.toggleAttribute("hidden", true);
```

## 💡 Examples [#-examples]

```js
const btn = document.querySelector("button");

btn.setAttribute("type", "button");
btn.getAttribute("type"); // "button"
btn.hasAttribute("disabled"); // false
btn.toggleAttribute("disabled"); // adds
btn.removeAttribute("disabled");

// data-*
el.dataset.userId = "42";
console.log(el.getAttribute("data-user-id")); // "42"
delete el.dataset.userId;

// Reflecting properties
const a = document.createElement("a");
a.href = "/docs";
a.getAttribute("href"); // "/docs" (may be absolutized for href property)

// Iterate attributes
for (const attr of el.attributes) {
  console.log(attr.name, attr.value);
}

// ARIA
el.setAttribute("role", "dialog");
el.setAttribute("aria-modal", "true");

// Boolean via property
input.disabled = true;
input.hasAttribute("disabled"); // true
```

```js
// Safe read with default
function attr(el, name, fallback = "") {
  return el.hasAttribute(name) ? el.getAttribute(name) : fallback;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `getAttribute` returns `null` when missing — not `""`.
* Changing the `value` property on inputs does not always update the content attribute the same way across browsers — know which you need.
* `dataset` values are always strings; parse numbers yourself.
* Setting `innerHTML` can wipe attributes on replaced subtrees.
* Invalid attribute names or wrong namespaces fail silently or throw in XML.

## 🔗 Related [#-related]

* [class.md](/docs/javascript/dom/class) — class attribute / classList
* [selectors.md](/docs/javascript/dom/selectors) — attribute selectors
* [content\_methods.md](/docs/javascript/dom/content-methods) — reading content
* [form.md](/docs/javascript/dom/form) — form control properties
* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — creating elements
* [../strings.md](/docs/javascript/strings) — string values
* [../objects.md](/docs/javascript/objects) — dataset object


# Canvas API (/docs/javascript/dom/canvas-api)



# Canvas API [#canvas-api]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The Canvas 2D API draws shapes, text, images, and pixels onto a `<canvas>` bitmap via `getContext("2d")`. Great for charts, games, and effects. For retained-mode scene graphs prefer SVG; for 3D use WebGL. Always size the drawing buffer for DPR sharpness.

## 🔧 Core concepts [#-core-concepts]

* **Context**: `const ctx = canvas.getContext("2d", \{ alpha, desynchronized \})`.
* **Drawing buffer**: `canvas.width` / `height` (attributes) ≠ CSS size.
* **State**: `save` / `restore`, transforms, styles (`fillStyle`, `strokeStyle`, `lineWidth`).
* **Paths**: `beginPath`, `moveTo`, `lineTo`, `arc`, `rect`, `fill`, `stroke`, `clip`.
* **Images**: `drawImage`, `getImageData` / `putImageData`.
* **Text**: `font`, `fillText`, `measureText`.
* **Hit testing**: custom math or `isPointInPath`.

```js
const canvas = document.querySelector("canvas");
const ctx = canvas.getContext("2d");
ctx.fillStyle = "#3366ff";
ctx.fillRect(10, 10, 100, 60);
```

## 💡 Examples [#-examples]

```js
// HiDPI setup
function fitCanvas(canvas) {
  const rect = canvas.getBoundingClientRect();
  const dpr = devicePixelRatio || 1;
  canvas.width = Math.round(rect.width * dpr);
  canvas.height = Math.round(rect.height * dpr);
  const ctx = canvas.getContext("2d");
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  return ctx;
}

// Path
ctx.beginPath();
ctx.arc(50, 50, 40, 0, Math.PI * 2);
ctx.fill();

// Transform
ctx.save();
ctx.translate(100, 100);
ctx.rotate(Math.PI / 4);
ctx.fillRect(-25, -25, 50, 50);
ctx.restore();

// Image
const img = new Image();
img.onload = () => ctx.drawImage(img, 0, 0, 200, 120);
img.src = "/photo.jpg";

// Pixels
const data = ctx.getImageData(0, 0, w, h);
for (let i = 0; i < data.data.length; i += 4) {
  data.data[i] = 255 - data.data[i]; // R invert
}
ctx.putImageData(data, 0, 0);

// Animation
function frame(t) {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  draw(t);
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Setting `width`/`height` resets the context state and clears the bitmap.
* CSS scaling without DPR adjustment blurs drawings.
* `getImageData` is expensive and taints canvas if cross-origin images lack CORS.
* Canvas is inaccessible by default — provide fallback text / ARIA when needed.
* Clearing with `clearRect` each frame; forgetting it leaves trails.

## 🔗 Related [#-related]

* [../Html/canvas.md](/docs/javascript/../html/canvas) — canvas element
* [../typed\_arrays.md](/docs/javascript/typed-arrays) — ImageData buffers
* [../timers.md](/docs/javascript/timers) — rAF loops
* [resize\_observer.md](/docs/javascript/dom/resize-observer) — responsive canvas
* [../performance.md](/docs/javascript/performance) — draw cost


# classList & CSS Classes (/docs/javascript/dom/class)



# classList & CSS Classes [#classlist--css-classes]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

`element.classList` is a live `DOMTokenList` for CSS class tokens. Prefer it over string-splicing `className`. It supports add/remove/toggle/replace and iteration.

## 🔧 Core concepts [#-core-concepts]

* **API**: `add`, `remove`, `toggle`, `contains`, `replace`, `item`, `length`.
* **`className`**: full string getter/setter (space-separated).
* **`classList.value`**: string form of the token list.
* **Toggle force**: `toggle(token, force)` — `true` adds, `false` removes.
* **SVG**: same `classList` on SVG elements in modern browsers.

```js
el.classList.add("is-open", "animate");
el.classList.toggle("is-open");
```

## 💡 Examples [#-examples]

```js
const el = document.querySelector(".panel");

el.classList.add("visible");
el.classList.remove("hidden");
el.classList.contains("visible"); // true

// Force on/off
el.classList.toggle("active", isActive);

// Replace token
el.classList.replace("theme-light", "theme-dark");

// Iterate
for (const token of el.classList) {
  console.log(token);
}

// One-shot from state object
function applyState(el, state) {
  el.classList.toggle("is-loading", state.loading);
  el.classList.toggle("is-error", state.error);
  el.classList.toggle("is-ready", state.ready);
}

// Avoid duplicates / empties — classList handles spaces & dupes
el.className = "  a   a  b "; // messy
el.classList.add("a", "b"); // clean tokens
```

```js
// Animation reflow trick
el.classList.remove("pulse");
void el.offsetWidth; // force reflow
el.classList.add("pulse");
```

```js
// Conditional multi-class from a list
function setClasses(el, tokens) {
  el.className = ""; // reset
  el.classList.add(...tokens.filter(Boolean));
}

setClasses(el, ["card", isFeatured && "card--featured", size]);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Tokens cannot contain spaces — each class is one token.
* `className` on SVG historically returned `SVGAnimatedString` — prefer `classList`.
* Toggling in tight loops can thrash layout if combined with measuring.
* Don’t store state only in classes if you need typed data — use `data-*` or JS state.
* Removing a missing class is a no-op; adding an existing class is a no-op.

## 🔗 Related [#-related]

* [attributes.md](/docs/javascript/dom/attributes) — class attribute
* [selectors.md](/docs/javascript/dom/selectors) — `.class` selectors
* [events.md](/docs/javascript/dom/events) — UI state toggles
* [content\_methods.md](/docs/javascript/dom/content-methods) — updating UI
* [position.md](/docs/javascript/dom/position) — layout reads after class changes
* [../strings.md](/docs/javascript/strings) — token strings


# Clipboard API (/docs/javascript/dom/clipboard-api)



# Clipboard API [#clipboard-api]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The Async Clipboard API reads and writes the system clipboard with promises: `navigator.clipboard.writeText` / `readText`, and richer `write` / `read` with `ClipboardItem`. Requires secure context and often transient user activation / permissions.

## 🔧 Core concepts [#-core-concepts]

* **Text**: `await navigator.clipboard.writeText(str)` / `readText()`.
* **Items**: `clipboard.write([new ClipboardItem(\{ [type]: blob \})])`.
* **Permissions**: `clipboard-read` / `clipboard-write` (browser-dependent).
* **Secure context**: HTTPS or localhost.
* **Fallback**: legacy `document.execCommand("copy")` with a temporary textarea (deprecated).
* **Paste events**: `paste` / `copy` / `cut` still useful for intercepting.

```js
await navigator.clipboard.writeText("Hello");
const text = await navigator.clipboard.readText();
```

## 💡 Examples [#-examples]

```js
// Copy button
btn.addEventListener("click", async () => {
  try {
    await navigator.clipboard.writeText(input.value);
    toast("Copied");
  } catch {
    toast("Clipboard blocked");
  }
});

// Copy HTML + plain text
async function copyRich(html, plain) {
  const item = new ClipboardItem({
    "text/plain": new Blob([plain], { type: "text/plain" }),
    "text/html": new Blob([html], { type: "text/html" }),
  });
  await navigator.clipboard.write([item]);
}

// Read image (where supported)
const items = await navigator.clipboard.read();
for (const item of items) {
  if (item.types.includes("image/png")) {
    const blob = await item.getType("image/png");
    img.src = URL.createObjectURL(blob);
  }
}

// Paste event
editor.addEventListener("paste", (e) => {
  const text = e.clipboardData?.getData("text/plain");
  const file = e.clipboardData?.files?.[0];
  // e.preventDefault(); custom insert
});

// Permission query
const status = await navigator.permissions.query({ name: "clipboard-read" });
```

```js
// Feature detect
if (!navigator.clipboard?.writeText) {
  /* show manual select UI */
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `readText` often requires permission + user gesture; expect failures in background tabs.
* Safari / Firefox policies differ for read — always try/catch and UX fallback.
* Don’t put secrets on the clipboard longer than needed.
* `ClipboardItem` blob MIME types must match what you write.
* Focus may be required — call from click handlers, not arbitrary timers.

## 🔗 Related [#-related]

* [events.md](/docs/javascript/dom/events) — copy/paste events
* [datatransfer.md](/docs/javascript/dom/datatransfer) — DataTransfer
* [drag\_drop.md](/docs/javascript/dom/drag-drop) — drag data
* [../encode.md](/docs/javascript/encode) — text encoding
* [form.md](/docs/javascript/dom/form) — selecting input text


# Content Methods (/docs/javascript/dom/content-methods)



# Content Methods [#content-methods]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

Read and write element content with `textContent`, `innerHTML`, `innerText`, and modern helpers like `insertAdjacentHTML`. Prefer `textContent` for untrusted strings; use HTML APIs only with sanitized markup.

## 🔧 Core concepts [#-core-concepts]

* **`textContent`**: all descendant text; no HTML parsing; fast and safe for plain text.
* **`innerHTML`**: get/set HTML markup; parses and replaces children.
* **`innerText`**: layout-aware visible text (triggers reflow); respects CSS.
* **`outerHTML`**: includes the element itself.
* **Adjacent**: `insertAdjacentHTML/Text/Element(position, ...)`.
* **Positions**: `beforebegin`, `afterbegin`, `beforeend`, `afterend`.

```js
el.textContent = userInput; // safe plain text
el.insertAdjacentHTML("beforeend", trustedHtml);
```

## 💡 Examples [#-examples]

```js
const box = document.querySelector("#box");

box.textContent = "Hello";
box.innerHTML = "<strong>Hello</strong>";

// Append HTML without wiping siblings' listeners on whole parent
box.insertAdjacentHTML("beforeend", "<li>Item</li>");
box.insertAdjacentText("afterbegin", "Note: ");

// Build with elements instead of HTML strings
const li = document.createElement("li");
li.textContent = item.name;
box.append(li);

// Read
const visible = box.innerText;
const all = box.textContent;

// Clear
box.replaceChildren(); // modern clear
// box.innerHTML = "";
```

```js
// Template + sanitize strategy: never assign raw user HTML
function renderComment(el, text) {
  el.textContent = "";
  const p = document.createElement("p");
  p.textContent = text;
  el.append(p);
}
```

```js
// insertAdjacentElement keeps node identity / listeners
const note = document.createElement("aside");
note.textContent = "Tip";
box.insertAdjacentElement("afterend", note);

console.log(box.outerHTML.slice(0, 40));
```

## ⚠️ Pitfalls [#️-pitfalls]

* Assigning `innerHTML` with user data is an XSS risk.
* Setting `innerHTML` destroys existing child nodes and their listeners.
* `innerText` is slower and style-dependent — prefer `textContent` for logic.
* `outerHTML` replacement can detach the element reference you hold.
* HTML parsing may normalize/fix markup unexpectedly.

## 🔗 Related [#-related]

* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — node creation
* [mutation\_methods.md](/docs/javascript/dom/mutation-methods) — append/replace
* [attributes.md](/docs/javascript/dom/attributes) — attributes vs content
* [selectors.md](/docs/javascript/dom/selectors) — finding targets
* [../strings.md](/docs/javascript/strings) — escaping text
* [../encode.md](/docs/javascript/encode) — encoding


# Create, Add, Remove (/docs/javascript/dom/create-add-remove)



# Create, Add, Remove [#create-add-remove]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

Build DOM trees with `createElement`, `createTextNode`, and modern insertion methods (`append`, `prepend`, `before`, `after`, `replaceWith`, `remove`). Prefer these over legacy `parentNode.appendChild` when you can.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `document.createElement(tag)`, `createElementNS`, `createTextNode`, `cloneNode(deep)`.
* **Insert**: `append`, `prepend`, `before`, `after`, `insertBefore`.
* **Replace / remove**: `replaceWith`, `replaceChildren`, `remove`, `replaceChild`.
* **DocumentFragment**: batch insert with one reflow.
* **Template**: `<template>` → `template.content.cloneNode(true)`.

```js
const el = document.createElement("button");
el.textContent = "Save";
parent.append(el);
```

## 💡 Examples [#-examples]

```js
const list = document.querySelector("#list");

const li = document.createElement("li");
li.className = "item";
li.textContent = "New item";
list.append(li);

// Multiple nodes
list.prepend(document.createTextNode("Header"), li.cloneNode(true));

// Fragment batching
const frag = document.createDocumentFragment();
for (const name of names) {
  const item = document.createElement("li");
  item.textContent = name;
  frag.append(item);
}
list.append(frag);

// Template
const tpl = document.querySelector("#row");
const row = tpl.content.cloneNode(true);
row.querySelector(".name").textContent = user.name;
list.append(row);

// Move existing node (reparent)
list.append(existingLi); // moves if already in DOM

// Remove
li.remove();
list.replaceChildren(); // clear all
```

```js
// Range createContextualFragment (HTML string → nodes)
const range = document.createRange();
const nodes = range.createContextualFragment("<span>Hi</span>");
parent.append(nodes);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `appendChild` returns the node; `append` can take strings (as text) and multiple args.
* Cloning with `cloneNode(true)` does **not** copy event listeners (unless you rebind).
* Inserting a node already in the tree **moves** it — it is not copied.
* Creating thousands of nodes one-by-one without a fragment causes layout thrash.
* `innerHTML += ...` re-parses the whole subtree — avoid in loops.

## 🔗 Related [#-related]

* [mutation\_methods.md](/docs/javascript/dom/mutation-methods) — mutation details
* [content\_methods.md](/docs/javascript/dom/content-methods) — text/HTML content
* [selectors.md](/docs/javascript/dom/selectors) — locating parents
* [document\_methods.md](/docs/javascript/dom/document-methods) — document factories
* [range.md](/docs/javascript/dom/range) — Range fragments
* [../strings.md](/docs/javascript/strings) — text nodes


# CSSOM (/docs/javascript/dom/cssom)



# CSSOM [#cssom]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

The CSS Object Model lets JS read and mutate stylesheets and computed style: `element.style`, `getComputedStyle`, `CSSStyleSheet` rules, and CSS variables. Prefer CSS classes for most UI state; use CSSOM for measured values, theming tokens, and dynamic rule injection.

## 🔧 Core concepts [#-core-concepts]

* **Inline**: `el.style.color`, `el.style.setProperty("--x", "1")`, `cssText`.
* **Computed**: `getComputedStyle(el)` — live, read-only, resolved values.
* **Sheets**: `document.styleSheets`, `sheet.cssRules`, `insertRule` / `deleteRule`.
* **Constructed stylesheets**: `new CSSStyleSheet()` + `adoptedStyleSheets` (shadow/document).
* **Variables**: `getPropertyValue("--token")`, `setProperty`, `removeProperty`.
* **OM values**: typed OM (`attributeStyleMap`) where supported.

```js
el.style.setProperty("--gap", "1rem");
const color = getComputedStyle(el).color;
```

## 💡 Examples [#-examples]

```js
// Toggle via custom property
document.documentElement.style.setProperty("--theme-bg", "#111");

// Read resolved size (px strings)
const { width, fontSize } = getComputedStyle(el);
const w = parseFloat(width);

// Avoid thrashing: batch reads/writes
const styles = els.map((el) => getComputedStyle(el).height);
els.forEach((el, i) => {
  el.style.minHeight = styles[i];
});

// Insert a rule
const sheet = document.styleSheets[0];
const i = sheet.insertRule(".flash { outline: 2px solid red; }", sheet.cssRules.length);
// sheet.deleteRule(i);

// Constructable stylesheet (components)
const sheet2 = new CSSStyleSheet();
sheet2.replaceSync(`:host { display: block; } .x { color: tomato; }`);
shadow.adoptedStyleSheets = [sheet2];

// CSS.escape for dynamic selectors
const sel = `#${CSS.escape(id)}`;
```

```js
// Feature: typed OM
el.attributeStyleMap.set("padding-top", CSS.px(8));
```

## ⚠️ Pitfalls [#️-pitfalls]

* `el.style` only sees **inline** styles — not classes; use `getComputedStyle` for final values.
* `getComputedStyle` forces layout — don’t call it in tight loops interleaved with writes.
* Cross-origin stylesheets block rule access (SecurityError).
* Shorthand reads from computed style may be empty or expanded inconsistently.
* Prefer classList for state; inline styles fight specificity and CSP.

## 🔗 Related [#-related]

* [class.md](/docs/javascript/dom/class) — classList
* [attributes.md](/docs/javascript/dom/attributes) — style attribute
* [position.md](/docs/javascript/dom/position) — layout metrics
* [resize\_observer.md](/docs/javascript/dom/resize-observer) — size changes
* [../CSS/variables.md](/docs/javascript/../css/variables) — custom properties


# Custom Elements (/docs/javascript/dom/custom-elements)



# Custom Elements [#custom-elements]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Custom Elements let you define new HTML tags (or upgrade builtins) with a JavaScript class. Combined with Shadow DOM and `<template>`, they form Web Components — reusable, encapsulated UI with lifecycle callbacks.

## 🔧 Core concepts [#-core-concepts]

* **Define**: `customElements.define("my-el", class extends HTMLElement \{ ... \})`.
* **Name**: must include a hyphen (`my-card`).
* **Lifecycle**: `connectedCallback`, `disconnectedCallback`, `attributeChangedCallback`, `adoptedCallback`.
* **Observed attrs**: static `observedAttributes = ["open"]`.
* **Autonomous** vs **customized built-in**: `extends: "button"` + `is="..."`.
* **Upgrade**: `customElements.whenDefined("my-el")`, `upgrade`.

```js
class HelloWorld extends HTMLElement {
  connectedCallback() {
    this.textContent = "Hello";
  }
}
customElements.define("hello-world", HelloWorld);
```

## 💡 Examples [#-examples]

```js
class FancyButton extends HTMLElement {
  static observedAttributes = ["label", "disabled"];

  constructor() {
    super();
    this.attachShadow({ mode: "open" });
    this.shadowRoot.innerHTML = `<button part="button"><slot></slot></button>`;
    this._btn = this.shadowRoot.querySelector("button");
  }

  connectedCallback() {
    this._btn.addEventListener("click", this._onClick);
  }

  disconnectedCallback() {
    this._btn.removeEventListener("click", this._onClick);
  }

  attributeChangedCallback(name, oldVal, newVal) {
    if (oldVal === newVal) return;
    if (name === "label") this._btn.textContent = newVal;
    if (name === "disabled") this._btn.disabled = newVal != null;
  }

  _onClick = () => {
    this.dispatchEvent(new CustomEvent("fancy-click", { bubbles: true }));
  };
}
customElements.define("fancy-button", FancyButton);

// Wait for definition
await customElements.whenDefined("fancy-button");
document.createElement("fancy-button");

// Customized built-in (where supported)
class ExpandingList extends HTMLUListElement {
  connectedCallback() {
    this.addEventListener("click", () => this.classList.toggle("open"));
  }
}
customElements.define("expanding-list", ExpandingList, { extends: "ul" });
// <ul is="expanding-list">
```

```js
// Reflect property ↔ attribute
get open() {
  return this.hasAttribute("open");
}
set open(v) {
  this.toggleAttribute("open", Boolean(v));
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Must call `super()` in constructors before using `this`; don’t read attributes too early if not upgraded.
* Customized built-ins lack Safari support historically — prefer autonomous elements for portability.
* `attributeChangedCallback` does not fire for property-only changes unless you reflect.
* Defining twice throws — guard or use feature detection.
* Slotted light DOM vs shadow: know where events retarget.

## 🔗 Related [#-related]

* [shadow\_dom.md](/docs/javascript/dom/shadow-dom) — encapsulation
* [../Html/template\_slot.md](/docs/javascript/../html/template-slot) — templates
* [../Html/web\_components.md](/docs/javascript/../html/web-components) — overview
* [attributes.md](/docs/javascript/dom/attributes) — attribute APIs
* [events.md](/docs/javascript/dom/events) — CustomEvent


# DataTransfer & Drag-and-Drop (/docs/javascript/dom/datatransfer)



# DataTransfer & Drag-and-Drop [#datatransfer--drag-and-drop]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

`DataTransfer` carries payload during drag-and-drop and clipboard operations. Set data in `dragstart`, read it in `drop`. Use `DataTransferItemList` for files and multiple MIME types.

## 🔧 Core concepts [#-core-concepts]

* **Events**: `dragstart`, `drag`, `dragenter`, `dragover`, `dragleave`, `drop`, `dragend`.
* **`event.dataTransfer`**: `setData`, `getData`, `clearData`, `types`, `files`, `items`.
* **`effectAllowed` / `dropEffect`**: copy | move | link | none.
* **`setDragImage(element, x, y)`**: custom ghost image.
* **Clipboard**: `ClipboardEvent.clipboardData` is also a `DataTransfer`.

```js
el.addEventListener("dragstart", (e) => {
  e.dataTransfer.setData("text/plain", el.id);
  e.dataTransfer.effectAllowed = "move";
});
```

## 💡 Examples [#-examples]

```js
const source = document.querySelector("#source");
const target = document.querySelector("#target");

source.draggable = true;

source.addEventListener("dragstart", (e) => {
  e.dataTransfer.setData("application/x-item-id", source.dataset.id);
  e.dataTransfer.setData("text/plain", source.textContent);
  e.dataTransfer.effectAllowed = "copyMove";
});

// Must preventDefault on dragover to allow drop
target.addEventListener("dragover", (e) => {
  e.preventDefault();
  e.dataTransfer.dropEffect = "move";
  target.classList.add("drag-over");
});

target.addEventListener("dragleave", () => {
  target.classList.remove("drag-over");
});

target.addEventListener("drop", (e) => {
  e.preventDefault();
  target.classList.remove("drag-over");
  const id = e.dataTransfer.getData("application/x-item-id");
  const node = document.querySelector(`[data-id="${CSS.escape(id)}"]`);
  if (node) target.append(node);
});

// File drop
target.addEventListener("drop", async (e) => {
  e.preventDefault();
  const files = [...e.dataTransfer.files];
  for (const file of files) {
    console.log(file.name, file.type, file.size);
  }
});
```

```js
// Clipboard paste image
editor.addEventListener("paste", (e) => {
  const items = e.clipboardData?.items;
  if (!items) return;
  for (const item of items) {
    if (item.type.startsWith("image/")) {
      const file = item.getAsFile();
      // upload / preview file
    }
  }
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Without `preventDefault` on `dragover`, `drop` will not fire.
* `getData` for custom types may be empty outside `drop` in some browsers (security).
* `files` is only populated for file drags — not for element drags.
* MIME type strings are case-sensitive conventions (`text/plain`).
* Touch devices often lack HTML5 DnD — provide click alternatives.

## 🔗 Related [#-related]

* [events.md](/docs/javascript/dom/events) — event handling
* [form.md](/docs/javascript/dom/form) — file inputs
* [attributes.md](/docs/javascript/dom/attributes) — draggable / data-\*
* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — moving nodes
* [../api.md](/docs/javascript/api) — File / Blob APIs
* [../async.md](/docs/javascript/async) — async file reads


# Document Methods (/docs/javascript/dom/document-methods)



# Document Methods [#document-methods]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

`document` is the entry point to the DOM tree: querying, creating nodes, reading metadata, and listening for lifecycle events. Prefer `document` methods over legacy globals like `document.all`.

## 🔧 Core concepts [#-core-concepts]

* **Query**: `getElementById`, `querySelector`, `querySelectorAll`, `getElementsBy*`.
* **Create**: `createElement`, `createTextNode`, `createDocumentFragment`, `createRange`.
* **Adopt/import**: `importNode`, `adoptNode` across documents.
* **Metadata**: `title`, `URL`, `documentElement`, `head`, `body`, `compatMode`.
* **Ready**: `DOMContentLoaded`, `document.readyState`, `document.fonts`.
* **Visibility**: `document.visibilityState`, `visibilitychange`.

```js
document.addEventListener("DOMContentLoaded", () => {
  init(document.getElementById("app"));
});
```

## 💡 Examples [#-examples]

```js
const app = document.getElementById("app");
const first = document.querySelector(".item");
const all = document.querySelectorAll(".item"); // static NodeList

// Collections (live)
const live = document.getElementsByClassName("item");
const tags = document.getElementsByTagName("div");

// Create & insert
const el = document.createElement("section");
el.id = "panel";
document.body.append(el);

// Ready helpers
if (document.readyState === "loading") {
  document.addEventListener("DOMContentLoaded", start);
} else {
  start();
}

// Visibility pause
document.addEventListener("visibilitychange", () => {
  if (document.hidden) pause();
  else resume();
});

// Current script (classic scripts)
const current = document.currentScript;

// Open graph-ish meta
document.title = "Dashboard";
```

```js
// Wait for fonts
await document.fonts.ready;
drawText();

// CSS escape for dynamic selectors
const id = "a.b#c";
document.querySelector(`#${CSS.escape(id)}`);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `getElementsBy*` collections are **live**; `querySelectorAll` is static.
* `document.write` clobbers the page after load — avoid it.
* Scripts of `type="module"` defer by default — `DOMContentLoaded` may already have fired.
* `getElementById` does not need `#`; `querySelector` does.
* Accessing `document.body` before it exists returns `null`.

## 🔗 Related [#-related]

* [selectors.md](/docs/javascript/dom/selectors) — selector engines
* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — node factories
* [events.md](/docs/javascript/dom/events) — document listeners
* [window.md](/docs/javascript/dom/window) — window ↔ document
* [navigation.md](/docs/javascript/dom/navigation) — location / history
* [../async.md](/docs/javascript/async) — waiting for ready


# Drag & Drop (/docs/javascript/dom/drag-drop)



# Drag & Drop [#drag--drop]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

HTML Drag and Drop uses `draggable` elements and drag events (`dragstart`, `dragover`, `drop`, …) with `DataTransfer` payloads. Good for reordering lists and file drops. For complex apps, consider Pointer Events libraries — native DnD has quirks across browsers.

## 🔧 Core concepts [#-core-concepts]

* **Make draggable**: `draggable="true"` on elements (images/links are draggable by default).
* **Events (source)**: `dragstart`, `drag`, `dragend`.
* **Events (target)**: `dragenter`, `dragover`, `dragleave`, `drop`.
* **`dataTransfer`**: `setData`/`getData`, `effectAllowed`, `dropEffect`, `files`, `items`.
* **Must `preventDefault` on `dragover`** to allow dropping.
* **File drop**: read `e.dataTransfer.files`.

```js
el.draggable = true;
el.addEventListener("dragstart", (e) => {
  e.dataTransfer.setData("text/plain", el.id);
});
zone.addEventListener("dragover", (e) => e.preventDefault());
zone.addEventListener("drop", (e) => {
  e.preventDefault();
  const id = e.dataTransfer.getData("text/plain");
});
```

## 💡 Examples [#-examples]

```js
// Reorder list item
list.querySelectorAll("[data-id]").forEach((item) => {
  item.draggable = true;
  item.addEventListener("dragstart", (e) => {
    e.dataTransfer.setData("text/plain", item.dataset.id);
    item.classList.add("dragging");
  });
  item.addEventListener("dragend", () => item.classList.remove("dragging"));
});

list.addEventListener("dragover", (e) => {
  e.preventDefault();
  const after = getDragAfterElement(list, e.clientY);
  const dragging = list.querySelector(".dragging");
  if (!after) list.append(dragging);
  else list.insertBefore(dragging, after);
});

// File drop zone
zone.addEventListener("dragover", (e) => {
  e.preventDefault();
  zone.classList.add("over");
});
zone.addEventListener("dragleave", () => zone.classList.remove("over"));
zone.addEventListener("drop", async (e) => {
  e.preventDefault();
  zone.classList.remove("over");
  const files = [...e.dataTransfer.files];
  for (const file of files) await upload(file);
});

// Custom ghost image
e.dataTransfer.setDragImage(img, 10, 10);
e.dataTransfer.effectAllowed = "move";
```

```js
// Types
e.dataTransfer.types; // ["text/plain", "Files", ...]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Forgetting `preventDefault` on `dragover` silently blocks `drop`.
* `getData` may be empty in `dragover` in some browsers for security — read on `drop`.
* Touch devices historically weak for HTML DnD — provide alternatives.
* Draggable text selection conflicts — manage UX carefully.
* See also Pointer Events for custom drag implementations.

## 🔗 Related [#-related]

* [datatransfer.md](/docs/javascript/dom/datatransfer) — DataTransfer deep dive
* [events.md](/docs/javascript/dom/events) — event model
* [clipboard\_api.md](/docs/javascript/dom/clipboard-api) — clipboard data
* [form.md](/docs/javascript/dom/form) — file inputs
* [../encode.md](/docs/javascript/encode) — MIME types


# Events (/docs/javascript/dom/events)



# Events [#events]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

DOM events notify your code about user and system actions. Register with `addEventListener`, control propagation with `stopPropagation` / `preventDefault`, and prefer delegation for dynamic lists.

## 🔧 Core concepts [#-core-concepts]

* **Listen**: `addEventListener(type, handler, options?)`, `removeEventListener` (same ref/options).
* **Options**: `\{ capture, once, passive, signal \}`.
* **Phases**: capture → target → bubble.
* **Event object**: `type`, `target`, `currentTarget`, `eventPhase`, `timeStamp`.
* **Cancel**: `preventDefault()` when `cancelable`; check `defaultPrevented`.
* **Custom**: `new CustomEvent(name, \{ detail, bubbles, cancelable \})` + `dispatchEvent`.

```js
btn.addEventListener("click", onClick, { once: true });
```

## 💡 Examples [#-examples]

```js
function onClick(e) {
  console.log(e.target, e.currentTarget);
  e.preventDefault();
}

link.addEventListener("click", onClick);
link.removeEventListener("click", onClick);

// AbortSignal unsubscribe
const ac = new AbortController();
window.addEventListener("resize", onResize, { signal: ac.signal });
ac.abort(); // removes listener

// Delegation
list.addEventListener("click", (e) => {
  const item = e.target.closest("li[data-id]");
  if (!item || !list.contains(item)) return;
  select(item.dataset.id);
});

// Keyboard
input.addEventListener("keydown", (e) => {
  if (e.key === "Enter" && !e.shiftKey) {
    e.preventDefault();
    submit();
  }
});

// Passive scroll (perf)
window.addEventListener("touchmove", onMove, { passive: true });

// Custom events
panel.addEventListener("cart:add", (e) => console.log(e.detail));
panel.dispatchEvent(
  new CustomEvent("cart:add", { detail: { id: 1 }, bubbles: true }),
);
```

```js
// Pointer events unify mouse/touch/pen
el.addEventListener("pointerdown", (e) => {
  el.setPointerCapture(e.pointerId);
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Anonymous handlers cannot be removed — keep a reference.
* Capture flag must match between add and remove.
* `passive: true` listeners cannot `preventDefault` (useful for scroll perf).
* Inline `onclick=` attributes and property handlers differ from `addEventListener` stacking.
* Forgetting delegation causes missing listeners on dynamically added nodes.

## 🔗 Related [#-related]

* [form.md](/docs/javascript/dom/form) — submit / input events
* [datatransfer.md](/docs/javascript/dom/datatransfer) — drag events
* [selectors.md](/docs/javascript/dom/selectors) — closest / matches
* [window.md](/docs/javascript/dom/window) — window-level events
* [mutation\_methods.md](/docs/javascript/dom/mutation-methods) — MutationObserver
* [../api.md](/docs/javascript/api) — AbortSignal
* [../async.md](/docs/javascript/async) — async handlers


# Fetch Streaming (/docs/javascript/dom/fetch-streaming)



# Fetch Streaming [#fetch-streaming]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Fetch responses expose a `ReadableStream` body for incremental processing — large files, SSE-like chunked text, and progressive JSON. Use readers, `TextDecoderStream`, and backpressure-aware transforms instead of buffering entire payloads with `res.text()` / `res.json()`.

## 🔧 Core concepts [#-core-concepts]

* **Body**: `response.body` → `ReadableStream`.
* **Read**: `const reader = body.getReader()` then `reader.read()` → `\{ value, done \}`.
* **Cancel**: `reader.cancel()` / `AbortSignal` on fetch.
* **Tee**: `body.tee()` for dual consumers.
* **Pipes**: `pipeThrough(new TextDecoderStream())`, `pipeTo(writable)`.
* **Request streams**: duplex upload where supported (`duplex: "half"`).

```js
const res = await fetch("/large.txt");
const reader = res.body.getReader();
const { value, done } = await reader.read();
```

## 💡 Examples [#-examples]

```js
// Byte loop
async function readBytes(url, signal) {
  const res = await fetch(url, { signal });
  if (!res.ok) throw new Error(res.status);
  const reader = res.body.getReader();
  const chunks = [];
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    chunks.push(value);
  }
  return chunks;
}

// Text lines via streams
async function* lines(url) {
  const res = await fetch(url);
  const text = res.body.pipeThrough(new TextDecoderStream());
  const reader = text.getReader();
  let buf = "";
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    buf += value;
    let idx;
    while ((idx = buf.indexOf("\n")) >= 0) {
      yield buf.slice(0, idx);
      buf = buf.slice(idx + 1);
    }
  }
  if (buf) yield buf;
}

// Progress with Content-Length
async function downloadWithProgress(url, onProgress) {
  const res = await fetch(url);
  const total = Number(res.headers.get("content-length")) || 0;
  let loaded = 0;
  const reader = res.body.getReader();
  const chunks = [];
  while (true) {
    const { value, done } = await reader.read();
    if (done) break;
    chunks.push(value);
    loaded += value.byteLength;
    onProgress(loaded, total);
  }
  return new Blob(chunks);
}

// Abort mid-stream
const c = new AbortController();
fetch("/stream", { signal: c.signal });
c.abort();
```

## ⚠️ Pitfalls [#️-pitfalls]

* Calling `res.json()` after reading `body` fails — body can be consumed once (unless teed).
* Not all servers send useful `Content-Length` (chunked) — progress may be indeterminate.
* Backpressure: don’t buffer unbounded chunks in memory.
* CORS and opaque responses limit body access.
* Upload streaming support is uneven across browsers — feature-detect.

## 🔗 Related [#-related]

* [../fetch.md](/docs/javascript/fetch) — fetch basics
* [../abort\_controller.md](/docs/javascript/abort-controller) — cancel
* [../typed\_arrays.md](/docs/javascript/typed-arrays) — Uint8Array chunks
* [../async.md](/docs/javascript/async) — async iteration
* [../encode.md](/docs/javascript/encode) — TextDecoder


# Focus & Blur (/docs/javascript/dom/focus-blur)



# Focus & Blur [#focus--blur]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Focus determines which element receives keyboard input. Manage it with `focus()`, `blur()`, `tabIndex`, autofocus, and focus events. Critical for accessibility, modals, and forms. Prefer moving focus intentionally; never trap keyboard users without an escape.

## 🔧 Core concepts [#-core-concepts]

* **Methods**: `el.focus(\{ preventScroll? \})`, `el.blur()`.
* **Events**: `focus`, `blur` (no bubble); `focusin`, `focusout` (bubble).
* **`document.activeElement`**: currently focused element.
* **Tab order**: DOM order + `tabindex` (`0` in order, positive avoid, `-1` programmatic only).
* **Focusable**: links, buttons, inputs, `[tabindex]`, some custom with `tabindex=0`.
* **`:focus-visible`**: keyboard-ish focus styling (CSS).

```js
input.focus();
input.addEventListener("focus", () => input.select());
```

## 💡 Examples [#-examples]

```js
// focusin delegation
form.addEventListener("focusin", (e) => {
  e.target.closest(".field")?.classList.add("focused");
});
form.addEventListener("focusout", (e) => {
  e.target.closest(".field")?.classList.remove("focused");
});

// Modal open: focus first control, restore later
let prev;
function openModal(modal) {
  prev = document.activeElement;
  modal.showModal?.() ?? modal.removeAttribute("hidden");
  modal.querySelector("button, [href], input")?.focus();
}
function closeModal(modal) {
  modal.close?.() ?? modal.setAttribute("hidden", "");
  prev?.focus();
}

// Programmatic-only focus target
const panel = document.querySelector("#panel");
panel.tabIndex = -1;
panel.focus({ preventScroll: true });

// Detect focus leaving container
container.addEventListener("focusout", (e) => {
  if (!container.contains(e.relatedTarget)) {
    // focus left container
  }
});

// Roving tabindex pattern (toolbar)
function setActive(items, active) {
  items.forEach((el) => (el.tabIndex = el === active ? 0 : -1));
  active.focus();
}
```

```js
// Don’t steal focus on every render
if (document.activeElement !== input) input.focus();
```

## ⚠️ Pitfalls [#️-pitfalls]

* `focus`/`blur` don’t bubble — use `focusin`/`focusout` for delegation.
* Positive `tabindex` creates maintenance nightmares — prefer DOM order + `0`/`-1`.
* Focusing hidden elements fails or confuses AT — show first, then focus.
* `preventScroll` support matters for sticky headers.
* Removing a focused node moves focus to `<body>` — restore deliberately.

## 🔗 Related [#-related]

* [events.md](/docs/javascript/dom/events) — focus events
* [forms\_validation.md](/docs/javascript/dom/forms-validation) — form UX
* [../Html/dialog.md](/docs/javascript/../html/dialog) — modal focus
* [../Html/accessibility.md](/docs/javascript/../html/accessibility) — a11y
* [../Html/aria.md](/docs/javascript/../html/aria) — aria-activedescendant


# Forms (/docs/javascript/dom/form)



# Forms [#forms]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

HTML forms expose controls, validation, and submission APIs. Use `FormData`, constraint validation, and `submit` / `input` / `change` events. Prefer progressive enhancement over hijacking every submit blindly.

## 🔧 Core concepts [#-core-concepts]

* **Elements**: `form.elements`, named access `form.email`, `HTMLFormControlsCollection`.
* **Events**: `submit`, `input`, `change`, `invalid`, `reset`.
* **Validation**: `checkValidity`, `reportValidity`, `setCustomValidity`, `:valid`/`:invalid`.
* **`FormData`**: `new FormData(form)` — key/value including files.
* **Submit**: `requestSubmit()` runs validation; `form.submit()` does not.

```js
form.addEventListener("submit", async (e) => {
  e.preventDefault();
  const data = new FormData(form);
  await fetch(form.action, { method: form.method, body: data });
});
```

## 💡 Examples [#-examples]

```js
const form = document.querySelector("#signup");
const email = form.elements.namedItem("email");

form.addEventListener("submit", (e) => {
  if (!form.checkValidity()) {
    e.preventDefault();
    form.reportValidity();
    return;
  }
  // native submit continues if not prevented
});

email.addEventListener("input", () => {
  if (email.validity.typeMismatch) {
    email.setCustomValidity("Enter a valid email");
  } else {
    email.setCustomValidity("");
  }
});

// FormData inspection
const fd = new FormData(form);
for (const [k, v] of fd) console.log(k, v);
fd.append("source", "web");

// JSON instead of multipart
async function submitJson(form) {
  const data = Object.fromEntries(new FormData(form).entries());
  await fetch("/api", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data),
  });
}

// Programmatic submit with validation
form.requestSubmit();
```

```js
// File input
const file = form.elements.file.files?.[0];
if (file) console.log(file.name, file.size);
```

## ⚠️ Pitfalls [#️-pitfalls]

* `form.submit()` skips submit event and constraint validation — use `requestSubmit()`.
* Unnamed controls are omitted from `FormData`.
* Disabled fields are excluded from submission.
* Multiple controls with the same name need `getAll`.
* Don’t forget `enctype` for files (`multipart/form-data` is automatic with `FormData` + fetch).

## 🔗 Related [#-related]

* [events.md](/docs/javascript/dom/events) — submit/input
* [attributes.md](/docs/javascript/dom/attributes) — required / name
* [selectors.md](/docs/javascript/dom/selectors) — finding controls
* [../fetch.md](/docs/javascript/fetch) — posting FormData
* [../json.md](/docs/javascript/json) — JSON bodies
* [../encode.md](/docs/javascript/encode) — URLSearchParams
* [datatransfer.md](/docs/javascript/dom/datatransfer) — file drops


# Forms Validation (/docs/javascript/dom/forms-validation)



# Forms Validation [#forms-validation]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Constraint Validation API gives native form checks: `required`, `type`, `pattern`, `min`/`max`, `minlength`/`maxlength`, and custom validity. Prefer native UI + progressive enhancement; use `setCustomValidity` for app-specific rules and `checkValidity` / `reportValidity` to trigger them.

## 🔧 Core concepts [#-core-concepts]

* **Element APIs**: `checkValidity()`, `reportValidity()`, `setCustomValidity(msg)`, `validity`, `validationMessage`, `willValidate`.
* **Form**: `form.checkValidity()`, `form.reportValidity()`, `novalidate` attribute.
* **Events**: `invalid` (cancelable per control), `input`/`change` to clear custom errors.
* **`validity` flags**: `valueMissing`, `typeMismatch`, `patternMismatch`, `tooLong`, `tooShort`, `rangeUnderflow`, `rangeOverflow`, `stepMismatch`, `customError`, `valid`.
* **CSS**: `:valid`, `:invalid`, `:user-valid`, `:user-invalid`.

```js
email.setCustomValidity(
  email.validity.typeMismatch ? "Enter a valid email" : "",
);
form.reportValidity();
```

## 💡 Examples [#-examples]

```js
const form = document.querySelector("form");
const password = form.elements.password;
const confirm = form.elements.confirm;

function syncPasswords() {
  confirm.setCustomValidity(
    confirm.value !== password.value ? "Passwords must match" : "",
  );
}
password.addEventListener("input", syncPasswords);
confirm.addEventListener("input", syncPasswords);

form.addEventListener("submit", (e) => {
  syncPasswords();
  if (!form.checkValidity()) {
    e.preventDefault();
    form.reportValidity();
    return;
  }
  e.preventDefault();
  submitData(new FormData(form));
});

// Live field message
input.addEventListener("invalid", (e) => {
  e.preventDefault(); // block browser bubble if custom UI
  showError(input, input.validationMessage);
});
input.addEventListener("input", () => {
  input.setCustomValidity("");
  clearError(input);
});

// Programmatic check without UI
if (username.validity.tooShort) {
  /* ... */
}
```

```html
<input
  name="username"
  required
  minlength="3"
  pattern="[a-z0-9_]+"
  title="Letters, numbers, underscore"
/>
```

## ⚠️ Pitfalls [#️-pitfalls]

* `setCustomValidity("msg")` makes the field invalid until cleared with `""`.
* `novalidate` on form skips native checks — you must validate yourself.
* Don’t rely only on client validation — always validate on the server.
* `:invalid` styles can show too early — prefer `:user-invalid` where supported.
* Disabled fields are barred from validation / submission.

## 🔗 Related [#-related]

* [form.md](/docs/javascript/dom/form) — form controls
* [../Html/form.md](/docs/javascript/../html/form) — form HTML
* [../Html/input.md](/docs/javascript/../html/input) — input types
* [focus\_blur.md](/docs/javascript/dom/focus-blur) — focusing first error
* [events.md](/docs/javascript/dom/events) — submit/invalid


# Geolocation (/docs/javascript/dom/geolocation)



# Geolocation [#geolocation]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`navigator.geolocation` provides the device’s geographic position (GPS/Wi‑Fi/IP heuristics) after user permission. Use for maps, check-ins, and local results. Always handle denial, timeouts, and inaccurate coords; prefer watch only while needed.

## 🔧 Core concepts [#-core-concepts]

* **One-shot**: `getCurrentPosition(success, error?, options?)`.
* **Watch**: `watchPosition(...)` → watchId; clear with `clearWatch(id)`.
* **Position**: `coords.latitude`, `longitude`, `accuracy`, `altitude`, `heading`, `speed`, `timestamp`.
* **Options**: `enableHighAccuracy`, `timeout`, `maximumAge`.
* **Errors**: `PERMISSION_DENIED`, `POSITION_UNAVAILABLE`, `TIMEOUT`.
* **Secure context** required in modern browsers.

```js
navigator.geolocation.getCurrentPosition(
  (pos) => console.log(pos.coords.latitude, pos.coords.longitude),
  (err) => console.error(err.code, err.message),
  { enableHighAccuracy: true, timeout: 10_000, maximumAge: 60_000 },
);
```

## 💡 Examples [#-examples]

```js
function getPosition(options) {
  return new Promise((resolve, reject) => {
    if (!navigator.geolocation) {
      reject(new Error("unsupported"));
      return;
    }
    navigator.geolocation.getCurrentPosition(resolve, reject, options);
  });
}

const pos = await getPosition({
  enableHighAccuracy: false,
  timeout: 8000,
  maximumAge: 300_000,
});
const { latitude: lat, longitude: lng, accuracy } = pos.coords;

// Watch while map is open
const id = navigator.geolocation.watchPosition(
  (p) => map.setCenter(p.coords),
  (e) => console.warn(e),
  { enableHighAccuracy: true },
);
// later
navigator.geolocation.clearWatch(id);

// Permissions API (where supported)
const status = await navigator.permissions.query({ name: "geolocation" });
status.onchange = () => console.log(status.state);
```

```js
// Distance helper (Haversine km)
function km(a, b) {
  const R = 6371;
  const dLat = ((b.lat - a.lat) * Math.PI) / 180;
  const dLon = ((b.lng - a.lng) * Math.PI) / 180;
  const s =
    Math.sin(dLat / 2) ** 2 +
    Math.cos((a.lat * Math.PI) / 180) *
      Math.cos((b.lat * Math.PI) / 180) *
      Math.sin(dLon / 2) ** 2;
  return 2 * R * Math.asin(Math.sqrt(s));
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Permission prompts need a user gesture in many browsers — don’t call on page load without context.
* `accuracy` can be hundreds of meters indoors — show uncertainty to users.
* High accuracy drains battery — clear watches promptly.
* Spoofing / VPNs possible — never treat as strong auth.
* Desktop may use IP geolocation — expect coarse results.

## 🔗 Related [#-related]

* [../abort\_controller.md](/docs/javascript/abort-controller) — timeouts pattern
* [../promise.md](/docs/javascript/promise) — promisify callbacks
* [events.md](/docs/javascript/dom/events) — user activation
* [../intl.md](/docs/javascript/intl) — formatting coords for display
* [window.md](/docs/javascript/dom/window) — navigator


# Dom (/docs/javascript/dom)



# Dom [#dom]

JavaScript notes in **Dom**.


# Intersection Observer (/docs/javascript/dom/intersection-observer)



# Intersection Observer [#intersection-observer]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`IntersectionObserver` asynchronously reports when a target element’s visibility crosses thresholds relative to a root (viewport or element). Use it for lazy-loading, infinite scroll, ad viewability, and scroll-driven UI — without scroll event spam.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new IntersectionObserver(callback, options)`.
* **Options**: `root`, `rootMargin`, `threshold` (0–1 or array).
* **Callback**: receives `entries` and the observer; runs off the main scroll path.
* **Entry**: `isIntersecting`, `intersectionRatio`, `boundingClientRect`, `rootBounds`, `target`, `time`.
* **Control**: `observe`, `unobserve`, `disconnect`, `takeRecords`.

```js
const io = new IntersectionObserver((entries) => {
  for (const e of entries) {
    if (e.isIntersecting) load(e.target);
  }
});
io.observe(document.querySelector("img[data-src]"));
```

## 💡 Examples [#-examples]

```js
// Lazy images
const io = new IntersectionObserver(
  (entries, obs) => {
    for (const e of entries) {
      if (!e.isIntersecting) continue;
      const img = e.target;
      img.src = img.dataset.src;
      obs.unobserve(img);
    }
  },
  { rootMargin: "200px 0px", threshold: 0.01 },
);
document.querySelectorAll("img[data-src]").forEach((img) => io.observe(img));

// Infinite scroll sentinel
const sentinel = document.querySelector("#sent");
new IntersectionObserver(async ([e]) => {
  if (e.isIntersecting) await loadMore();
}).observe(sentinel);

// Multiple thresholds for progress
new IntersectionObserver(
  ([e]) => {
    bar.style.width = `${e.intersectionRatio * 100}%`;
  },
  { threshold: Array.from({ length: 21 }, (_, i) => i / 20) },
).observe(article);

// Section spy / active nav
const sections = document.querySelectorAll("section[id]");
const navIo = new IntersectionObserver(
  (entries) => {
    entries.forEach((e) => {
      const link = document.querySelector(`a[href="#${e.target.id}"]`);
      link?.classList.toggle("active", e.isIntersecting);
    });
  },
  { rootMargin: "-40% 0px -40% 0px", threshold: 0 },
);
sections.forEach((s) => navIo.observe(s));
```

## ⚠️ Pitfalls [#️-pitfalls]

* `root` must be an ancestor of the target (or `null` for viewport).
* Zero-size targets may never intersect — ensure measurable box.
* Callbacks are batched and async — not frame-perfect with scroll position.
* Always `unobserve`/`disconnect` when done to avoid leaks.
* `rootMargin` uses CSS margin syntax — percentages resolve against root size.

## 🔗 Related [#-related]

* [mutation\_observer.md](/docs/javascript/dom/mutation-observer) — DOM change watching
* [resize\_observer.md](/docs/javascript/dom/resize-observer) — size changes
* [events.md](/docs/javascript/dom/events) — scroll events alternative
* [position.md](/docs/javascript/dom/position) — geometry
* [../timers.md](/docs/javascript/timers) — rAF pairing


# MediaQueryList (/docs/javascript/dom/media-query-list)



# MediaQueryList [#mediaquerylist]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`window.matchMedia(query)` returns a `MediaQueryList` for CSS media queries in JS — responsive behavior, dark mode detection, and reduced-motion preferences. Listen with `addEventListener("change", ...)` (not deprecated `addListener` in new code).

## 🔧 Core concepts [#-core-concepts]

* **Create**: `const mql = matchMedia("(min-width: 768px)")`.
* **`mql.matches`**: boolean current state.
* **`mql.media`**: serialized query string.
* **Events**: `change` when match flips.
* **Common queries**: width, `prefers-color-scheme`, `prefers-reduced-motion`, `hover`, `pointer`, `display-mode`.
* **CSS sync**: same syntax as `@media`.

```js
const wide = matchMedia("(min-width: 900px)");
if (wide.matches) enableGrid();
wide.addEventListener("change", (e) => {
  e.matches ? enableGrid() : enableStack();
});
```

## 💡 Examples [#-examples]

```js
// Dark mode preference
const dark = matchMedia("(prefers-color-scheme: dark)");
function applyTheme() {
  document.documentElement.dataset.theme = dark.matches ? "dark" : "light";
}
applyTheme();
dark.addEventListener("change", applyTheme);

// Reduced motion
const motion = matchMedia("(prefers-reduced-motion: reduce)");
if (!motion.matches) startAnimation();

// Hover-capable devices
const canHover = matchMedia("(hover: hover) and (pointer: fine)").matches;

// PWA display mode
matchMedia("(display-mode: standalone)").matches;

// Helper
function onMedia(query, cb) {
  const mql = matchMedia(query);
  cb(mql.matches);
  const handler = (e) => cb(e.matches);
  mql.addEventListener("change", handler);
  return () => mql.removeEventListener("change", handler);
}

const stop = onMedia("(max-width: 600px)", (isMobile) => {
  nav.dataset.mode = isMobile ? "drawer" : "bar";
});
```

```js
// Older Safari used addListener/removeListener
// mql.addListener(fn); // legacy
```

## ⚠️ Pitfalls [#️-pitfalls]

* Don’t parse `window.innerWidth` for breakpoints you already express in CSS — prefer `matchMedia` for parity.
* Evaluate once at load isn’t enough for rotatable devices — listen for `change`.
* Unit differences (`em` vs `px`) follow CSS rules relative to initial viewport / font.
* `matchMedia` is sync and cheap — still avoid creating thousands of listeners.
* JS theme overrides should respect user preference unless explicitly overridden.

## 🔗 Related [#-related]

* [../CSS/media\_queries.md](/docs/javascript/../css/media-queries) — CSS `@media`
* [../CSS/dark\_mode.md](/docs/javascript/../css/dark-mode) — color schemes
* [events.md](/docs/javascript/dom/events) — change events
* [screen.md](/docs/javascript/dom/screen) — screen metrics
* [window.md](/docs/javascript/dom/window) — viewport


# Mutation Methods & Observers (/docs/javascript/dom/mutation-methods)



# Mutation Methods & Observers [#mutation-methods--observers]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

Mutate the tree with node methods (`append`, `remove`, `replaceChildren`, …) and observe changes with `MutationObserver`. Use observers for integrations and accessibility hooks — not as a substitute for app state.

## 🔧 Core concepts [#-core-concepts]

* **Child mutation**: `append`, `prepend`, `replaceChildren`, `replaceWith`, `remove`.
* **Legacy**: `appendChild`, `insertBefore`, `removeChild`, `replaceChild`.
* **`MutationObserver`**: callback with `MutationRecord[]`.
* **Observe options**: `childList`, `subtree`, `attributes`, `attributeFilter`, `characterData`.
* **Records**: `type`, `target`, `addedNodes`, `removedNodes`, `attributeName`, `oldValue`.

```js
parent.replaceChildren(...newItems);
```

## 💡 Examples [#-examples]

```js
const list = document.querySelector("#list");
list.append(li1, li2);
list.prepend(header);
old.replaceWith(fresh);
empty.remove();
list.replaceChildren(); // clear

// Observer
const obs = new MutationObserver((records) => {
  for (const r of records) {
    if (r.type === "childList") {
      r.addedNodes.forEach((n) => {
        if (n.nodeType === Node.ELEMENT_NODE) enhance(n);
      });
    }
    if (r.type === "attributes" && r.attributeName === "class") {
      syncClass(r.target);
    }
  }
});

obs.observe(list, {
  childList: true,
  subtree: true,
  attributes: true,
  attributeFilter: ["class", "aria-expanded"],
  attributeOldValue: true,
});

// Later
obs.disconnect();
```

```js
// Batch read after mutations
requestAnimationFrame(() => {
  const h = list.getBoundingClientRect().height;
});

// takeRecords drains the queue synchronously
const pending = obs.takeRecords();
for (const r of pending) handle(r);
```

## ⚠️ Pitfalls [#️-pitfalls]

* Observers are async (microtask) — don’t expect sync delivery mid-script.
* Observing `attributes: true` without `attributeFilter` is noisy.
* Mutating the DOM inside the callback can recurse — guard or disconnect temporarily.
* Live `NodeList` from `childNodes` changes as you mutate — copy first if needed.
* Prefer explicit app updates over observing your own renders.

## 🔗 Related [#-related]

* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — creating nodes
* [content\_methods.md](/docs/javascript/dom/content-methods) — content updates
* [events.md](/docs/javascript/dom/events) — user-driven changes
* [attributes.md](/docs/javascript/dom/attributes) — attribute mutations
* [selectors.md](/docs/javascript/dom/selectors) — finding roots
* [../async.md](/docs/javascript/async) — microtask timing


# Mutation Observer (/docs/javascript/dom/mutation-observer)



# Mutation Observer [#mutation-observer]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`MutationObserver` notifies you of DOM tree changes: child lists, attributes, and character data. Prefer it over deprecated mutation events. Ideal for integrating with third-party widgets, reacting to SPA renders, and building developer tools — use sparingly in hot paths.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new MutationObserver(callback)`.
* **`observe(target, options)`**: start watching.
* **Options**: `childList`, `attributes`, `characterData`, `subtree`, `attributeFilter`, `attributeOldValue`, `characterDataOldValue`.
* **Records**: `type`, `target`, `addedNodes`, `removedNodes`, `attributeName`, `oldValue`, etc.
* **`disconnect()`*&#x2A; / &#x2A;*`takeRecords()`**: stop or flush queue.
* Delivered as microtasks after mutations settle.

```js
const mo = new MutationObserver((records) => {
  for (const r of records) console.log(r.type, r.target);
});
mo.observe(document.body, { childList: true, subtree: true });
```

## 💡 Examples [#-examples]

```js
// Watch attribute changes on one element
mo.observe(el, {
  attributes: true,
  attributeFilter: ["class", "aria-expanded"],
  attributeOldValue: true,
});

// React when a node appears
function whenAdded(selector, root = document.body) {
  return new Promise((resolve) => {
    const found = root.querySelector(selector);
    if (found) return resolve(found);
    const obs = new MutationObserver(() => {
      const el = root.querySelector(selector);
      if (el) {
        obs.disconnect();
        resolve(el);
      }
    });
    obs.observe(root, { childList: true, subtree: true });
  });
}

// Sanitize added nodes
const sanitizer = new MutationObserver((records) => {
  for (const r of records) {
    r.addedNodes.forEach((node) => {
      if (node.nodeType === 1) scrub(node);
    });
  }
});
sanitizer.observe(container, { childList: true, subtree: true });

// Character data
mo.observe(textNode, { characterData: true, characterDataOldValue: true });
```

```js
// Avoid feedback loops
let applying = false;
const obs = new MutationObserver(() => {
  if (applying) return;
  applying = true;
  sync();
  applying = false;
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Observing `document` with `subtree: true` can flood callbacks — narrow the root/filter.
* Mutations you make inside the callback can re-trigger — guard with flags or disconnect temporarily.
* Does not observe computed style / resize — use ResizeObserver / IntersectionObserver.
* `attributeFilter` is ignored unless `attributes: true`.
* Memory: disconnect when components unmount.

## 🔗 Related [#-related]

* [intersection\_observer.md](/docs/javascript/dom/intersection-observer) — visibility
* [resize\_observer.md](/docs/javascript/dom/resize-observer) — size
* [mutation\_methods.md](/docs/javascript/dom/mutation-methods) — DOM mutations
* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — creating nodes
* [../event\_loop.md](/docs/javascript/event-loop) — microtask delivery


# Navigation (Location & History) (/docs/javascript/dom/navigation)



# Navigation (Location & History) [#navigation-location--history]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

`location` describes the current URL; `history` manages the session history stack. For SPAs, combine `pushState` / `replaceState` with `popstate` and the Navigation API where available.

## 🔧 Core concepts [#-core-concepts]

* **`location`**: `href`, `origin`, `pathname`, `search`, `hash`, `assign`, `replace`, `reload`.
* **`history`**: `length`, `state`, `pushState`, `replaceState`, `back`, `forward`, `go`.
* **Events**: `popstate`, `hashchange`.
* **Navigation API** (modern): `navigation.navigate()`, `navigate` event (progressive enhancement).
* **URL API**: parse `location.href` with `new URL(...)`.

```js
history.pushState({ page: 2 }, "", "/page/2");
```

## 💡 Examples [#-examples]

```js
// Read
const url = new URL(location.href);
const page = url.searchParams.get("page");

// Navigate
location.assign("/home"); // pushes history
location.replace("/login"); // no extra history entry
location.reload();

// SPA route change
function navigate(path, state = {}) {
  history.pushState(state, "", path);
  render(path, state);
}

window.addEventListener("popstate", (e) => {
  render(location.pathname, e.state);
});

// Hash routing
window.addEventListener("hashchange", () => {
  renderHash(location.hash.slice(1));
});

// Query update without full reload
function setQuery(key, value) {
  const u = new URL(location.href);
  u.searchParams.set(key, value);
  history.replaceState(history.state, "", u);
}
```

```js
// Guard unload
window.addEventListener("beforeunload", (e) => {
  if (isDirty) {
    e.preventDefault();
    e.returnValue = "";
  }
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* `pushState` does not trigger `popstate` — you must render yourself.
* Cross-origin `location` access throws — only same-origin details are readable.
* Large `history.state` objects are cloned — keep them small/serializable.
* `location.search` includes `?`; prefer `URLSearchParams`.
* `beforeunload` prompts are restricted/browser-dependent.

## 🔗 Related [#-related]

* [window.md](/docs/javascript/dom/window) — window object
* [../url.md](/docs/javascript/url) — URL / search params
* [../encode.md](/docs/javascript/encode) — encoding paths
* [events.md](/docs/javascript/dom/events) — popstate / hashchange
* [document\_methods.md](/docs/javascript/dom/document-methods) — document.URL
* [storage.md](/docs/javascript/dom/storage) — persisting UI state


# Position & Geometry (/docs/javascript/dom/position)



# Position & Geometry [#position--geometry]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

Measure layout with `getBoundingClientRect`, offset/scroll properties, and `IntersectionObserver` / `ResizeObserver`. Batch reads and writes to avoid layout thrashing.

## 🔧 Core concepts [#-core-concepts]

* **Viewport box**: `getBoundingClientRect()` → `x`, `y`, `width`, `height`, `top`, `right`, `bottom`, `left` (CSS pixels, viewport-relative).
* **Offset**: `offsetTop`, `offsetLeft`, `offsetWidth`, `offsetHeight`, `offsetParent`.
* **Client**: `clientWidth` / `clientHeight` (padding box, no scrollbar).
* **Scroll**: `scrollTop`, `scrollLeft`, `scrollWidth`, `scrollHeight`, `scrollTo`.
* **Observers**: `ResizeObserver`, `IntersectionObserver`.
* **Visual viewport**: `window.visualViewport` (mobile chrome).

```js
const r = el.getBoundingClientRect();
const visible = r.top < innerHeight && r.bottom > 0;
```

## 💡 Examples [#-examples]

```js
// Center in viewport?
function isInViewport(el) {
  const r = el.getBoundingClientRect();
  return r.top >= 0 && r.bottom <= window.innerHeight;
}

// Scroll into view
el.scrollIntoView({ behavior: "smooth", block: "nearest" });

// Document position
function pageOffset(el) {
  const r = el.getBoundingClientRect();
  return {
    top: r.top + window.scrollY,
    left: r.left + window.scrollX,
  };
}

// ResizeObserver
const ro = new ResizeObserver((entries) => {
  for (const entry of entries) {
    const { width, height } = entry.contentRect;
    chart.resize(width, height);
  }
});
ro.observe(container);

// IntersectionObserver lazy-load
const io = new IntersectionObserver(
  (entries, obs) => {
    for (const e of entries) {
      if (!e.isIntersecting) continue;
      e.target.src = e.target.dataset.src;
      obs.unobserve(e.target);
    }
  },
  { rootMargin: "100px" },
);
document.querySelectorAll("img[data-src]").forEach((img) => io.observe(img));
```

```js
// Avoid thrashing: read all, then write
const heights = items.map((el) => el.getBoundingClientRect().height);
items.forEach((el, i) => {
  el.style.minHeight = `${Math.max(...heights)}px`;
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Interleaving measure and mutate causes forced synchronous layout.
* `getBoundingClientRect` is viewport-relative — add `scrollX/Y` for document coords.
* Transforms affect bounding rects; offset props may differ.
* `offsetParent` can be `null` for fixed/hidden elements.
* Subpixel floats — round when comparing to integers.

## 🔗 Related [#-related]

* [window.md](/docs/javascript/dom/window) — scrollX / innerHeight
* [screen.md](/docs/javascript/dom/screen) — screen metrics
* [class.md](/docs/javascript/dom/class) — class-driven layout
* [events.md](/docs/javascript/dom/events) — scroll / resize
* [selectors.md](/docs/javascript/dom/selectors) — targeting elements
* [../math.md](/docs/javascript/math) — clamping / rounding


# Range & Selection (/docs/javascript/dom/range)



# Range & Selection [#range--selection]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

A `Range` represents a fragment of the document between two boundary points. `Selection` (from `window.getSelection()`) is the user highlight, often backed by one or more ranges. Used for editing, measuring text, and inserting at the caret.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `document.createRange()`, `Range` methods on selection.
* **Boundaries**: `setStart`, `setEnd`, `selectNode`, `selectNodeContents`, `collapse`.
* **Content**: `cloneContents`, `extractContents`, `deleteContents`, `insertNode`, `surroundContents`.
* **Geometry**: `getBoundingClientRect`, `getClientRects`.
* **Selection**: `getSelection()`, `addRange`, `removeAllRanges`, `collapse`, `toString()`.

```js
const range = document.createRange();
range.selectNodeContents(el);
```

## 💡 Examples [#-examples]

```js
// Select all text in an element
const sel = window.getSelection();
const range = document.createRange();
range.selectNodeContents(el);
sel.removeAllRanges();
sel.addRange(range);

// Insert at caret
function insertAtCaret(node) {
  const sel = window.getSelection();
  if (!sel.rangeCount) return;
  const range = sel.getRangeAt(0);
  range.deleteContents();
  range.insertNode(node);
  range.setStartAfter(node);
  range.collapse(true);
  sel.removeAllRanges();
  sel.addRange(range);
}

// Extract HTML fragment
const r = document.createRange();
r.setStart(startNode, startOffset);
r.setEnd(endNode, endOffset);
const frag = r.cloneContents();

// Caret coordinates (approx)
function caretRect() {
  const sel = getSelection();
  if (!sel.rangeCount) return null;
  const r = sel.getRangeAt(0).cloneRange();
  r.collapse(true);
  return r.getBoundingClientRect();
}

// Wrap selection
function boldSelection() {
  const sel = getSelection();
  if (!sel.rangeCount || sel.isCollapsed) return;
  const strong = document.createElement("strong");
  sel.getRangeAt(0).surroundContents(strong);
}
```

```js
// createContextualFragment
const html = document.createRange().createContextualFragment("<em>x</em>");
```

## ⚠️ Pitfalls [#️-pitfalls]

* `surroundContents` throws if the range partially selects non-text nodes — split carefully.
* Selection APIs differ in iframes — use the iframe’s `window.getSelection()`.
* Mutating DOM often invalidates live ranges — clone or re-create.
* Multi-range selections exist in some browsers (Firefox) — don’t assume one range.
* Measuring collapsed ranges can yield zero-size rects — insert a temporary marker if needed.

## 🔗 Related [#-related]

* [content\_methods.md](/docs/javascript/dom/content-methods) — text editing
* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — insertNode
* [events.md](/docs/javascript/dom/events) — selectionchange
* [document\_methods.md](/docs/javascript/dom/document-methods) — createRange
* [position.md](/docs/javascript/dom/position) — rects
* [window.md](/docs/javascript/dom/window) — getSelection


# Resize Observer (/docs/javascript/dom/resize-observer)



# Resize Observer [#resize-observer]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

`ResizeObserver` fires when an Element’s size changes — more precise than `window.resize` for component-level layouts, container queries polyfills, and chart reflows. Observe content box, border box, or device-pixel content box.

## 🔧 Core concepts [#-core-concepts]

* **Create**: `new ResizeObserver(callback)`.
* **`observe(el, \{ box \})`**: `content-box` (default), `border-box`, `device-pixel-content-box`.
* **Entry**: `contentRect`, `borderBoxSize`, `contentBoxSize`, `devicePixelContentBoxSize`, `target`.
* **`unobserve` / `disconnect`**: cleanup.
* Fired before paint after layout; avoid layout loops.

```js
const ro = new ResizeObserver((entries) => {
  for (const e of entries) {
    const { width, height } = e.contentRect;
    chart.resize(width, height);
  }
});
ro.observe(container);
```

## 💡 Examples [#-examples]

```js
// Prefer box sizes arrays (newer)
new ResizeObserver((entries) => {
  const e = entries[0];
  const [size] = e.contentBoxSize;
  const w = size.inlineSize;
  const h = size.blockSize;
  render(w, h);
}).observe(el, { box: "content-box" });

// Border box for total footprint
ro.observe(el, { box: "border-box" });

// Responsive component without window listener
function mount(el) {
  const ro = new ResizeObserver(([e]) => {
    el.dataset.wide = String(e.contentRect.width > 600);
  });
  ro.observe(el);
  return () => ro.disconnect();
}

// Canvas backing store
const canvas = document.querySelector("canvas");
new ResizeObserver(() => {
  const dpr = devicePixelRatio;
  const { width, height } = canvas.getBoundingClientRect();
  canvas.width = Math.round(width * dpr);
  canvas.height = Math.round(height * dpr);
  draw();
}).observe(canvas);
```

```js
// Guard infinite resize loops
let frame;
const ro = new ResizeObserver(() => {
  cancelAnimationFrame(frame);
  frame = requestAnimationFrame(update);
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing size inside the callback can cause observation loops — batch via rAF and check thresholds.
* `contentRect` is legacy-ish; prefer `contentBoxSize` / `borderBoxSize` (arrays for fragmented boxes).
* SVG / table quirks exist — verify in target browsers.
* Not a substitute for CSS container queries when pure CSS suffices.
* Disconnect on teardown.

## 🔗 Related [#-related]

* [intersection\_observer.md](/docs/javascript/dom/intersection-observer) — visibility
* [mutation\_observer.md](/docs/javascript/dom/mutation-observer) — DOM changes
* [position.md](/docs/javascript/dom/position) — measurements
* [../timers.md](/docs/javascript/timers) — rAF
* [cssom.md](/docs/javascript/dom/cssom) — computed sizes


# Screen (/docs/javascript/dom/screen)



# Screen [#screen]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

`window.screen` exposes information about the output display: pixel dimensions, color depth, and orientation. Pair with `window` viewport metrics and media queries for responsive behavior — screen size ≠ layout viewport.

## 🔧 Core concepts [#-core-concepts]

* **Size**: `screen.width`, `screen.height` (full screen).
* **Available**: `screen.availWidth`, `screen.availHeight` (minus OS chrome).
* **Color**: `colorDepth`, `pixelDepth`.
* **Orientation**: `screen.orientation.type`, `angle`, `lock()` / `unlock()` (secure contexts / UX rules).
* **Multi-screen** (experimental): `window.getScreenDetails()` where permitted.
* **Device pixels**: `window.devicePixelRatio`.

```js
console.log(screen.width, screen.height, devicePixelRatio);
```

## 💡 Examples [#-examples]

```js
// Basic readout
const info = {
  screen: `${screen.width}×${screen.height}`,
  avail: `${screen.availWidth}×${screen.availHeight}`,
  dpr: devicePixelRatio,
  orientation: screen.orientation?.type,
};

// Orientation change
screen.orientation?.addEventListener("change", () => {
  console.log(screen.orientation.type, screen.orientation.angle);
});

// Prefer CSS / matchMedia for layout
const mq = matchMedia("(orientation: portrait)");
mq.addEventListener("change", (e) => {
  document.body.classList.toggle("portrait", e.matches);
});

// Lock landscape (may require fullscreen + gesture)
async function lockLandscape() {
  try {
    await document.documentElement.requestFullscreen();
    await screen.orientation.lock("landscape");
  } catch (err) {
    console.warn("orientation lock failed", err);
  }
}

// Canvas backing store
canvas.width = Math.floor(cssWidth * devicePixelRatio);
canvas.height = Math.floor(cssHeight * devicePixelRatio);
ctx.setTransform(devicePixelRatio, 0, 0, devicePixelRatio, 0, 0);
```

```js
// Don’t use screen.width for responsive layout — use viewport
const layoutWidth = document.documentElement.clientWidth;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `screen.width` is not the browser viewport — use `innerWidth` / `clientWidth` for layout.
* Orientation lock is heavily gated and often fails outside fullscreen/PWA.
* Extended screen APIs need permission and are not universal.
* Browser zoom affects CSS pixels vs device pixels — test with DPR ≠ 1.
* Values can change when moving windows across monitors.

## 🔗 Related [#-related]

* [window.md](/docs/javascript/dom/window) — viewport metrics
* [position.md](/docs/javascript/dom/position) — element geometry
* [events.md](/docs/javascript/dom/events) — resize / orientation
* [navigation.md](/docs/javascript/dom/navigation) — fullscreen flows
* [../math.md](/docs/javascript/math) — rounding DPR sizes
* [../api.md](/docs/javascript/api) — media / display APIs


# Selectors (/docs/javascript/dom/selectors)



# Selectors [#selectors]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

Find nodes with CSS selectors via `querySelector` / `querySelectorAll`, or with id/class/tag helpers. Use `matches` and `closest` for event delegation. Escape dynamic values with `CSS.escape`.

## 🔧 Core concepts [#-core-concepts]

* **Single**: `parent.querySelector(sel)` → first match or `null`.
* **All**: `querySelectorAll` → static `NodeList`.
* **Id**: `getElementById` (document only) — fastest for ids.
* **Live collections**: `getElementsByClassName`, `getElementsByTagName`, `getElementsByName`.
* **Test**: `el.matches(sel)`, `el.closest(sel)`.
* **Scope**: query relative to any `Element` / `Document` / `DocumentFragment`.

```js
const item = document.querySelector(".list > li.active");
const items = document.querySelectorAll("[data-id]");
```

## 💡 Examples [#-examples]

```js
const root = document.querySelector("#app");
const btn = root.querySelector("button[type='submit']");
const rows = root.querySelectorAll("tbody tr");

// Convert to array
const arr = [...rows];

// Delegation helpers
list.addEventListener("click", (e) => {
  const row = e.target.closest("tr[data-id]");
  if (!row || !list.contains(row)) return;
  if (e.target.matches("button.delete")) {
    row.remove();
  }
});

// Dynamic id/class
const id = "section.1";
document.querySelector(`#${CSS.escape(id)}`);

// Attribute selectors
document.querySelectorAll('input[name="tags"]:checked');
document.querySelectorAll("a[href^='https://']");

// :scope in modern engines
root.querySelectorAll(":scope > .child");
```

```js
// Prefer getElementById for plain ids
document.getElementById("app");

// Live vs static
const live = document.getElementsByClassName("item");
const staticList = document.querySelectorAll(".item");
const extra = document.createElement("div");
extra.className = "item";
document.body.append(extra);
console.log(live.length, staticList.length); // live grew; static did not
```

## ⚠️ Pitfalls [#️-pitfalls]

* Invalid selectors throw `DOMException` — escape user input.
* `querySelectorAll` is a snapshot; live HTMLCollections update as the DOM changes.
* `closest` goes upward including itself — check `matches` when you need only ancestors.
* Descendant queries from a detached tree only search that subtree.
* Over-specific selectors are brittle — prefer stable `data-*` hooks.

## 🔗 Related [#-related]

* [document\_methods.md](/docs/javascript/dom/document-methods) — document queries
* [events.md](/docs/javascript/dom/events) — delegation
* [attributes.md](/docs/javascript/dom/attributes) — data attributes
* [class.md](/docs/javascript/dom/class) — class tokens
* [create\_add\_remove.md](/docs/javascript/dom/create-add-remove) — building trees
* [../strings.md](/docs/javascript/strings) — building selector strings


# Shadow DOM (/docs/javascript/dom/shadow-dom)



# Shadow DOM [#shadow-dom]

*JavaScript DOM · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Shadow DOM attaches an encapsulated DOM tree to an element. Styles and nodes inside the shadow root stay mostly isolated from the page, enabling component CSS without global leaks. Open mode exposes `shadowRoot`; closed hides it.

## 🔧 Core concepts [#-core-concepts]

* **Attach**: `el.attachShadow(\{ mode: "open" | "closed", delegatesFocus?, slotAssignment? \})`.
* **Tree**: `shadowRoot` hosts markup; light DOM children may project via `<slot>`.
* **Style**: shadow styles don’t apply outside (mostly); page styles don’t pierce in (except inheritance of some properties / `::part` / CSS variables).
* **Events**: retargeted so `event.target` appears as the host from outside.
* **Parts**: `part="name"` + `::part(name)` from outside.
* **Slots**: default and named (`<slot name="title">`).

```js
const root = host.attachShadow({ mode: "open" });
root.innerHTML = `
  <style>:host { display: block; }</style>
  <slot></slot>
`;
```

## 💡 Examples [#-examples]

```js
class Card extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" }).innerHTML = `
      <style>
        :host { display: block; border: 1px solid #ccc; }
        ::slotted(h2) { margin: 0; }
        button { color: var(--accent, blue); }
      </style>
      <slot name="title"></slot>
      <div class="body"><slot></slot></div>
      <button part="action">OK</button>
    `;
  }
}
customElements.define("x-card", Card);

// Light DOM usage
// <x-card><h2 slot="title">Hi</h2><p>Body</p></x-card>

// Outside styling via parts
// x-card::part(action) { font-weight: bold; }

// Manual slot assignment (imperative)
const shadow = host.attachShadow({
  mode: "open",
  slotAssignment: "manual",
});
const slot = shadow.querySelector("slot");
slot.assign(nodeA, nodeB);

// Query inside
host.shadowRoot.querySelector("button");
```

```js
// CSS variables pierce shadow
// :root { --accent: tomato; }
```

## ⚠️ Pitfalls [#️-pitfalls]

* Closed mode is not a security boundary — don’t store secrets there.
* `document.querySelector` won’t see shadow internals — pierce with `shadowRoot`.
* Form-associated custom elements need Extra APIs for native form participation.
* Slotted content stays in light DOM — styles with `::slotted` are limited.
* Duplicate `attachShadow` throws — only one shadow root per host.

## 🔗 Related [#-related]

* [custom\_elements.md](/docs/javascript/dom/custom-elements) — defining elements
* [../Html/template\_slot.md](/docs/javascript/../html/template-slot) — slot HTML
* [../Html/web\_components.md](/docs/javascript/../html/web-components) — stack overview
* [selectors.md](/docs/javascript/dom/selectors) — piercing limits
* [events.md](/docs/javascript/dom/events) — retargeting


# Web Storage (/docs/javascript/dom/storage)



# Web Storage [#web-storage]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

`localStorage` and `sessionStorage` provide synchronous key/value string storage per origin. Use them for small preferences — not for large datasets or secrets. Prefer IndexedDB for structured/offline data.

## 🔧 Core concepts [#-core-concepts]

* **`localStorage`**: persists across sessions until cleared.
* **`sessionStorage`**: per-tab session; survives reload, not new tabs (usually).
* **API**: `getItem`, `setItem`, `removeItem`, `clear`, `key(i)`, `length`.
* **Quota**: throws `QuotaExceededError` when full.
* **Events**: `storage` fires in *other* documents of the same origin on `localStorage` changes.
* **Only strings**: JSON-encode objects.

```js
localStorage.setItem("theme", "dark");
const theme = localStorage.getItem("theme");
```

## 💡 Examples [#-examples]

```js
const storage = {
  get(key, fallback = null) {
    try {
      const raw = localStorage.getItem(key);
      return raw == null ? fallback : JSON.parse(raw);
    } catch {
      return fallback;
    }
  },
  set(key, value) {
    localStorage.setItem(key, JSON.stringify(value));
  },
  remove(key) {
    localStorage.removeItem(key);
  },
};

storage.set("user", { id: 1, name: "Ada" });
const user = storage.get("user", {});

// Cross-tab sync
window.addEventListener("storage", (e) => {
  if (e.key === "theme") {
    applyTheme(e.newValue);
  }
});

// sessionStorage wizard draft
sessionStorage.setItem("draft", JSON.stringify(formState));

// Enumerate
for (let i = 0; i < localStorage.length; i++) {
  const k = localStorage.key(i);
  console.log(k, localStorage.getItem(k));
}
```

```js
try {
  localStorage.setItem("cache", bigString);
} catch (err) {
  if (err.name === "QuotaExceededError") {
    localStorage.removeItem("cache");
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Synchronous and blocking — avoid huge reads/writes on the main thread.
* Never store tokens/passwords in accessible storage without a clear threat model.
* Private mode / blocked storage can throw on access — wrap in try/catch.
* `storage` event does not fire in the writer’s document.
* Values are strings — forgetting `JSON.parse` yields subtle bugs.

## 🔗 Related [#-related]

* [window.md](/docs/javascript/dom/window) — window\.localStorage
* [events.md](/docs/javascript/dom/events) — storage event
* [../json.md](/docs/javascript/json) — serialize values
* [../error.md](/docs/javascript/error) — quota errors
* [navigation.md](/docs/javascript/dom/navigation) — session lifecycle
* [../objects.md](/docs/javascript/objects) — plain data shapes


# Window (/docs/javascript/dom/window)



# Window [#window]

*JavaScript DOM · Reference cheat sheet*

## 📋 Overview [#-overview]

`window` is the global object in browsers (`globalThis === window`). It exposes the viewport, timers, framing, storage entry points, and dialogs. Prefer feature-specific APIs (`document`, `location`, `fetch`) over legacy window methods when both exist.

## 🔧 Core concepts [#-core-concepts]

* **Global**: undeclared `var` / browser globals hang off `window`; modules don’t create globals.
* **Viewport**: `innerWidth`, `innerHeight`, `outerWidth`, `scrollX`, `scrollY`, `devicePixelRatio`.
* **Frames**: `parent`, `top`, `frames`, `frameElement`.
* **Timers**: `setTimeout`, `setInterval`, `requestAnimationFrame`, `requestIdleCallback`.
* **Dialogs**: `alert`, `confirm`, `prompt` (blocking — avoid in modern UX).
* **Open**: `window.open`, `close`, `focus` (popup rules apply).

```js
requestAnimationFrame(draw);
window.addEventListener("resize", onResize);
```

## 💡 Examples [#-examples]

```js
// Scroll helpers
window.scrollTo({ top: 0, behavior: "smooth" });
const y = window.scrollY;

// rAF loop
let raf;
function loop(t) {
  update(t);
  raf = requestAnimationFrame(loop);
}
raf = requestAnimationFrame(loop);
cancelAnimationFrame(raf);

// Match media
const dark = window.matchMedia("(prefers-color-scheme: dark)");
dark.addEventListener("change", (e) => {
  document.documentElement.dataset.theme = e.matches ? "dark" : "light";
});

// postMessage (cross-window)
otherWindow.postMessage({ type: "ping" }, "https://trusted.example");
window.addEventListener("message", (e) => {
  if (e.origin !== "https://trusted.example") return;
  console.log(e.data);
});

// Safe external open
const w = window.open("https://example.com", "_blank", "noopener,noreferrer");
```

```js
// globalThis for portable code
const g = globalThis;
g.addEventListener?.("offline", () => showBanner());

// Idle work when browser is quiet
requestIdleCallback?.((deadline) => {
  while (deadline.timeRemaining() > 0 && jobs.length) {
    jobs.shift()();
  }
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Popup blockers require `window.open` in direct user-gesture handlers.
* Always verify `event.origin` on `message` events.
* `innerWidth` includes scrollbars differently across engines — test layout.
* Blocking dialogs freeze the main thread and are suppressed in many contexts.
* In workers there is no `window` — use `self` / `globalThis`.

## 🔗 Related [#-related]

* [document\_methods.md](/docs/javascript/dom/document-methods) — document
* [navigation.md](/docs/javascript/dom/navigation) — location / history
* [screen.md](/docs/javascript/dom/screen) — screen metrics
* [position.md](/docs/javascript/dom/position) — scroll & geometry
* [events.md](/docs/javascript/dom/events) — window events
* [storage.md](/docs/javascript/dom/storage) — localStorage
* [../api.md](/docs/javascript/api) — timers & fetch globals
* [../fetch.md](/docs/javascript/fetch) — networking


# Export CSV Report (/docs/powershell/examples/export-csv-report)



# Export CSV Report [#export-csv-report]

*Powershell · Example / how-to*

***

## 📋 Overview [#-overview]

Query objects, project columns, and export a CSV report with `Export-Csv` and UTF-8 encoding.

## 🔧 Core concepts [#-core-concepts]

| Piece                | Role                            |
| -------------------- | ------------------------------- |
| `Select-Object`      | Choose / rename columns         |
| `Export-Csv`         | Write spreadsheet-friendly file |
| `-NoTypeInformation` | Cleaner CSV header              |
| Pipeline             | Compose filters                 |

## 💡 Examples [#-examples]

**export\_csv\_report.ps1:**

```powershell
param(
    [string]$OutFile = ".\report.csv",
    [int]$Top = 50
)

$ErrorActionPreference = "Stop"

$rows = Get-ChildItem -Path $PSScriptRoot -File -Recurse -ErrorAction SilentlyContinue |
    Where-Object { $_.Extension -in ".md", ".ps1", ".ts", ".py" } |
    Sort-Object Length -Descending |
    Select-Object -First $Top @{
        Name = "RelativePath"
        Expression = { $_.FullName.Substring($PSScriptRoot.Length).TrimStart("\") }
    }, Length, LastWriteTime, Extension

$rows | Export-Csv -Path $OutFile -NoTypeInformation -Encoding utf8

Write-Host "Wrote $($rows.Count) rows to $OutFile"
```

**From process list:**

```powershell
Get-Process |
  Select-Object Name, Id, CPU, WorkingSet |
  Export-Csv .\processes.csv -NoTypeInformation -Encoding utf8
```

## ⚠️ Pitfalls [#️-pitfalls]

* Default encoding can confuse Excel — prefer `-Encoding utf8`.
* Nested objects become strings poorly — flatten with calculated properties.
* `Export-Csv` overwrites by default; confirm the path in scripts.

## 🔗 Related [#-related]

* [REST get JSON](/docs/powershell/examples/rest-get-json)
* [Watch folder](/docs/powershell/examples/watch-folder)


# Examples (/docs/powershell/examples)



# Examples [#examples]

PowerShell notes in **Examples**.


# REST Get JSON (/docs/powershell/examples/rest-get-json)



# REST Get JSON [#rest-get-json]

*Powershell · Example / how-to*

***

## 📋 Overview [#-overview]

Call a JSON REST API with `Invoke-RestMethod`, handle errors, and select fields from the response.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                     |
| ------------------- | ------------------------ |
| `Invoke-RestMethod` | Parse JSON automatically |
| Headers             | Accept / auth            |
| try/catch           | Surface HTTP errors      |
| Pipeline select     | Shape output             |

## 💡 Examples [#-examples]

**rest\_get\_json.ps1:**

```powershell
param(
    [string]$UserId = "1"
)

$ErrorActionPreference = "Stop"
$url = "https://jsonplaceholder.typicode.com/users/$UserId"

try {
    $user = Invoke-RestMethod -Uri $url -Method Get -Headers @{
        Accept = "application/json"
    }
} catch {
    Write-Error "Request failed: $($_.Exception.Message)"
    exit 1
}

[pscustomobject]@{
    Id    = $user.id
    Name  = $user.name
    Email = $user.email
    City  = $user.address.city
} | Format-List
```

**With token:**

```powershell
$token = $env:API_TOKEN
Invoke-RestMethod -Uri "https://api.example.com/v1/items" -Headers @{
    Authorization = "Bearer $token"
    Accept        = "application/json"
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Secrets in scripts should come from env vars / secret stores, not literals.
* `Invoke-WebRequest` returns raw response; prefer `Invoke-RestMethod` for JSON.
* TLS / proxy issues often need `[Net.ServicePointManager]` only as a last resort.

## 🔗 Related [#-related]

* [Export CSV report](/docs/powershell/examples/export-csv-report)
* [Watch folder](/docs/powershell/examples/watch-folder)


# Watch Folder (/docs/powershell/examples/watch-folder)



# Watch Folder [#watch-folder]

*Powershell · Example / how-to*

***

## 📋 Overview [#-overview]

Watch a directory for created/changed files using `FileSystemWatcher` and run a handler for each event.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                         |
| ---------------------- | ---------------------------- |
| `FileSystemWatcher`    | OS file change events        |
| `Register-ObjectEvent` | Subscribe in PowerShell      |
| Filter                 | Limit to extensions          |
| Debounce mindset       | Editors may fire many events |

## 💡 Examples [#-examples]

**watch\_folder.ps1:**

```powershell
param(
    [string]$Path = ".\inbox",
    [string]$Filter = "*.*"
)

$ErrorActionPreference = "Stop"
New-Item -ItemType Directory -Force -Path $Path | Out-Null

$watcher = New-Object System.IO.FileSystemWatcher
$watcher.Path = (Resolve-Path $Path)
$watcher.Filter = $Filter
$watcher.IncludeSubdirectories = $false
$watcher.EnableRaisingEvents = $true

$action = {
    $name = $Event.SourceEventArgs.Name
    $change = $Event.SourceEventArgs.ChangeType
    $time = Get-Date -Format o
    Write-Host "[$time] $change :: $name"
}

$handlers = @(
    Register-ObjectEvent $watcher Created -Action $action
    Register-ObjectEvent $watcher Changed -Action $action
    Register-ObjectEvent $watcher Renamed -Action $action
)

Write-Host "Watching $($watcher.Path) (Ctrl+C to stop)"
try {
    while ($true) { Start-Sleep -Seconds 1 }
} finally {
    $handlers | ForEach-Object { Unregister-Event -SourceIdentifier $_.Name -ErrorAction SilentlyContinue }
    $watcher.EnableRaisingEvents = $false
    $watcher.Dispose()
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Some apps write via temp+rename — listen for `Renamed`/`Created`, not only `Changed`.
* Event storms: debounce in the action if you kick off heavy work.
* Always unregister events / dispose the watcher on exit.

## 🔗 Related [#-related]

* [Export CSV report](/docs/powershell/examples/export-csv-report)
* [REST get JSON](/docs/powershell/examples/rest-get-json)


# API Mock (/docs/playwright/examples/api-mock)



# API Mock [#api-mock]

*Playwright · Example / how-to*

***

## 📋 Overview [#-overview]

Intercept network calls with `page.route` so UI tests stay fast and deterministic without hitting a real backend.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role              |
| --------------- | ----------------- |
| `page.route`    | Match URL pattern |
| `route.fulfill` | Return stub JSON  |
| `route.abort`   | Simulate failures |
| Test isolation  | Mock per test     |

## 💡 Examples [#-examples]

**api\_mock.spec.ts:**

```typescript
import { test, expect } from "@playwright/test";

test("renders posts from mocked API", async ({ page }) => {
  await page.route("**/api/posts", async (route) => {
    await route.fulfill({
      status: 200,
      contentType: "application/json",
      body: JSON.stringify([
        { id: 1, title: "Hello" },
        { id: 2, title: "World" },
      ]),
    });
  });

  await page.goto("/posts");
  await expect(page.getByText("Hello")).toBeVisible();
  await expect(page.getByText("World")).toBeVisible();
});

test("shows error when API fails", async ({ page }) => {
  await page.route("**/api/posts", (route) =>
    route.fulfill({
      status: 500,
      contentType: "application/json",
      body: JSON.stringify({ error: "boom" }),
    }),
  );

  await page.goto("/posts");
  await expect(page.getByRole("alert")).toContainText(/failed|error/i);
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Over-broad globs can mock unrelated requests — tighten the pattern.
* Forgetting `await route.fulfill` leaves the request hanging.
* Keep fixtures small; large snapshots are hard to maintain.

## 🔗 Related [#-related]

* [Login flow](/docs/playwright/examples/login-flow)


# Examples (/docs/playwright/examples)



# Examples [#examples]

Playwright notes in **Examples**.


# Login Flow (/docs/playwright/examples/login-flow)



# Login Flow [#login-flow]

*Playwright · Example / how-to*

***

## 📋 Overview [#-overview]

Automate a login form with Playwright: fill credentials, submit, and assert a post-login URL or UI marker.

## 🔧 Core concepts [#-core-concepts]

| Piece            | Role                       |
| ---------------- | -------------------------- |
| `page.goto`      | Open login page            |
| Locators         | Role/label-based selectors |
| `fill` / `click` | Interact                   |
| Assertions       | `expect` URL or text       |

## 💡 Examples [#-examples]

**login\_flow\.spec.ts:**

```typescript
import { test, expect } from "@playwright/test";

test("user can sign in", async ({ page }) => {
  await page.goto("/login");

  await page.getByLabel("Email").fill("ada@example.com");
  await page.getByLabel("Password").fill("correct-horse-battery");
  await page.getByRole("button", { name: "Sign in" }).click();

  await expect(page).toHaveURL(/\/dashboard$/);
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
});

test("shows error on bad password", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill("ada@example.com");
  await page.getByLabel("Password").fill("wrong");
  await page.getByRole("button", { name: "Sign in" }).click();

  await expect(page.getByRole("alert")).toContainText(/invalid/i);
  await expect(page).toHaveURL(/\/login/);
});
```

**Reuse auth via storage state (sketch):**

```typescript
await page.context().storageState({ path: "playwright/.auth/user.json" });
```

## ⚠️ Pitfalls [#️-pitfalls]

* Prefer `getByRole` / `getByLabel` over brittle CSS selectors.
* Hard waits (`waitForTimeout`) flake — assert on conditions instead.
* Never commit real passwords; use env vars or test-only accounts.

## 🔗 Related [#-related]

* [API mock](/docs/playwright/examples/api-mock)


# Examples (/docs/pytest/examples)



# Examples [#examples]

Pytest notes in **Examples**.


# Parametrize IDs (/docs/pytest/examples/parametrize-ids)



# Parametrize IDs [#parametrize-ids]

*Pytest · Example / how-to*

***

## 📋 Overview [#-overview]

Use `@pytest.mark.parametrize` with explicit `ids=` so failure output names cases clearly.

## 🔧 Core concepts [#-core-concepts]

| Piece          | Role                      |
| -------------- | ------------------------- |
| `parametrize`  | Run one test many ways    |
| `ids`          | Human-readable case names |
| `pytest.param` | Per-case marks / id       |
| Failure output | Shows id in nodeid        |

## 💡 Examples [#-examples]

**test\_parametrize\_ids.py:**

```python
import pytest


@pytest.mark.parametrize(
    ("raw", "expected"),
    [
        ("  ada  ", "ada"),
        ("ADA", "ada"),
        ("", ""),
    ],
    ids=["trim", "lower", "empty"],
)
def test_normalize(raw: str, expected: str) -> None:
    assert raw.strip().lower() == expected


@pytest.mark.parametrize(
    "value",
    [
        pytest.param(2, id="even"),
        pytest.param(3, id="odd"),
        pytest.param(-1, id="negative", marks=pytest.mark.xfail(reason="not yet")),
    ],
)
def test_is_non_negative_even(value: int) -> None:
    assert value >= 0 and value % 2 == 0
```

**Run:**

```shellscript
pytest -q test_parametrize_ids.py
pytest -q test_parametrize_ids.py -k trim
```

## ⚠️ Pitfalls [#️-pitfalls]

* Auto ids from values can be ugly or collide — set `ids` for clarity.
* Too many combinations explode runtime — prefer focused tables.
* Marks on `pytest.param` apply only to that case, not the whole matrix.

## 🔗 Related [#-related]

* [tmp\_path files](/docs/pytest/examples/tmp-path-files)


# tmp_path Files (/docs/pytest/examples/tmp-path-files)



# tmp\_path Files [#tmp_path-files]

*Pytest · Example / how-to*

***

## 📋 Overview [#-overview]

Use the `tmp_path` fixture to create isolated files/directories per test without polluting the repo.

## 🔧 Core concepts [#-core-concepts]

| Piece              | Role                           |
| ------------------ | ------------------------------ |
| `tmp_path`         | Unique `pathlib.Path` per test |
| Write / read       | Exercise file IO safely        |
| Cleanup            | Pytest removes the dir         |
| `tmp_path_factory` | Session-scoped temps           |

## 💡 Examples [#-examples]

**test\_tmp\_path\_files.py:**

```python
from pathlib import Path


def test_write_and_read_config(tmp_path: Path) -> None:
    config = tmp_path / "config.ini"
    config.write_text("[app]\ndebug = true\n", encoding="utf-8")

    text = config.read_text(encoding="utf-8")
    assert "debug = true" in text


def test_nested_layout(tmp_path: Path) -> None:
    inbox = tmp_path / "inbox"
    inbox.mkdir()
    sample = inbox / "note.md"
    sample.write_text("# hi\n", encoding="utf-8")

    files = sorted(p.name for p in inbox.iterdir())
    assert files == ["note.md"]


def test_factory_shared_seed(tmp_path_factory) -> None:
    root = tmp_path_factory.mktemp("seed")
    (root / "data.csv").write_text("a,b\n1,2\n", encoding="utf-8")
    assert (root / "data.csv").exists()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Do not hard-code `/tmp/...` paths — use the fixture for isolation.
* Binary vs text: pass `encoding` for text; use `write_bytes` for binaries.
* Tests must not assume leftover files from a previous run.

## 🔗 Related [#-related]

* [Parametrize ids](/docs/pytest/examples/parametrize-ids)


# Controlled Input (/docs/react/examples/controlled-input)



# Controlled Input [#controlled-input]

*React · Example / how-to*

***

## 📋 Overview [#-overview]

Keep an input’s value in React state (controlled component) so validation and submit logic stay in sync with the UI.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                     |
| ---------------------- | ------------------------ |
| Controlled value       | `value` + `onChange`     |
| Single source of truth | State owns the string    |
| Validation             | Derive errors from state |
| Submit handler         | Read state, not DOM      |

## 💡 Examples [#-examples]

**ControlledInput.tsx:**

```tsx
import { FormEvent, useState } from "react";

export function NameForm({ onSave }: { onSave: (name: string) => void }) {
  const [name, setName] = useState("");
  const error = name.trim().length === 0 ? "Name is required" : null;

  function handleSubmit(event: FormEvent) {
    event.preventDefault();
    if (error) return;
    onSave(name.trim());
    setName("");
  }

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="name">Name</label>
      <input
        id="name"
        value={name}
        onChange={(e) => setName(e.target.value)}
        aria-invalid={Boolean(error)}
        aria-describedby={error ? "name-error" : undefined}
      />
      {error ? (
        <p id="name-error" role="alert">
          {error}
        </p>
      ) : null}
      <button type="submit" disabled={Boolean(error)}>
        Save
      </button>
    </form>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing `defaultValue` and `value` makes the input semi-controlled — pick one.
* For checkboxes use `checked`, not `value`, as the controlled prop.
* Resetting after submit should set state to `""`, not touch the DOM.

## 🔗 Related [#-related]

* [Counter](/docs/react/examples/counter)
* [Fetch list](/docs/react/examples/fetch-list)


# Counter (/docs/react/examples/counter)



# Counter [#counter]

*React · Example / how-to*

***

## 📋 Overview [#-overview]

A minimal counter with `useState`: increment, decrement, and reset in a single component.

## 🔧 Core concepts [#-core-concepts]

| Piece              | Role                   |
| ------------------ | ---------------------- |
| `useState`         | Local numeric state    |
| Event handlers     | Update on click        |
| Functional updates | `setCount(c => c + 1)` |
| Derived UI         | Render current value   |

## 💡 Examples [#-examples]

**Counter.tsx:**

```tsx
import { useState } from "react";

export function Counter({ initial = 0 }: { initial?: number }) {
  const [count, setCount] = useState(initial);

  return (
    <div>
      <p aria-live="polite">Count: {count}</p>
      <button type="button" onClick={() => setCount((c) => c - 1)}>
        −
      </button>
      <button type="button" onClick={() => setCount(initial)}>
        Reset
      </button>
      <button type="button" onClick={() => setCount((c) => c + 1)}>
        +
      </button>
    </div>
  );
}
```

**Usage:**

```tsx
import { Counter } from "./Counter";

export default function App() {
  return <Counter initial={0} />;
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `setCount(count + 1)` in rapid clicks can stale — prefer functional updates.
* Do not store derived values in state if they can be computed from `count`.
* Keys on lists of counters must be stable if you mount many instances.

## 🔗 Related [#-related]

* [Controlled input](/docs/react/examples/controlled-input)
* [Theme context](/docs/react/examples/theme-context)


# Fetch List (/docs/react/examples/fetch-list)



# Fetch List [#fetch-list]

*React · Example / how-to*

***

## 📋 Overview [#-overview]

Load a remote list in `useEffect`, track loading/error/data states, and cancel in-flight requests on unmount.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                   |
| ---------------------- | ---------------------- |
| `useEffect`            | Trigger fetch on mount |
| Loading / error / data | Explicit UI states     |
| `AbortController`      | Cancel on cleanup      |
| Keys                   | Stable list rendering  |

## 💡 Examples [#-examples]

**FetchList.tsx:**

```tsx
import { useEffect, useState } from "react";

type Post = { id: number; title: string };

export function FetchList() {
  const [posts, setPosts] = useState<Post[] | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const controller = new AbortController();

    async function load() {
      setLoading(true);
      setError(null);
      try {
        const res = await fetch(
          "https://jsonplaceholder.typicode.com/posts?_limit=5",
          { signal: controller.signal },
        );
        if (!res.ok) throw new Error(`HTTP ${res.status}`);
        const data = (await res.json()) as Post[];
        setPosts(data);
      } catch (err) {
        if ((err as Error).name === "AbortError") return;
        setError((err as Error).message);
      } finally {
        if (!controller.signal.aborted) setLoading(false);
      }
    }

    void load();
    return () => controller.abort();
  }, []);

  if (loading) return <p>Loading…</p>;
  if (error) return <p role="alert">Error: {error}</p>;
  if (!posts?.length) return <p>No posts</p>;

  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Setting state after unmount without abort causes warnings/races.
* Empty dependency arrays only run once — add deps when the URL depends on props.
* Do not use array index as `key` if the list can reorder.

## 🔗 Related [#-related]

* [Controlled input](/docs/react/examples/controlled-input)
* [Theme context](/docs/react/examples/theme-context)


# Examples (/docs/react/examples)



# Examples [#examples]

React notes in **Examples**.


# Theme Context (/docs/react/examples/theme-context)



# Theme Context [#theme-context]

*React · Example / how-to*

***

## 📋 Overview [#-overview]

Share light/dark theme across the tree with `createContext`, a provider, and a small `useTheme` hook.

## 🔧 Core concepts [#-core-concepts]

| Piece        | Role                   |
| ------------ | ---------------------- |
| Context      | Avoid prop drilling    |
| Provider     | Own theme state        |
| Custom hook  | Enforce provider usage |
| `data-theme` | Drive CSS variables    |

## 💡 Examples [#-examples]

**theme\_context.tsx:**

```tsx
import {
  createContext,
  useContext,
  useEffect,
  useState,
  type ReactNode,
} from "react";

type Theme = "light" | "dark";

type ThemeContextValue = {
  theme: Theme;
  toggle: () => void;
};

const ThemeContext = createContext<ThemeContextValue | null>(null);

export function ThemeProvider({ children }: { children: ReactNode }) {
  const [theme, setTheme] = useState<Theme>("light");

  useEffect(() => {
    document.documentElement.dataset.theme = theme;
  }, [theme]);

  const value: ThemeContextValue = {
    theme,
    toggle: () => setTheme((t) => (t === "light" ? "dark" : "light")),
  };

  return (
    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
  );
}

export function useTheme() {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error("useTheme must be used within ThemeProvider");
  return ctx;
}

export function ThemeToggle() {
  const { theme, toggle } = useTheme();
  return (
    <button type="button" onClick={toggle}>
      Theme: {theme}
    </button>
  );
}
```

**App wiring:**

```tsx
import { ThemeProvider, ThemeToggle } from "./theme_context";

export default function App() {
  return (
    <ThemeProvider>
      <ThemeToggle />
    </ThemeProvider>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Creating context value inline without memo can re-render broadly — fine for tiny apps; split if hot.
* Reading context outside the provider should throw a clear error.
* Persist theme separately (e.g. localStorage) if you need reload survival.

## 🔗 Related [#-related]

* [Counter](/docs/react/examples/counter)
* [Fetch list](/docs/react/examples/fetch-list)


# CLI Tool (/docs/python/examples/cli-tool)



# CLI Tool [#cli-tool]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Build a small command-line tool with `argparse`, structured logging, and an entrypoint under `if __name__ == "__main__"`. Package it later with a console script in `pyproject.toml`.

## 🔧 Core concepts [#-core-concepts]

| Piece      | Role                     |
| ---------- | ------------------------ |
| Parser     | Flags, args, subcommands |
| Exit codes | `0` ok, non-zero failure |
| Logging    | `-v` / `-q` adjust level |
| `Path`     | File arguments           |
| `main()`   | Testable entry           |

Keep business logic in functions; CLI layer only parses and prints.

## 💡 Examples [#-examples]

**greet.py:**

```python
from __future__ import annotations

import argparse
import logging
import sys
from pathlib import Path

log = logging.getLogger("greet")

def greet(name: str, shout: bool = False) -> str:
    msg = f"Hello, {name}!"
    return msg.upper() if shout else msg

def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(description="Greet someone")
    p.add_argument("name", help="person to greet")
    p.add_argument("-s", "--shout", action="store_true")
    p.add_argument("-o", "--output", type=Path)
    p.add_argument("-v", "--verbose", action="count", default=0)
    return p

def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    level = logging.WARNING - (10 * min(args.verbose, 2))
    logging.basicConfig(level=level, format="%(levelname)s %(message)s")

    message = greet(args.name, shout=args.shout)
    log.info("writing greeting")
    if args.output:
        args.output.write_text(message + "\n", encoding="utf-8")
    else:
        print(message)
    return 0

if __name__ == "__main__":
    sys.exit(main())
```

**Usage:**

```shellscript
python greet.py Ada
python greet.py Ada --shout -v -o out.txt
```

**Test main without subprocess:**

```python
def test_main_stdout(capsys):
    assert main(["Ada"]) == 0
    assert "Hello, Ada!" in capsys.readouterr().out
```

## ⚠️ Pitfalls [#️-pitfalls]

* Parsing at import time breaks tests and packaging.
* Printing errors to stdout — use stderr + non-zero exit.
* Relative paths depend on cwd — document or resolve carefully.
* Catching all exceptions without logging hides failures.
* For richer CLIs, consider Typer/Click once argparse gets painful.

## 🔗 Related [#-related]

* [Pytest example](/docs/python/examples/pytest-example)
* [HTTP requests](/docs/python/examples/http-requests)
* [../argparse.md](/docs/python/argparse)
* [../logging.md](/docs/python/logging)
* [../pathlib.md](/docs/python/pathlib)
* [../packaging.md](/docs/python/packaging)


# Convert files (/docs/python/examples/convert-files)



# Convert files [#convert-files]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Convert between common text/data formats (CSV ↔ JSON, encoding changes, line endings) with the standard library. Keep conversions streaming when files are large; always specify encodings explicitly on Windows.

## 🔧 Core concepts [#-core-concepts]

| Task           | Tools                                                  |
| -------------- | ------------------------------------------------------ |
| CSV ↔ JSON     | `csv`, `json`                                          |
| Encoding       | `open(..., encoding=...)`, `pathlib.Path.read_text`    |
| Paths          | `pathlib.Path`                                         |
| Binary vs text | Use text mode for CSV/JSON; binary for images/archives |
| Streaming      | Iterate rows instead of `read()` whole file            |

## 💡 Examples [#-examples]

**CSV to JSON:**

```python
import csv
import json
from pathlib import Path

def csv_to_json(src: Path, dest: Path) -> None:
    with src.open(newline="", encoding="utf-8") as f:
        rows = list(csv.DictReader(f))
    dest.write_text(json.dumps(rows, indent=2, ensure_ascii=False), encoding="utf-8")

if __name__ == "__main__":
    csv_to_json(Path("users.csv"), Path("users.json"))
```

**JSON to CSV:**

```python
import csv
import json
from pathlib import Path

def json_to_csv(src: Path, dest: Path) -> None:
    rows = json.loads(src.read_text(encoding="utf-8"))
    if not rows:
        dest.write_text("", encoding="utf-8")
        return
    fieldnames = list(rows[0].keys())
    with dest.open("w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames)
        writer.writeheader()
        writer.writerows(rows)

if __name__ == "__main__":
    json_to_csv(Path("users.json"), Path("users.csv"))
```

**Re-encode a text file (e.g. latin-1 → utf-8):**

```python
from pathlib import Path

def reencode(src: Path, dest: Path, from_enc: str = "latin-1", to_enc: str = "utf-8") -> None:
    text = src.read_text(encoding=from_enc)
    dest.write_text(text, encoding=to_enc)

if __name__ == "__main__":
    reencode(Path("legacy.txt"), Path("utf8.txt"))
```

## ⚠️ Pitfalls [#️-pitfalls]

* Omitting `encoding=` uses locale defaults—breaks cross-platform.
* CSV needs `newline=""` to avoid blank lines on Windows.
* Nested JSON objects do not map cleanly to flat CSV—flatten or keep JSON.
* Loading huge files with `json.loads` / `list(DictReader)` can exhaust memory.

## 🔗 Related [#-related]

* [Manage files](/docs/python/examples/manage-files)
* [Encrypt](/docs/python/examples/encrypt)
* [List to dict](/docs/python/examples/list-to-dict)
* [Merge lists](/docs/python/examples/merge-lists)
* [../strings.md](/docs/python/strings)
* [../dictionaries.md](/docs/python/dictionaries)


# CSV and Excel (/docs/python/examples/csv-excel)



# CSV and Excel [#csv-and-excel]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Read/write tabular data with the stdlib `csv` module. For Excel (`.xlsx`), use `openpyxl` or `pandas`. Prefer CSV for interchange; Excel when stakeholders need workbooks.

## 🔧 Core concepts [#-core-concepts]

| Task           | Tool                                 |
| -------------- | ------------------------------------ |
| CSV read/write | `csv.DictReader` / `DictWriter`      |
| Dialect        | excel, excel-tab, custom             |
| Encoding       | `utf-8` / `utf-8-sig` (Excel)        |
| xlsx           | `openpyxl`, `pandas.read_excel`      |
| Large files    | Stream row-by-row; avoid loading all |

Always open CSV with `newline=""` (as docs recommend) and an explicit encoding.

## 💡 Examples [#-examples]

**CSV round-trip:**

```python
import csv
from pathlib import Path

path = Path("people.csv")
rows = [
    {"name": "Ada", "score": "10"},
    {"name": "Bob", "score": "7"},
]

with path.open("w", encoding="utf-8", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=["name", "score"])
    writer.writeheader()
    writer.writerows(rows)

with path.open("r", encoding="utf-8", newline="") as f:
    for row in csv.DictReader(f):
        print(row["name"], int(row["score"]))
```

**pandas quick path:**

```python
import pandas as pd

df = pd.read_csv("people.csv")
df["score"] = df["score"].astype(int)
df.to_excel("people.xlsx", index=False)
df2 = pd.read_excel("people.xlsx")
print(df2.head())
```

**openpyxl minimal:**

```python
from openpyxl import Workbook

wb = Workbook()
ws = wb.active
ws.title = "Scores"
ws.append(["name", "score"])
ws.append(["Ada", 10])
wb.save("scores.xlsx")
```

## ⚠️ Pitfalls [#️-pitfalls]

* Excel often expects `utf-8-sig` for CSV to show Unicode correctly.
* Forgetting `newline=""` on Windows can insert blank lines.
* Type coercion: CSV is all strings until you parse.
* Formulas / merged cells in xlsx need library-specific handling.
* Don't load multi-GB CSVs into a single list — stream or use pandas chunks.

## 🔗 Related [#-related]

* [Manage files](/docs/python/examples/manage-files)
* [Dataclass pipeline](/docs/python/examples/dataclass-pipeline)
* [SQLite](/docs/python/examples/sqlite)
* [../pathlib.md](/docs/python/pathlib)
* [../files\_io.md](/docs/python/files-io)
* [../dataclasses.md](/docs/python/dataclasses)


# Dataclass Config (/docs/python/examples/dataclass-config)



# Dataclass Config [#dataclass-config]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Load app settings into a frozen `@dataclass` from environment variables with defaults and light validation.

## 🔧 Core concepts [#-core-concepts]

| Piece                     | Role                      |
| ------------------------- | ------------------------- |
| `@dataclass(frozen=True)` | Immutable config snapshot |
| `os.environ`              | External configuration    |
| `classmethod` factory     | `from_env()` constructor  |
| Validation                | Fail fast on bad values   |

## 💡 Examples [#-examples]

**dataclass\_config.py:**

```python
from __future__ import annotations

import os
from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class AppConfig:
    app_name: str
    debug: bool
    port: int
    database_url: str

    @classmethod
    def from_env(cls) -> AppConfig:
        port_raw = os.environ.get("PORT", "8000")
        try:
            port = int(port_raw)
        except ValueError as e:
            raise ValueError(f"PORT must be an int, got {port_raw!r}") from e
        if not 1 <= port <= 65535:
            raise ValueError(f"PORT out of range: {port}")

        debug = os.environ.get("DEBUG", "0").lower() in {"1", "true", "yes"}
        database_url = os.environ.get("DATABASE_URL", "sqlite:///./app.db")
        if not database_url:
            raise ValueError("DATABASE_URL must not be empty")

        return cls(
            app_name=os.environ.get("APP_NAME", "demo"),
            debug=debug,
            port=port,
            database_url=database_url,
        )


def main() -> None:
    cfg = AppConfig.from_env()
    print(cfg)


if __name__ == "__main__":
    main()
```

**Usage:**

```shellscript
set PORT=9000
set DEBUG=true
python dataclass_config.py
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutable defaults (`list`, `dict`) need `field(default_factory=...)`.
* Frozen instances cannot be assigned after creation — rebuild instead.
* Booleans from env are strings; `"False"` is truthy if you only check `bool(s)`.

## 🔗 Related [#-related]

* [Dataclass pipeline](/docs/python/examples/dataclass-pipeline)
* [../dataclasses.md](/docs/python/dataclasses)
* [../enums.md](/docs/python/enums)


# Dataclass Pipeline (/docs/python/examples/dataclass-pipeline)



# Dataclass Pipeline [#dataclass-pipeline]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Model rows as dataclasses, then map/filter/validate through a small pipeline. Clear types beat anonymous dicts for ETL-style scripts.

## 🔧 Core concepts [#-core-concepts]

| Stage     | Role                                   |
| --------- | -------------------------------------- |
| Parse     | Raw dict/CSV → dataclass               |
| Validate  | `__post_init__` or explicit checks     |
| Transform | Pure functions returning new instances |
| Sink      | Write CSV/DB/JSON                      |

Prefer immutable (`frozen=True`) records when transforming functionally.

## 💡 Examples [#-examples]

**Model + parse:**

```python
from __future__ import annotations

from dataclasses import dataclass, asdict, replace
import csv
from pathlib import Path

@dataclass(frozen=True, slots=True)
class Order:
    id: int
    customer: str
    total: float

    def __post_init__(self) -> None:
        if self.total < 0:
            raise ValueError("total must be >= 0")

def parse_order(row: dict[str, str]) -> Order:
    return Order(
        id=int(row["id"]),
        customer=row["customer"].strip(),
        total=float(row["total"]),
    )
```

**Pipeline:**

```python
def load_orders(path: Path) -> list[Order]:
    with path.open(encoding="utf-8", newline="") as f:
        return [parse_order(r) for r in csv.DictReader(f)]

def with_tax(order: Order, rate: float = 0.1) -> Order:
    return replace(order, total=round(order.total * (1 + rate), 2))

def big_orders(orders: list[Order], min_total: float = 100.0) -> list[Order]:
    return [o for o in orders if o.total >= min_total]

def write_jsonl(path: Path, orders: list[Order]) -> None:
    import json
    lines = [json.dumps(asdict(o)) for o in orders]
    path.write_text("\n".join(lines) + "\n", encoding="utf-8")

def run(src: Path, dst: Path) -> None:
    orders = load_orders(src)
    taxed = [with_tax(o) for o in orders]
    write_jsonl(dst, big_orders(taxed))
```

**Sample CSV:**

```plaintext
id,customer,total
1,Ada,120.0
2,Bob,40.0
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mutable default fields need `field(default_factory=...)`.
* Silent bad rows: decide whether to skip + log or fail fast.
* Floating money — prefer integer cents in real billing systems.
* `asdict` is shallow for nested dataclasses.
* Mixing validation in many places — keep one parse boundary.

## 🔗 Related [#-related]

* [CSV and Excel](/docs/python/examples/csv-excel)
* [SQLite](/docs/python/examples/sqlite)
* [Pytest example](/docs/python/examples/pytest-example)
* [../dataclasses.md](/docs/python/dataclasses)
* [../json.md](/docs/python/json)
* [../typing\_hints.md](/docs/python/typing-hints)


# Decorators Timing (/docs/python/examples/decorators-timing)



# Decorators Timing [#decorators-timing]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Time function calls with a reusable decorator that preserves the wrapped signature via `functools.wraps`.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                          |
| ------------------- | ----------------------------- |
| Decorator           | Wrap callable, return wrapper |
| `functools.wraps`   | Keep `__name__` / docstring   |
| `time.perf_counter` | High-resolution elapsed time  |
| `*args, **kwargs`   | Forward any signature         |

## 💡 Examples [#-examples]

**decorators\_timing.py:**

```python
from __future__ import annotations

import functools
import time
from collections.abc import Callable
from typing import ParamSpec, TypeVar

P = ParamSpec("P")
R = TypeVar("R")


def timed(fn: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(fn)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.perf_counter()
        try:
            return fn(*args, **kwargs)
        finally:
            elapsed_ms = (time.perf_counter() - start) * 1000
            print(f"{fn.__name__} took {elapsed_ms:.2f} ms")

    return wrapper


@timed
def slow_add(a: int, b: int) -> int:
    time.sleep(0.05)
    return a + b


if __name__ == "__main__":
    print(slow_add(2, 3))
```

**Optional label / logger:**

```python
import logging

log = logging.getLogger(__name__)

def timed_log(fn: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(fn)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.perf_counter()
        try:
            return fn(*args, **kwargs)
        finally:
            log.info("%s %.2fms", fn.__name__, (time.perf_counter() - start) * 1000)
    return wrapper
```

## ⚠️ Pitfalls [#️-pitfalls]

* Without `@wraps`, tests and docs see `wrapper` instead of the real name.
* Timing includes exceptions — use `finally` so failures still report duration.
* Decorators on methods need care with `self`; this pattern still works.

## 🔗 Related [#-related]

* [../decorators.md](/docs/python/decorators)
* [../functions.md](/docs/python/functions)
* [../typing\_hints.md](/docs/python/typing-hints)


# Encrypt (/docs/python/examples/encrypt)



# Encrypt [#encrypt]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Encrypt secrets at rest with modern cryptography—not homemade XOR. For passwords use one-way hashing (`hashlib.scrypt` / `bcrypt`). For reversible data use authenticated encryption (Fernet or AES-GCM via the `cryptography` package). Never commit keys; load from environment.

## 🔧 Core concepts [#-core-concepts]

| Goal              | Approach                                           |
| ----------------- | -------------------------------------------------- |
| Password storage  | Slow hash + salt (`scrypt`, `argon2`, `bcrypt`)    |
| Symmetric encrypt | Fernet (AES + HMAC) or AES-GCM                     |
| Key storage       | Env var / secret manager—not source                |
| Integrity         | Prefer AEAD; detect tampering                      |
| Stdlib only       | `hashlib`, `secrets`, `hmac`—limited for full AEAD |

Install: `pip install cryptography`

## 💡 Examples [#-examples]

**Password hashing (stdlib scrypt):**

```python
import hashlib
import secrets

def hash_password(password: str) -> str:
    salt = secrets.token_bytes(16)
    digest = hashlib.scrypt(
        password.encode("utf-8"),
        salt=salt,
        n=2**14,
        r=8,
        p=1,
        dklen=32,
    )
    return f"{salt.hex()}${digest.hex()}"

def verify_password(password: str, stored: str) -> bool:
    salt_hex, digest_hex = stored.split("$", 1)
    salt = bytes.fromhex(salt_hex)
    digest = hashlib.scrypt(
        password.encode("utf-8"),
        salt=salt,
        n=2**14,
        r=8,
        p=1,
        dklen=32,
    )
    return secrets.compare_digest(digest.hex(), digest_hex)

if __name__ == "__main__":
    stored = hash_password("s3cret!")
    assert verify_password("s3cret!", stored)
```

**Fernet encrypt / decrypt:**

```python
import os
from cryptography.fernet import Fernet

def get_fernet() -> Fernet:
    key = os.environ.get("APP_FERNET_KEY")
    if not key:
        # generate once: Fernet.generate_key().decode()
        raise RuntimeError("Set APP_FERNET_KEY")
    return Fernet(key.encode("utf-8") if isinstance(key, str) else key)

def encrypt_text(plain: str) -> bytes:
    return get_fernet().encrypt(plain.encode("utf-8"))

def decrypt_text(token: bytes) -> str:
    return get_fernet().decrypt(token).decode("utf-8")

if __name__ == "__main__":
    # Demo only — set a real key in production
    os.environ["APP_FERNET_KEY"] = Fernet.generate_key().decode()
    token = encrypt_text("hello")
    print(decrypt_text(token))
```

**Generate a key once:**

```python
from cryptography.fernet import Fernet

print(Fernet.generate_key().decode())
```

## ⚠️ Pitfalls [#️-pitfalls]

* MD5/SHA-1 alone are not password hashes—use scrypt/argon2/bcrypt.
* Reusing IVs/nonces with AES-GCM is catastrophic; Fernet handles this for you.
* Logging plaintext or keys defeats encryption.
* `hashlib.md5` for “checksums” is fine for non-security integrity only.

## 🔗 Related [#-related]

* [Manage files](/docs/python/examples/manage-files)
* [Convert files](/docs/python/examples/convert-files)
* [Server](/docs/python/examples/server)
* [Telegram bot](/docs/python/examples/tg-bot)
* [../import\_export.md](/docs/python/import-export)
* [../types.md](/docs/python/types)


# Hello CLI (/docs/python/examples/hello-cli)



# Hello CLI [#hello-cli]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Minimal command-line greeting with `argparse`: one positional argument, one flag, and a clean `main()` entrypoint.

## 🔧 Core concepts [#-core-concepts]

| Piece                | Role                           |
| -------------------- | ------------------------------ |
| `ArgumentParser`     | Define CLI interface           |
| Positional arg       | Required `name`                |
| `store_true`         | Optional `--shout` flag        |
| `main()` + exit code | Testable entry, `0` on success |

## 💡 Examples [#-examples]

**hello\_cli.py:**

```python
from __future__ import annotations

import argparse
import sys


def greet(name: str, shout: bool = False) -> str:
    msg = f"Hello, {name}!"
    return msg.upper() if shout else msg


def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(description="Say hello")
    p.add_argument("name", help="who to greet")
    p.add_argument("-s", "--shout", action="store_true", help="uppercase")
    return p


def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    print(greet(args.name, shout=args.shout))
    return 0


if __name__ == "__main__":
    sys.exit(main())
```

**Usage:**

```shellscript
python hello_cli.py Ada
python hello_cli.py Ada --shout
```

## ⚠️ Pitfalls [#️-pitfalls]

* Do not parse `sys.argv` at import time — keep parsing inside `main()`.
* Prefer returning an exit code over `sys.exit()` deep in helpers.
* `print` alone is fine for tiny tools; add logging when behavior grows.

## 🔗 Related [#-related]

* [CLI tool](/docs/python/examples/cli-tool)
* [../argparse.md](/docs/python/argparse)
* [../print\_input.md](/docs/python/print-input)


# HTTP Requests (/docs/python/examples/http-requests)



# HTTP Requests [#http-requests]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Call HTTP APIs with the popular `requests` library (or stdlib `urllib`). Handle timeouts, status codes, and JSON payloads explicitly. Install: `python -m pip install requests`.

## 🔧 Core concepts [#-core-concepts]

| Task         | Approach                                  |
| ------------ | ----------------------------------------- |
| GET/POST     | `requests.get/post`                       |
| JSON body    | `json=` param                             |
| Query string | `params=`                                 |
| Headers      | `headers=`                                |
| Timeout      | Always set `timeout=`                     |
| Errors       | `raise_for_status()`                      |
| Session      | `requests.Session()` for connection reuse |

Prefer sessions for multiple calls to the same host. Never hardcode secrets — use env vars.

## 💡 Examples [#-examples]

**GET JSON:**

```python
import os
import requests

def fetch_user(user_id: int) -> dict:
    token = os.environ["API_TOKEN"]
    url = f"https://api.example.com/users/{user_id}"
    resp = requests.get(
        url,
        headers={"Authorization": f"Bearer {token}"},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()
```

**POST and session:**

```python
import requests

with requests.Session() as s:
    s.headers.update({"Accept": "application/json"})
    r = s.post(
        "https://httpbin.org/post",
        json={"name": "Ada"},
        timeout=10,
    )
    r.raise_for_status()
    print(r.json()["json"])
```

**stdlib alternative:**

```python
import json
from urllib.request import Request, urlopen

req = Request(
    "https://httpbin.org/get",
    headers={"Accept": "application/json"},
)
with urlopen(req, timeout=10) as resp:
    data = json.load(resp)
print(data["url"])
```

**Retry sketch:** see [retry backoff](/docs/python/examples/retry-backoff).

## ⚠️ Pitfalls [#️-pitfalls]

* Missing `timeout` can hang forever.
* Not calling `raise_for_status()` treats 404/500 as success.
* Logging response bodies may leak PII/tokens.
* `verify=False` disables TLS verification — avoid.
* Relative redirects + mixed POST/GET behavior — know `allow_redirects`.

## 🔗 Related [#-related]

* [Retry backoff](/docs/python/examples/retry-backoff)
* [Scrape HTML](/docs/python/examples/scrape-html)
* [CLI tool](/docs/python/examples/cli-tool)
* [../json.md](/docs/python/json)
* [../exceptions.md](/docs/python/exceptions)
* [../logging.md](/docs/python/logging)


# Examples (/docs/python/examples)



# Examples [#examples]

Python notes in **Examples**.


# List to dict (/docs/python/examples/list-to-dict)



# List to dict [#list-to-dict]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Turn sequences into dictionaries for O(1) lookup: pairs → mapping, list of objects → keyed by id, or group values under a key. Prefer `dict()`, comprehensions, and `collections.defaultdict` over manual loops when clear.

## 🔧 Core concepts [#-core-concepts]

| Pattern       | Idiom                                        |
| ------------- | -------------------------------------------- |
| Pairs         | `dict(pairs)` / `\{k: v for k, v in pairs\}` |
| Key function  | `\{item.id: item for item in items\}`        |
| Enumerate     | `dict(enumerate(items))`                     |
| Group         | `defaultdict(list)`                          |
| Zip two lists | `dict(zip(keys, values))`                    |

Duplicate keys: later values win in a comprehension/`dict`.

## 💡 Examples [#-examples]

**Zip keys and values:**

```python
keys = ["id", "name", "role"]
values = [1, "Ada", "admin"]
user = dict(zip(keys, values, strict=True))
print(user)  # {'id': 1, 'name': 'Ada', 'role': 'admin'}
```

**Index objects by id:**

```python
from dataclasses import dataclass

@dataclass(frozen=True)
class User:
    id: int
    name: str

users = [User(1, "Ada"), User(2, "Bob")]
by_id = {u.id: u for u in users}
print(by_id[1].name)  # Ada
```

**Group list of dicts:**

```python
from collections import defaultdict

rows = [
    {"dept": "eng", "name": "Ada"},
    {"dept": "hr", "name": "Bob"},
    {"dept": "eng", "name": "Cary"},
]

grouped: dict[str, list[str]] = defaultdict(list)
for row in rows:
    grouped[row["dept"]].append(row["name"])
print(dict(grouped))
```

**Pairs from nested lists:**

```python
pairs = [["a", 1], ["b", 2], ["a", 3]]
# last wins for duplicate keys
print(dict(pairs))  # {'a': 3, 'b': 2}
```

## ⚠️ Pitfalls [#️-pitfalls]

* `dict(zip(keys, values))` silently truncates if lengths differ—use `strict=True` (3.10+).
* Unhashable keys (`list`, `dict`) raise `TypeError`.
* Building `\{i: x for i, x in enumerate(xs)\}` is rarely needed—keep the list if order matters.
* Mutating values that are shared lists/dicts affects every reference.

## 🔗 Related [#-related]

* [Merge lists](/docs/python/examples/merge-lists)
* [Convert files](/docs/python/examples/convert-files)
* [Manage files](/docs/python/examples/manage-files)
* [../dictionaries.md](/docs/python/dictionaries)
* [../loops.md](/docs/python/loops)
* [../types.md](/docs/python/types)


# Manage files (/docs/python/examples/manage-files)



# Manage files [#manage-files]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Create, read, write, copy, move, and delete files with `pathlib` and `shutil`. Prefer context managers (`with`) so handles close reliably. Use absolute paths in scripts; resolve relative to a known base directory.

## 🔧 Core concepts [#-core-concepts]

| Task             | API                             |
| ---------------- | ------------------------------- |
| Paths            | `pathlib.Path`                  |
| Read/write text  | `Path.read_text` / `write_text` |
| Read/write bytes | `read_bytes` / `write_bytes`    |
| List             | `iterdir`, `glob`, `rglob`      |
| Copy / move      | `shutil.copy2`, `shutil.move`   |
| Delete           | `Path.unlink`, `shutil.rmtree`  |
| Temp             | `tempfile.TemporaryDirectory`   |

Always pass `encoding="utf-8"` for text unless you know otherwise.

## 💡 Examples [#-examples]

**Read, write, append:**

```python
from pathlib import Path

base = Path("data")
base.mkdir(parents=True, exist_ok=True)

path = base / "notes.txt"
path.write_text("hello\n", encoding="utf-8")
path.write_text(path.read_text(encoding="utf-8") + "world\n", encoding="utf-8")
print(path.read_text(encoding="utf-8"))
```

**List and filter:**

```python
from pathlib import Path

root = Path("data")
for p in sorted(root.rglob("*.txt")):
    if p.is_file():
        print(p, p.stat().st_size)
```

**Copy, move, delete safely:**

```python
import shutil
from pathlib import Path

src = Path("data/notes.txt")
backup = Path("data/backup")
backup.mkdir(parents=True, exist_ok=True)

shutil.copy2(src, backup / src.name)
shutil.move(str(backup / src.name), backup / "notes.bak")

target = backup / "notes.bak"
if target.exists():
    target.unlink()
```

**Atomic-ish write (write temp then replace):**

```python
from pathlib import Path

def atomic_write(path: Path, text: str) -> None:
    tmp = path.with_suffix(path.suffix + ".tmp")
    tmp.write_text(text, encoding="utf-8")
    tmp.replace(path)

if __name__ == "__main__":
    atomic_write(Path("data/config.json"), '{"ok": true}\n')
```

## ⚠️ Pitfalls [#️-pitfalls]

* `open` without `with` leaks handles on exceptions.
* `Path.unlink()` raises if missing—use `missing_ok=True` (3.8+).
* `shutil.rmtree` is destructive; confirm paths before deleting.
* Relative paths depend on the process cwd—not the script location (`Path(__file__).resolve().parent`).

## 🔗 Related [#-related]

* [Convert files](/docs/python/examples/convert-files)
* [Encrypt](/docs/python/examples/encrypt)
* [Server](/docs/python/examples/server)
* [../import\_export.md](/docs/python/import-export)
* [../strings.md](/docs/python/strings)
* [../f-string.md](/docs/python/f-string)


# Merge lists (/docs/python/examples/merge-lists)



# Merge lists [#merge-lists]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Combine lists by concatenation, extension, or set-like union while controlling duplicates and order. Choose the approach based on whether you need stable order, uniqueness, or pairwise zipping.

## 🔧 Core concepts [#-core-concepts]

| Goal                  | Approach                             |
| --------------------- | ------------------------------------ |
| Concatenate           | `a + b`, `[*a, *b]`                  |
| Extend in place       | `a.extend(b)`                        |
| Unique preserve order | `dict.fromkeys(a + b)`               |
| Set union             | `list(set(a) \| set(b))` (unordered) |
| Interleave / pair     | `zip`, nested loops                  |
| Deep merge objects    | Custom logic / dict merge            |

## 💡 Examples [#-examples]

**Concatenate and unique (order preserved):**

```python
a = [1, 2, 3, 2]
b = [3, 4, 5]

merged = a + b
unique = list(dict.fromkeys(merged))
print(merged)  # [1, 2, 3, 2, 3, 4, 5]
print(unique)  # [1, 2, 3, 4, 5]
```

**Extend vs new list:**

```python
a = [1, 2]
b = [3, 4]
a.extend(b)       # mutates a → [1, 2, 3, 4]
c = [*a, *b]      # new list (here a already includes b)
```

**Merge list of dicts by key:**

```python
from typing import Any

def merge_by_id(*groups: list[dict[str, Any]]) -> list[dict[str, Any]]:
    by_id: dict[Any, dict[str, Any]] = {}
    for group in groups:
        for row in group:
            key = row["id"]
            by_id[key] = {**by_id.get(key, {}), **row}
    return list(by_id.values())

left = [{"id": 1, "name": "Ada"}, {"id": 2, "name": "Bob"}]
right = [{"id": 2, "role": "admin"}, {"id": 3, "name": "Cary"}]
print(merge_by_id(left, right))
```

**Flatten nested lists:**

```python
nested = [[1, 2], [3], [4, 5]]
flat = [x for group in nested for x in group]
print(flat)  # [1, 2, 3, 4, 5]
```

## ⚠️ Pitfalls [#️-pitfalls]

* `a += b` mutates `a`; `a = a + b` allocates a new list.
* `set` union drops order and requires hashable elements.
* Aliasing: `c = a; c.extend(b)` also changes `a`.
* Nested mutable elements are shared after shallow merges.

## 🔗 Related [#-related]

* [List to dict](/docs/python/examples/list-to-dict)
* [Convert files](/docs/python/examples/convert-files)
* [../loops.md](/docs/python/loops)
* [../dictionaries.md](/docs/python/dictionaries)
* [../types.md](/docs/python/types)
* [../kwags.md](/docs/python/kwags)


# Parse JSON API (/docs/python/examples/parse-json-api)



# Parse JSON API [#parse-json-api]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Fetch a JSON API with `urllib` or `httpx`, validate the shape lightly, and extract fields safely.

## 🔧 Core concepts [#-core-concepts]

| Piece             | Role                             |
| ----------------- | -------------------------------- |
| GET + JSON body   | Typical REST read                |
| `response.json()` | Decode payload                   |
| Key checks        | Avoid `KeyError` on partial data |
| Timeout           | Fail fast on hung networks       |

## 💡 Examples [#-examples]

**parse\_json\_api.py (stdlib):**

```python
from __future__ import annotations

import json
import urllib.error
import urllib.request
from typing import Any


def fetch_user(user_id: int, timeout: float = 10.0) -> dict[str, Any]:
    url = f"https://jsonplaceholder.typicode.com/users/{user_id}"
    req = urllib.request.Request(url, headers={"Accept": "application/json"})
    try:
        with urllib.request.urlopen(req, timeout=timeout) as resp:
            raw = resp.read().decode("utf-8")
    except urllib.error.HTTPError as e:
        raise RuntimeError(f"HTTP {e.code} for user {user_id}") from e
    except urllib.error.URLError as e:
        raise RuntimeError(f"network error: {e.reason}") from e

    data = json.loads(raw)
    if not isinstance(data, dict):
        raise ValueError("expected a JSON object")
    if "id" not in data or "email" not in data:
        raise ValueError("missing id or email")
    return data


def main() -> None:
    user = fetch_user(1)
    print(f"{user['name']} <{user['email']}>")


if __name__ == "__main__":
    main()
```

**With httpx (optional):**

```python
import httpx

def fetch_user_httpx(user_id: int) -> dict:
    r = httpx.get(
        f"https://jsonplaceholder.typicode.com/users/{user_id}",
        timeout=10.0,
    )
    r.raise_for_status()
    return r.json()
```

## ⚠️ Pitfalls [#️-pitfalls]

* Never assume every key exists — APIs change and error bodies differ.
* Always set a timeout; default can hang forever.
* `json.loads` on HTML error pages raises `JSONDecodeError` — catch it.

## 🔗 Related [#-related]

* [HTTP requests](/docs/python/examples/http-requests)
* [../json.md](/docs/python/json)
* [../exceptions.md](/docs/python/exceptions)


# Pathlib Walk (/docs/python/examples/pathlib-walk)



# Pathlib Walk [#pathlib-walk]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Walk a directory tree with `pathlib.Path.rglob`, filter by suffix, and collect file sizes without `os.walk`.

## 🔧 Core concepts [#-core-concepts]

| Piece            | Role                            |
| ---------------- | ------------------------------- |
| `Path`           | Cross-platform paths            |
| `rglob`          | Recursive glob                  |
| `is_file()`      | Skip directories / broken links |
| `stat().st_size` | Byte size                       |

## 💡 Examples [#-examples]

**pathlib\_walk.py:**

```python
from __future__ import annotations

from pathlib import Path


def list_py_files(root: Path) -> list[tuple[Path, int]]:
    root = root.resolve()
    results: list[tuple[Path, int]] = []
    for path in root.rglob("*.py"):
        if not path.is_file():
            continue
        results.append((path.relative_to(root), path.stat().st_size))
    return sorted(results, key=lambda t: str(t[0]))


def main() -> None:
    root = Path(".")
    rows = list_py_files(root)
    total = sum(size for _, size in rows)
    for rel, size in rows:
        print(f"{size:>8}  {rel}")
    print(f"\n{len(rows)} files, {total} bytes")


if __name__ == "__main__":
    main()
```

**Exclude folders:**

```python
SKIP = {".git", ".venv", "node_modules", "__pycache__"}

def list_py_files_filtered(root: Path) -> list[Path]:
    out: list[Path] = []
    for path in root.rglob("*.py"):
        if any(part in SKIP for part in path.parts):
            continue
        if path.is_file():
            out.append(path)
    return out
```

## ⚠️ Pitfalls [#️-pitfalls]

* `rglob` follows symlinks on some platforms — guard against cycles if needed.
* Calling `stat()` on every file can be slow on huge trees; batch or cache.
* Relative vs absolute: resolve once at the start for stable `relative_to`.

## 🔗 Related [#-related]

* [Manage files](/docs/python/examples/manage-files)
* [../pathlib.md](/docs/python/pathlib)
* [../files\_io.md](/docs/python/files-io)


# Pytest Example (/docs/python/examples/pytest-example)



# Pytest Example [#pytest-example]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

A minimal pytest layout: functions under test, fixtures, parametrize, and `tmp_path`. Run with `python -m pytest -q`.

## 🔧 Core concepts [#-core-concepts]

| Piece         | Role                |
| ------------- | ------------------- |
| `test_*.py`   | Discovery           |
| Fixtures      | Reusable setup      |
| `parametrize` | Many inputs         |
| `tmp_path`    | Isolated filesystem |
| `capsys`      | Capture stdout      |
| `raises`      | Expected errors     |

Keep tests independent; name them after behavior, not implementation.

## 💡 Examples [#-examples]

**mylib.py:**

```python
from pathlib import Path

def normalize(name: str) -> str:
    cleaned = name.strip().lower()
    if not cleaned:
        raise ValueError("empty name")
    return cleaned

def save_greeting(path: Path, name: str) -> None:
    path.write_text(f"Hello, {normalize(name)}!\n", encoding="utf-8")
```

**test\_mylib.py:**

```python
import pytest
from pathlib import Path

from mylib import normalize, save_greeting

@pytest.mark.parametrize(
    "raw,expected",
    [(" Ada ", "ada"), ("BOB", "bob")],
)
def test_normalize(raw: str, expected: str) -> None:
    assert normalize(raw) == expected

def test_normalize_empty() -> None:
    with pytest.raises(ValueError, match="empty"):
        normalize("   ")

def test_save_greeting(tmp_path: Path) -> None:
    out = tmp_path / "hi.txt"
    save_greeting(out, " Ada ")
    assert out.read_text(encoding="utf-8") == "Hello, ada!\n"
```

**CLI test with capsys:**

```python
from cli_tool_stub import main  # your main(argv) -> int

def test_cli(capsys) -> None:
    assert main(["Ada"]) == 0
    assert "Hello, Ada!" in capsys.readouterr().out
```

**Run:**

```shellscript
python -m pip install pytest
python -m pytest -q
python -m pytest -k normalize -vv
```

## ⚠️ Pitfalls [#️-pitfalls]

* Import path issues — use `src` layout or install editable (`pip install -e .`).
* Tests depending on wall-clock time without freezing.
* Writing into the repo instead of `tmp_path`.
* Over-mocking until tests assert nothing real.
* Ignoring warnings that signal API misuse.

## 🔗 Related [#-related]

* [CLI tool](/docs/python/examples/cli-tool)
* [Dataclass pipeline](/docs/python/examples/dataclass-pipeline)
* [../testing\_pytest.md](/docs/python/testing-pytest)
* [../exceptions.md](/docs/python/exceptions)
* [../pathlib.md](/docs/python/pathlib)
* [../functions.md](/docs/python/functions)


# Retry with Backoff (/docs/python/examples/retry-backoff)



# Retry with Backoff [#retry-with-backoff]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Transient failures (network blips, 429/503) often succeed on retry. Use exponential backoff with jitter. Prefer a small helper or `tenacity` over ad-hoc loops copied everywhere.

## 🔧 Core concepts [#-core-concepts]

| Idea                | Detail                                    |
| ------------------- | ----------------------------------------- |
| Retryable           | Timeouts, connection errors, 429/5xx      |
| Non-retryable       | 400/401/403/404 (usually)                 |
| Exponential backoff | `delay * 2 ** attempt`                    |
| Jitter              | Randomize delay to avoid thundering herds |
| Cap                 | Max attempts + max delay                  |
| Idempotency         | Safe to retry GET; careful with POST      |

## 💡 Examples [#-examples]

**Manual helper:**

```python
from __future__ import annotations

import random
import time
from collections.abc import Callable
from typing import TypeVar

import requests

T = TypeVar("T")

def with_backoff(
    fn: Callable[[], T],
    *,
    attempts: int = 5,
    base: float = 0.5,
    max_delay: float = 8.0,
) -> T:
    last: Exception | None = None
    for i in range(attempts):
        try:
            return fn()
        except (requests.Timeout, requests.ConnectionError) as e:
            last = e
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else 0
            if status not in {429, 500, 502, 503, 504}:
                raise
            last = e
        delay = min(max_delay, base * (2**i))
        delay *= 0.5 + random.random()  # jitter
        time.sleep(delay)
    assert last is not None
    raise last

def fetch(url: str) -> dict:
    def _call() -> dict:
        r = requests.get(url, timeout=10)
        r.raise_for_status()
        return r.json()

    return with_backoff(_call)
```

**tenacity sketch:**

```python
from tenacity import retry, stop_after_attempt, wait_exponential_jitter
import requests

@retry(stop=stop_after_attempt(5), wait=wait_exponential_jitter(initial=0.5, max=8))
def get_json(url: str) -> dict:
    r = requests.get(url, timeout=10)
    r.raise_for_status()
    return r.json()
```

**Async note:** use `asyncio.sleep` in async helpers — see [../async.md](/docs/python/async).

## ⚠️ Pitfalls [#️-pitfalls]

* Retrying non-idempotent POSTs can duplicate side effects.
* No jitter → synchronized retries amplify outages.
* Swallowing all exceptions hides permanent bugs.
* Ignoring `Retry-After` headers on 429.
* Busy-loops without sleep burn CPU and get banned.

## 🔗 Related [#-related]

* [HTTP requests](/docs/python/examples/http-requests)
* [Scrape HTML](/docs/python/examples/scrape-html)
* [../exceptions.md](/docs/python/exceptions)
* [../concurrency.md](/docs/python/concurrency)
* [../logging.md](/docs/python/logging)
* [../datetime.md](/docs/python/datetime)


# Scrape HTML (/docs/python/examples/scrape-html)



# Scrape HTML [#scrape-html]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Fetch HTML over HTTP and parse it with Beautiful Soup (`bs4`). Respect robots.txt, rate limits, and site terms. Prefer official APIs when available.

## 🔧 Core concepts [#-core-concepts]

| Step   | Tool                                           |
| ------ | ---------------------------------------------- |
| Fetch  | `requests` + timeout                           |
| Parse  | `BeautifulSoup(html, "html.parser")` or `lxml` |
| Select | CSS via `select` / `select_one`                |
| Text   | `.get_text(strip=True)`                        |
| Attrs  | `tag["href"]`, `.get("href")`                  |

Install: `python -m pip install requests beautifulsoup4`. Optional: `lxml` for speed.

## 💡 Examples [#-examples]

**Extract links:**

```python
import requests
from bs4 import BeautifulSoup

def extract_links(url: str) -> list[str]:
    resp = requests.get(url, timeout=15, headers={"User-Agent": "docs-bot/1.0"})
    resp.raise_for_status()
    soup = BeautifulSoup(resp.text, "html.parser")
    links: list[str] = []
    for a in soup.select("a[href]"):
        href = a.get("href")
        if href:
            links.append(href)
    return links

if __name__ == "__main__":
    print(extract_links("https://example.com")[:5])
```

**Table-ish content:**

```python
from bs4 import BeautifulSoup

html = """
<ul class="items">
  <li data-id="1">Ada</li>
  <li data-id="2">Bob</li>
</ul>
"""
soup = BeautifulSoup(html, "html.parser")
people = [
    {"id": li["data-id"], "name": li.get_text(strip=True)}
    for li in soup.select("ul.items li")
]
print(people)
```

**Absolute URLs:**

```python
from urllib.parse import urljoin
import requests
from bs4 import BeautifulSoup

base = "https://example.com"
soup = BeautifulSoup(requests.get(base, timeout=15).text, "html.parser")
abs_links = [urljoin(base, a["href"]) for a in soup.select("a[href]")]
```

## ⚠️ Pitfalls [#️-pitfalls]

* Scraping JS-rendered pages needs a browser tool — BS4 only sees HTML.
* Fragile CSS selectors break when sites redesign.
* Aggressive crawling can get you blocked — throttle and cache.
* Encoding: use `resp.content` + apparent encoding when text looks wrong.
* Legal/ToS: check before scraping; don't bypass paywalls/auth.

## 🔗 Related [#-related]

* [HTTP requests](/docs/python/examples/http-requests)
* [Retry backoff](/docs/python/examples/retry-backoff)
* [../regex.md](/docs/python/regex)
* [../strings.md](/docs/python/strings)
* [../json.md](/docs/python/json)
* [../exceptions.md](/docs/python/exceptions)


# HTTP server (/docs/python/examples/server)



# HTTP server [#http-server]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Spin up a small HTTP server with the standard library for local tools, webhooks, and demos. For production APIs prefer FastAPI/Django/Flask with a proper ASGI/WSGI server. Below: `http.server` for static files and a tiny `ThreadingHTTPServer` JSON handler.

## 🔧 Core concepts [#-core-concepts]

| Piece                                | Role                                                   |
| ------------------------------------ | ------------------------------------------------------ |
| `HTTPServer` / `ThreadingHTTPServer` | Socket + request loop                                  |
| `BaseHTTPRequestHandler`             | `do_GET` / `do_POST`                                   |
| Static files                         | `http.server` module CLI or `SimpleHTTPRequestHandler` |
| Bind                                 | `0.0.0.0` for LAN; `127.0.0.1` for local only          |
| Port                                 | Check availability; avoid privileged \< 1024           |

## 💡 Examples [#-examples]

**Static file server (CLI):**

```shellscript
python -m http.server 9000 --bind 127.0.0.1
```

**Minimal JSON API:**

```python
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class Handler(BaseHTTPRequestHandler):
    def _json(self, code: int, payload: dict) -> None:
        body = json.dumps(payload).encode("utf-8")
        self.send_response(code)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_GET(self) -> None:
        if self.path == "/health":
            self._json(200, {"status": "ok"})
            return
        self._json(404, {"error": "not found"})

    def do_POST(self) -> None:
        if self.path != "/echo":
            self._json(404, {"error": "not found"})
            return
        length = int(self.headers.get("Content-Length", "0"))
        raw = self.rfile.read(length)
        data = json.loads(raw.decode("utf-8") or "{}")
        self._json(200, {"echo": data})

    def log_message(self, fmt: str, *args) -> None:
        print(f"{self.address_string()} - {fmt % args}")


def main() -> None:
    host, port = "127.0.0.1", 9000
    server = ThreadingHTTPServer((host, port), Handler)
    print(f"listening on http://{host}:{port}")
    server.serve_forever()


if __name__ == "__main__":
    main()
```

**Async alternative sketch (aiohttp-style idea with asyncio):**

```python
# Prefer a real framework for async HTTP; stdlib has limited ASGI support.
# Example entry with FastAPI would be: uvicorn app:app --port 9000
```

## ⚠️ Pitfalls [#️-pitfalls]

* `http.server` is not hardened for public internet exposure.
* Blocking work in `do_*` stalls that worker thread—offload heavy jobs.
* Forgetting `Content-Length` / correct headers breaks some clients.
* Binding `0.0.0.0` without auth exposes the service on the LAN.

## 🔗 Related [#-related]

* [Telegram bot](/docs/python/examples/tg-bot)
* [Encrypt](/docs/python/examples/encrypt)
* [Manage files](/docs/python/examples/manage-files)
* [../async.md](/docs/python/async)
* [../import\_export.md](/docs/python/import-export)
* [../f-string.md](/docs/python/f-string)


# SQLite (/docs/python/examples/sqlite)



# SQLite [#sqlite]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

`sqlite3` is a zero-config SQL database in the stdlib. Great for local apps, caches, and prototypes. Use parameterized queries always; never format SQL with f-strings and user input.

## 🔧 Core concepts [#-core-concepts]

| Task         | API                             |
| ------------ | ------------------------------- |
| Connect      | `sqlite3.connect(path)`         |
| Cursor       | `conn.execute` / `cursor`       |
| Commit       | `conn.commit()` or `with conn:` |
| Params       | `?` placeholders                |
| Rows         | `sqlite3.Row` factory           |
| Transactions | Context manager on connection   |

`:memory:` creates an in-memory DB. WAL mode helps concurrent readers.

## 💡 Examples [#-examples]

**Create and query:**

```python
import sqlite3
from pathlib import Path

db = Path("app.db")
with sqlite3.connect(db) as conn:
    conn.row_factory = sqlite3.Row
    conn.execute(
        """
        CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY,
            name TEXT NOT NULL UNIQUE
        )
        """
    )
    conn.execute("INSERT OR IGNORE INTO users (name) VALUES (?)", ("Ada",))
    row = conn.execute(
        "SELECT id, name FROM users WHERE name = ?", ("Ada",)
    ).fetchone()
    print(dict(row) if row else None)
```

**Many inserts:**

```python
import sqlite3

rows = [("Ada",), ("Bob",), ("Cy",)]
with sqlite3.connect("app.db") as conn:
    conn.executemany("INSERT OR IGNORE INTO users (name) VALUES (?)", rows)
```

**Context and cleanup:**

```python
import sqlite3

def list_names(path: str) -> list[str]:
    with sqlite3.connect(path) as conn:
        cur = conn.execute("SELECT name FROM users ORDER BY name")
        return [r[0] for r in cur]
```

## ⚠️ Pitfalls [#️-pitfalls]

* SQL injection: never interpolate user strings into SQL.
* Forgetting `commit` (use `with conn:` which auto-commits if no error).
* Sharing connections across threads — check `check_same_thread`.
* `LIKE` wildcards from users need escaping.
* Schema migrations: plan `ALTER` carefully; SQLite has limits.

## 🔗 Related [#-related]

* [CSV and Excel](/docs/python/examples/csv-excel)
* [Dataclass pipeline](/docs/python/examples/dataclass-pipeline)
* [CLI tool](/docs/python/examples/cli-tool)
* [../context\_managers.md](/docs/python/context-managers)
* [../exceptions.md](/docs/python/exceptions)
* [../pathlib.md](/docs/python/pathlib)


# Telegram bot (/docs/python/examples/tg-bot)



# Telegram bot [#telegram-bot]

*Python · Example / how-to*

***

## 📋 Overview [#-overview]

Build a simple Telegram bot with long polling using `httpx`/`requests` against Bot API, or the popular `python-telegram-bot` library. Store the bot token in an environment variable. Start with echo/commands; add webhooks when you deploy behind HTTPS.

## 🔧 Core concepts [#-core-concepts]

| Piece       | Detail                                                          |
| ----------- | --------------------------------------------------------------- |
| Token       | From [@BotFather](https://t.me/BotFather); `TELEGRAM_BOT_TOKEN` |
| getUpdates  | Long polling for local/dev                                      |
| sendMessage | Reply to `chat.id`                                              |
| Commands    | Messages starting with `/`                                      |
| Webhook     | Production: HTTPS endpoint receives updates                     |
| Library     | `pip install python-telegram-bot`                               |

## 💡 Examples [#-examples]

**Minimal echo with `python-telegram-bot` (v21+ async):**

```python
import os
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters


async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    assert update.effective_message
    await update.effective_message.reply_text("Hi! Send me any text.")


async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    assert update.effective_message and update.effective_message.text
    await update.effective_message.reply_text(update.effective_message.text)


def main() -> None:
    token = os.environ["TELEGRAM_BOT_TOKEN"]
    app = Application.builder().token(token).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
    app.run_polling(allowed_updates=Update.ALL_TYPES)


if __name__ == "__main__":
    main()
```

**Raw Bot API long poll (stdlib + urllib):**

```python
import json
import os
import urllib.parse
import urllib.request

TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"


def call(method: str, **params):
    data = urllib.parse.urlencode(params).encode()
    with urllib.request.urlopen(f"{API}/{method}", data=data, timeout=60) as resp:
        return json.loads(resp.read().decode())


def main() -> None:
    offset = 0
    while True:
        payload = call("getUpdates", offset=offset, timeout=30)
        for upd in payload.get("result", []):
            offset = upd["update_id"] + 1
            msg = upd.get("message") or {}
            text = msg.get("text")
            chat = msg.get("chat") or {}
            chat_id = chat.get("id")
            if text and chat_id:
                call("sendMessage", chat_id=chat_id, text=f"echo: {text}")


if __name__ == "__main__":
    main()
```

**Run:**

```shellscript
set TELEGRAM_BOT_TOKEN=123456:ABC...
python bot.py
```

## ⚠️ Pitfalls [#️-pitfalls]

* Committing tokens to git—rotate immediately if leaked.
* Two pollers with the same token fight over updates.
* Network timeouts: use reasonable `timeout` and retry with backoff.
* Webhooks require valid TLS; local dev usually uses polling.

## 🔗 Related [#-related]

* [Server](/docs/python/examples/server)
* [Encrypt](/docs/python/examples/encrypt)
* [Manage files](/docs/python/examples/manage-files)
* [../async.md](/docs/python/async)
* [../import\_export.md](/docs/python/import-export)
* [../kwags.md](/docs/python/kwags)


# Dark Mode Toggle (/docs/react-native/examples/dark-mode-toggle)



# Dark Mode Toggle [#dark-mode-toggle]

*React Native · Example / how-to*

***

## 📋 Overview [#-overview]

Toggle light/dark appearance with React context and `useColorScheme`, applying colors through a small theme object.

## 🔧 Core concepts [#-core-concepts]

| Piece            | Role                     |
| ---------------- | ------------------------ |
| `useColorScheme` | System preference        |
| Context          | Share resolved theme     |
| Manual override  | User toggle beats system |
| Style tokens     | Background / text colors |

## 💡 Examples [#-examples]

**dark\_mode\_toggle.tsx:**

```tsx
import {
  createContext,
  useContext,
  useMemo,
  useState,
  type ReactNode,
} from "react";
import {
  Button,
  Text,
  useColorScheme,
  View,
  StyleSheet,
} from "react-native";

type Mode = "system" | "light" | "dark";
type Palette = { bg: string; fg: string };

const palettes: Record<"light" | "dark", Palette> = {
  light: { bg: "#ffffff", fg: "#111111" },
  dark: { bg: "#111111", fg: "#f5f5f5" },
};

type ThemeCtx = {
  mode: Mode;
  setMode: (m: Mode) => void;
  colors: Palette;
};

const ThemeContext = createContext<ThemeCtx | null>(null);

export function ThemeProvider({ children }: { children: ReactNode }) {
  const system = useColorScheme();
  const [mode, setMode] = useState<Mode>("system");
  const resolved = mode === "system" ? (system === "dark" ? "dark" : "light") : mode;
  const value = useMemo(
    () => ({ mode, setMode, colors: palettes[resolved] }),
    [mode, resolved],
  );
  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

export function useTheme() {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error("useTheme requires ThemeProvider");
  return ctx;
}

export function DarkModeToggle() {
  const { mode, setMode, colors } = useTheme();
  return (
    <View style={[styles.box, { backgroundColor: colors.bg }]}>
      <Text style={{ color: colors.fg }}>Mode: {mode}</Text>
      <Button title="System" onPress={() => setMode("system")} />
      <Button title="Light" onPress={() => setMode("light")} />
      <Button title="Dark" onPress={() => setMode("dark")} />
    </View>
  );
}

const styles = StyleSheet.create({
  box: { flex: 1, gap: 8, padding: 16, justifyContent: "center" },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* System scheme can be `null` — default to light.
* Hard-coded `#fff` in child components ignores the theme — pass `colors` or use context.
* Persist `mode` if you want the choice to survive restarts.

## 🔗 Related [#-related]

* [FlatList search](/docs/react-native/examples/flatlist-search)
* [Form keyboard](/docs/react-native/examples/form-keyboard)


# FlatList Search (/docs/react-native/examples/flatlist-search)



# FlatList Search [#flatlist-search]

*React Native · Example / how-to*

***

## 📋 Overview [#-overview]

Filter a `FlatList` from a search `TextInput` with memoized data and stable `keyExtractor`.

## 🔧 Core concepts [#-core-concepts]

| Piece          | Role                              |
| -------------- | --------------------------------- |
| `FlatList`     | Virtualized list                  |
| `TextInput`    | Query string                      |
| `useMemo`      | Filter without extra renders cost |
| `keyExtractor` | Stable row ids                    |

## 💡 Examples [#-examples]

**FlatListSearch.tsx:**

```tsx
import { useMemo, useState } from "react";
import { FlatList, StyleSheet, Text, TextInput, View } from "react-native";

type Item = { id: string; title: string };

const DATA: Item[] = [
  { id: "1", title: "Alpha" },
  { id: "2", title: "Beta" },
  { id: "3", title: "Gamma" },
  { id: "4", title: "Delta" },
];

export function FlatListSearch() {
  const [query, setQuery] = useState("");

  const filtered = useMemo(() => {
    const q = query.trim().toLowerCase();
    if (!q) return DATA;
    return DATA.filter((item) => item.title.toLowerCase().includes(q));
  }, [query]);

  return (
    <View style={styles.container}>
      <TextInput
        value={query}
        onChangeText={setQuery}
        placeholder="Search…"
        autoCorrect={false}
        clearButtonMode="while-editing"
        style={styles.input}
      />
      <FlatList
        data={filtered}
        keyExtractor={(item) => item.id}
        keyboardShouldPersistTaps="handled"
        ListEmptyComponent={<Text>No matches</Text>}
        renderItem={({ item }) => (
          <Text style={styles.row}>{item.title}</Text>
        )}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16 },
  input: {
    borderWidth: 1,
    borderColor: "#ccc",
    borderRadius: 8,
    paddingHorizontal: 12,
    paddingVertical: 8,
    marginBottom: 12,
  },
  row: { paddingVertical: 12, fontSize: 16 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Inline `renderItem` recreates each render — extract a memoized row if profiling shows cost.
* Without `keyboardShouldPersistTaps`, taps on rows may dismiss the keyboard first.
* For remote search, debounce the query before fetching.

## 🔗 Related [#-related]

* [Form keyboard](/docs/react-native/examples/form-keyboard)
* [Dark mode toggle](/docs/react-native/examples/dark-mode-toggle)


# Form Keyboard (/docs/react-native/examples/form-keyboard)



# Form Keyboard [#form-keyboard]

*React Native · Example / how-to*

***

## 📋 Overview [#-overview]

Build a login-style form that scrolls with the keyboard using `KeyboardAvoidingView` and proper `TextInput` props.

## 🔧 Core concepts [#-core-concepts]

| Piece                            | Role                               |
| -------------------------------- | ---------------------------------- |
| `KeyboardAvoidingView`           | Shift UI above keyboard            |
| `behavior`                       | `padding` (iOS) vs platform quirks |
| `returnKeyType` / `blurOnSubmit` | Field-to-field flow                |
| `ScrollView`                     | Allow scroll when keyboard open    |

## 💡 Examples [#-examples]

**FormKeyboard.tsx:**

```tsx
import { useRef, useState } from "react";
import {
  KeyboardAvoidingView,
  Platform,
  ScrollView,
  StyleSheet,
  TextInput,
  Button,
  View,
} from "react-native";

export function FormKeyboard({ onSubmit }: { onSubmit: (email: string, password: string) => void }) {
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const passwordRef = useRef<TextInput>(null);

  return (
    <KeyboardAvoidingView
      style={styles.flex}
      behavior={Platform.OS === "ios" ? "padding" : undefined}
      keyboardVerticalOffset={Platform.OS === "ios" ? 64 : 0}
    >
      <ScrollView
        contentContainerStyle={styles.content}
        keyboardShouldPersistTaps="handled"
      >
        <TextInput
          value={email}
          onChangeText={setEmail}
          placeholder="Email"
          autoCapitalize="none"
          keyboardType="email-address"
          textContentType="emailAddress"
          returnKeyType="next"
          onSubmitEditing={() => passwordRef.current?.focus()}
          style={styles.input}
        />
        <TextInput
          ref={passwordRef}
          value={password}
          onChangeText={setPassword}
          placeholder="Password"
          secureTextEntry
          textContentType="password"
          returnKeyType="done"
          onSubmitEditing={() => onSubmit(email.trim(), password)}
          style={styles.input}
        />
        <View style={styles.button}>
          <Button title="Sign in" onPress={() => onSubmit(email.trim(), password)} />
        </View>
      </ScrollView>
    </KeyboardAvoidingView>
  );
}

const styles = StyleSheet.create({
  flex: { flex: 1 },
  content: { padding: 16, justifyContent: "center", flexGrow: 1 },
  input: {
    borderWidth: 1,
    borderColor: "#ccc",
    borderRadius: 8,
    padding: 12,
    marginBottom: 12,
  },
  button: { marginTop: 8 },
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Android often needs `android:windowSoftInputMode` in the manifest / Expo app config.
* Nesting multiple scroll views fights the keyboard — keep one scroll parent.
* `keyboardVerticalOffset` must account for headers / safe area.

## 🔗 Related [#-related]

* [FlatList search](/docs/react-native/examples/flatlist-search)
* [Dark mode toggle](/docs/react-native/examples/dark-mode-toggle)


# Examples (/docs/react-native/examples)



# Examples [#examples]

React Native notes in **Examples**.


# Build (/docs/react-native/expo/build)



# Build [#build]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**EAS Build** compiles iOS/Android binaries in the cloud (or locally) from your Expo project. Profiles in `eas.json` define development, preview, and production builds.

## 🔧 Core concepts [#-core-concepts]

* **Profiles** — `development` (dev client), `preview` (internal), `production` (store).
* **Workflow** — `eas build -p android|ios --profile <name>`.
* **Credentials** — EAS can manage keystores / distribution certs / provisioning.
* **App config** — `app.json` / `app.config.ts` + native projects via **CNG / prebuild**.
* **Local** — `eas build --local` when you need on-machine compiles.

## 💡 Examples [#-examples]

```json
// eas.json
{
  "cli": { "version": ">= 12.0.0" },
  "build": {
    "development": {
      "developmentClient": true,
      "distribution": "internal"
    },
    "preview": {
      "distribution": "internal",
      "android": { "buildType": "apk" }
    },
    "production": {
      "autoIncrement": true
    }
  },
  "submit": {
    "production": {}
  }
}
```

```shellscript
npx eas-cli login
npx eas-cli build --platform android --profile preview
npx eas-cli build --platform ios --profile production
npx eas-cli submit --platform ios --latest
```

## ⚠️ Pitfalls [#️-pitfalls]

* Building production without matching bundle ID / package + store listings.
* Forgetting `developmentClient: true` when you need custom native modules in dev.
* Native changes without rebuilding the binary (JS OTA can’t add native code).

## 🔗 Related [#-related]

* [commands.md](/docs/react-native/expo/commands) — CLI commands
* [config.md](/docs/react-native/expo/config) — app config
* [keystore\_sign.md](/docs/react-native/expo/keystore-sign) — Android signing
* [plugins.md](/docs/react-native/expo/plugins) — config plugins in builds


# Commands (/docs/react-native/expo/commands)



# Commands [#commands]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Day-to-day Expo CLI / EAS commands for local dev, prebuild, installs, and cloud builds. Prefer `npx expo` / `npx eas-cli` for pinned versions.

## 🔧 Core concepts [#-core-concepts]

* **Dev server** — `npx expo start` (tunnel / LAN / USB).
* **Platform run** — `npx expo run:android` / `run:ios` (dev client / bare).
* **Install** — `npx expo install <pkg>` aligns SDK-compatible versions.
* **Prebuild** — `npx expo prebuild` generates `ios/` / `android/`.
* **EAS** — `eas build`, `eas submit`, `eas update`, `eas credentials`.

## 💡 Examples [#-examples]

```shellscript
# Create & run
npx create-expo-app@latest MyApp
cd MyApp
npx expo start
npx expo start --tunnel

# Dependency aligned to SDK
npx expo install react-native-reanimated expo-secure-store

# Native projects + local run
npx expo prebuild
npx expo run:android
npx expo run:ios

# EAS
npx eas-cli build -p all --profile preview
npx eas-cli update --branch production --message "Fix crash"
npx eas-cli credentials
```

```shellscript
# Doctor / info
npx expo-doctor
npx expo config --type public
```

## ⚠️ Pitfalls [#️-pitfalls]

* `npm install` of Expo modules without `expo install` → version mismatches.
* Editing native folders then running prebuild without a strategy → overwrites (use plugins / CNG).
* Confusing Expo Go limits with what a **dev client** build can do.

## 🔗 Related [#-related]

* [build.md](/docs/react-native/expo/build) — EAS Build
* [config.md](/docs/react-native/expo/config) — configuration
* [filestructure.md](/docs/react-native/expo/filestructure) — project layout
* [plugins.md](/docs/react-native/expo/plugins) — native config


# Config (/docs/react-native/expo/config)



# Config [#config]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

App identity and native behavior live in &#x2A;*`app.json`*&#x2A; or dynamic &#x2A;*`app.config.js/ts`**. Config plugins mutate native projects at prebuild time. Use `extra` / `EXPO_PUBLIC_*` for non-secret runtime config.

## 🔧 Core concepts [#-core-concepts]

* **Identity** — `name`, `slug`, `version`, `orientation`, `icon`, `splash`.
* **Platform blocks** — `ios.bundleIdentifier`, `android.package`, permissions, intents.
* **Scheme** — deep linking `scheme`.
* **Plugins** — `plugins: ["expo-secure-store", [...]]`.
* **EAS** — `extra.eas.projectId`; env in EAS secrets / `.env`.

## 💡 Examples [#-examples]

```ts
// app.config.ts
import type { ExpoConfig } from "expo/config";

const config: ExpoConfig = {
  name: "MyApp",
  slug: "my-app",
  version: "1.0.0",
  scheme: "myapp",
  orientation: "portrait",
  icon: "./assets/icon.png",
  userInterfaceStyle: "automatic",
  splash: {
    image: "./assets/splash.png",
    resizeMode: "contain",
    backgroundColor: "#ffffff",
  },
  ios: {
    supportsTablet: true,
    bundleIdentifier: "com.example.myapp",
  },
  android: {
    adaptiveIcon: {
      foregroundImage: "./assets/adaptive-icon.png",
      backgroundColor: "#ffffff",
    },
    package: "com.example.myapp",
  },
  plugins: [
    "expo-secure-store",
    [
      "expo-notifications",
      { icon: "./assets/notification-icon.png", color: "#111111" },
    ],
  ],
  extra: {
    apiUrl: process.env.EXPO_PUBLIC_API_URL,
    eas: { projectId: "your-project-id" },
  },
};

export default config;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Changing package / bundle ID after store release without a migration plan.
* Secrets in `extra` or public env vars.
* Plugin options ignored until the next native rebuild.

## 🔗 Related [#-related]

* [plugins.md](/docs/react-native/expo/plugins) — config plugins
* [build.md](/docs/react-native/expo/build) — applying config in builds
* [filestructure.md](/docs/react-native/expo/filestructure) — where config lives
* [commands.md](/docs/react-native/expo/commands) — `expo config`


# Constants (/docs/react-native/expo/constants)



# Constants [#constants]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**`expo-constants`** exposes app metadata from the native manifest / config: version, `expoConfig`, installation id (where available), and EAS project fields. Use for feature flags wiring, update URLs, and debugging—not for secrets.

## 🔧 Core concepts [#-core-concepts]

| Field                                     | Role                               |
| ----------------------------------------- | ---------------------------------- |
| `Constants.expoConfig`                    | App config (name, slug, extra, …)  |
| `Constants.easConfig`                     | EAS ids when present               |
| `nativeAppVersion` / `nativeBuildVersion` | Store versions                     |
| `executionEnvironment`                    | storeClient / standalone / …       |
| `appOwnership`                            | expo / standalone (legacy nuances) |

`extra` comes from `app.config` → `expo.extra`.

## 💡 Examples [#-examples]

```tsx
import Constants from "expo-constants";
import { Text } from "react-native";

export function BuildStamp() {
  const version = Constants.expoConfig?.version ?? "dev";
  const projectId =
    Constants.expoConfig?.extra?.eas?.projectId ??
    Constants.easConfig?.projectId;
  return (
    <Text>
      v{version} · {projectId ?? "no-project"}
    </Text>
  );
}

export function apiBaseUrl() {
  return (
    Constants.expoConfig?.extra?.apiUrl ??
    process.env.EXPO_PUBLIC_API_URL ??
    ""
  );
}
```

```ts
// app.config.ts
extra: {
  apiUrl: process.env.EXPO_PUBLIC_API_URL,
  eas: { projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" },
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Putting secrets in `extra` (shipped in the binary).
* Assuming `manifest` legacy fields on new SDKs—prefer `expoConfig`.
* Using Constants for values that change per environment without rebuild/update.
* Null access before config is available—optional chain.

## 🔗 Related [#-related]

* [config.md](/docs/react-native/expo/config) — app config
* [updates\_ota.md](/docs/react-native/expo/updates-ota) — projectId
* [notifications\_expo.md](/docs/react-native/expo/notifications-expo) — push tokens
* [build.md](/docs/react-native/expo/build) — versioning
* [env](/docs/react-native/expo/config) — EXPO\_PUBLIC\_\*


# EAS Submit (/docs/react-native/expo/eas-submit)



# EAS Submit [#eas-submit]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**`eas submit`** uploads a build to App Store Connect or Google Play. Pair with `eas build` artifacts (local path or latest build on EAS). Configure credentials once; automate with CI profiles in `eas.json`.

## 🔧 Core concepts [#-core-concepts]

| Piece                     | Role                  |
| ------------------------- | --------------------- |
| `eas submit -p ios`       | ASC upload            |
| `eas submit -p android`   | Play upload           |
| `eas.json` submit profile | Track, release status |
| ASC API key / Apple ID    | iOS auth              |
| Google service account    | Play API JSON         |
| `--latest`                | Use latest EAS build  |

Submit ≠ review: you still complete store listing / review in consoles.

## 💡 Examples [#-examples]

```json
// eas.json (excerpt)
{
  "cli": { "version": ">= 12.0.0" },
  "build": {
    "production": { "channel": "production" }
  },
  "submit": {
    "production": {
      "ios": {
        "ascAppId": "1234567890"
      },
      "android": {
        "serviceAccountKeyPath": "./play-service-account.json",
        "track": "internal"
      }
    }
  }
}
```

```shellscript
eas build -p ios --profile production
eas submit -p ios --profile production --latest

eas build -p android --profile production
eas submit -p android --profile production --path ./app-release.aab
```

## ⚠️ Pitfalls [#️-pitfalls]

* Submitting a build with wrong version/build number.
* Committing Play/ASC private keys to git.
* Using `production` track before internal testing.
* Assuming submit publishes immediately—manual rollout/review may remain.

## 🔗 Related [#-related]

* [build.md](/docs/react-native/expo/build) — EAS Build
* [keystore\_sign.md](/docs/react-native/expo/keystore-sign) — Android signing
* [updates\_ota.md](/docs/react-native/expo/updates-ota) — JS updates vs binaries
* [commands.md](/docs/react-native/expo/commands) — CLI
* [config.md](/docs/react-native/expo/config) — version / bundle ids


# File structure (/docs/react-native/expo/filestructure)



# File structure [#file-structure]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Expo apps are mostly JS/TS under the project root (or `src/`), with config at the top level. Native `ios/` / `android/` appear after **prebuild** or in bare workflows; prefer Continuous Native Generation + plugins over hand-editing when possible.

## 🔧 Core concepts [#-core-concepts]

* **Entry** — `package.json` `"main"` → `expo-router/entry` or `node_modules/expo/AppEntry.js`.
* **Router** — Expo Router uses `app/` file-based routes.
* **Assets** — `assets/` for icons, splash, fonts.
* **Config** — `app.config.ts`, `eas.json`, `babel.config.js`, `metro.config.js`.
* **Native** — generated `ios/`, `android/` (gitignore in managed CNG setups).

## 💡 Examples [#-examples]

```plaintext
MyApp/
  app/                 # Expo Router screens
    _layout.tsx
    index.tsx
    settings.tsx
  assets/
    icon.png
    splash.png
  src/
    components/
    lib/
  app.config.ts
  eas.json
  package.json
  tsconfig.json
  # after prebuild:
  ios/
  android/
```

```json
// package.json (Router)
{
  "main": "expo-router/entry",
  "scripts": {
    "start": "expo start",
    "android": "expo run:android",
    "ios": "expo run:ios"
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Committing generated native projects while also relying on prebuild — pick a workflow.
* Putting screens outside `app/` when using Expo Router without registering them.
* Huge `assets/` without compression → install size.

## 🔗 Related [#-related]

* [config.md](/docs/react-native/expo/config) — app config
* [commands.md](/docs/react-native/expo/commands) — prebuild / start
* [plugins.md](/docs/react-native/expo/plugins) — native customization
* [build.md](/docs/react-native/expo/build) — CI builds


# Gradle (/docs/react-native/expo/gradle)



# Gradle [#gradle]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Android builds use **Gradle** inside `android/` (after prebuild) or on EAS builders. Expo abstracts most of this; touch Gradle for custom native modules, packaging options, or troubleshooting.

## 🔧 Core concepts [#-core-concepts]

* **Root** — `android/build.gradle`, `android/settings.gradle`, `gradle.properties`.
* **App module** — `android/app/build.gradle` (`applicationId`, signing, `minSdk`).
* **Expo autolinking** — native modules linked via Expo / RN Gradle plugins.
* **Properties** — `org.gradle.jvmargs`, `hermesEnabled`, architectures.
* **EAS** — cloud images run Gradle; override via `eas.json` env / `expo-build-properties` plugin.

## 💡 Examples [#-examples]

```ts
// app.config.ts — prefer plugin over hand-editing Gradle
plugins: [
  [
    "expo-build-properties",
    {
      android: {
        minSdkVersion: 24,
        compileSdkVersion: 35,
        targetSdkVersion: 35,
        kotlinVersion: "1.9.24",
      },
    },
  ],
],
```

```properties
# android/gradle.properties (generated — customize via plugins when possible)
hermesEnabled=true
newArchEnabled=true
```

```shellscript
cd android && ./gradlew assembleRelease
# or via Expo
npx expo run:android --variant release
```

## ⚠️ Pitfalls [#️-pitfalls]

* Manual Gradle edits wiped by `expo prebuild --clean` unless reflected in config plugins.
* Mismatched JDK / AGP versions vs Expo SDK expectations.
* Enabling New Architecture without compatible libraries.

## 🔗 Related [#-related]

* [build.md](/docs/react-native/expo/build) — EAS Android builds
* [keystore\_sign.md](/docs/react-native/expo/keystore-sign) — signing configs
* [plugins.md](/docs/react-native/expo/plugins) — build-properties plugin
* [commands.md](/docs/react-native/expo/commands) — `expo run:android`


# Image Picker (/docs/react-native/expo/image-picker)



# Image Picker [#image-picker]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**`expo-image-picker`** launches the system gallery or camera to pick images/videos. Request media permissions, then `launchImageLibraryAsync` / `launchCameraAsync`. Returns local `uri`s for upload or display.

## 🔧 Core concepts [#-core-concepts]

| API                                   | Role                                                                |
| ------------------------------------- | ------------------------------------------------------------------- |
| `requestMediaLibraryPermissionsAsync` | Gallery                                                             |
| `requestCameraPermissionsAsync`       | Camera                                                              |
| `launchImageLibraryAsync`             | Pick existing                                                       |
| `launchCameraAsync`                   | Capture                                                             |
| Options                               | `mediaTypes`, `allowsEditing`, `quality`, `allowsMultipleSelection` |

Config plugin for photos permission strings.

## 💡 Examples [#-examples]

```tsx
import * as ImagePicker from "expo-image-picker";
import { useState } from "react";
import { Image, Pressable, Text } from "react-native";

export function AvatarPicker() {
  const [uri, setUri] = useState<string | null>(null);

  async function pick() {
    const perm = await ImagePicker.requestMediaLibraryPermissionsAsync();
    if (!perm.granted) return;
    const result = await ImagePicker.launchImageLibraryAsync({
      mediaTypes: ["images"],
      allowsEditing: true,
      aspect: [1, 1],
      quality: 0.8,
    });
    if (!result.canceled) setUri(result.assets[0]?.uri ?? null);
  }

  return (
    <>
      <Pressable onPress={pick}>
        <Text>Choose photo</Text>
      </Pressable>
      {uri ? (
        <Image source={{ uri }} style={{ width: 96, height: 96 }} />
      ) : null}
    </>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Using deprecated `MediaTypeOptions` enums on newer SDKs—prefer `mediaTypes` arrays.
* Ignoring `canceled` results.
* Uploading full-resolution images without compression.
* Missing Info.plist / Android permission messages.

## 🔗 Related [#-related]

* [../camera.md](/docs/react-native/camera) — live camera
* [../image.md](/docs/react-native/image) — display
* [../permissions.md](/docs/react-native/permissions) — permission UX
* [config.md](/docs/react-native/expo/config) — plugins
* [secure\_store.md](/docs/react-native/expo/secure-store) — not for images


# Expo (/docs/react-native/expo)



# Expo [#expo]

React Native notes in **Expo**.


# Keystore & signing (/docs/react-native/expo/keystore-sign)



# Keystore & signing [#keystore--signing]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Android release builds must be **signed** with an upload/app signing keystore. EAS can generate and store credentials; Play App Signing uses Google’s key for distribution while you keep an upload key.

## 🔧 Core concepts [#-core-concepts]

* **Keystore** — `.jks` / `.keystore` with alias + passwords.
* **EAS-managed** — default for new projects; downloadable via `eas credentials`.
* **Local signing** — `android/app` signingConfigs for local release builds.
* **iOS counterpart** — distribution cert + provisioning profile (also via EAS).
* **Backup** — losing the upload key complicates Play updates (recovery possible with Play App Signing).

## 💡 Examples [#-examples]

```shellscript
# Inspect / manage credentials
npx eas-cli credentials -p android

# Production build (EAS uses stored keystore)
npx eas-cli build -p android --profile production
```

```json
// eas.json — credentialsSource
{
  "build": {
    "production": {
      "android": {
        "credentialsSource": "remote"
      }
    }
  }
}
```

```groovy
// Local sketch — prefer EAS; only for bare local releases
android {
  signingConfigs {
    release {
      storeFile file("release.keystore")
      storePassword System.getenv("KEYSTORE_PASSWORD")
      keyAlias System.getenv("KEY_ALIAS")
      keyPassword System.getenv("KEY_PASSWORD")
    }
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Committing keystores or passwords to git.
* Creating a new keystore for an existing Play listing without updating upload key.
* Mixing debug and release signing when testing IAP / push.

## 🔗 Related [#-related]

* [build.md](/docs/react-native/expo/build) — release builds
* [gradle.md](/docs/react-native/expo/gradle) — Android build system
* [commands.md](/docs/react-native/expo/commands) — `eas credentials`
* [config.md](/docs/react-native/expo/config) — package name must stay stable


# Linking (Expo) (/docs/react-native/expo/linking-expo)



# Linking (Expo) [#linking-expo]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

Expo linking builds on RN `Linking&#x60; with &#x2A;*`expo-linking`** helpers and Expo Router path integration. Set `scheme` in app config; use universal links / app links for https. Create URLs with `Linking.createURL` for consistent env behavior.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                                 |
| --------------- | ------------------------------------ |
| `scheme`        | Custom URL scheme in config          |
| `createURL`     | Build deep link for current env      |
| `parse`         | Parse path/query                     |
| Expo Router     | File paths map to URLs               |
| Universal links | `associatedDomains` / intent filters |

Dev client / Go vs production URLs differ—`createURL` helps.

## 💡 Examples [#-examples]

```tsx
import * as Linking from "expo-linking";
import { useEffect } from "react";
import { router } from "expo-router";

const prefix = Linking.createURL("/");

export function useDeepLinks() {
  useEffect(() => {
    function handle(url: string) {
      const { path, queryParams } = Linking.parse(url);
      if (path?.startsWith("post/")) {
        router.push(`/post/${queryParams?.id ?? ""}`);
      }
    }
    Linking.getInitialURL().then((url) => url && handle(url));
    const sub = Linking.addEventListener("url", ({ url }) => handle(url));
    return () => sub.remove();
  }, []);
}

export function shareLink(id: string) {
  return Linking.createURL(`/post/${id}`);
}
```

```json
{
  "expo": {
    "scheme": "myapp",
    "ios": { "associatedDomains": ["applinks:example.com"] },
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [{ "scheme": "https", "host": "example.com", "pathPrefix": "/" }],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Hardcoding `myapp://` without `createURL` (breaks in Expo Go).
* Missing AASA / assetlinks verification for https links.
* Not testing cold start (`getInitialURL`).
* Scheme typos between config and marketing links.

## 🔗 Related [#-related]

* [router.md](/docs/react-native/expo/router) — Expo Router
* [config.md](/docs/react-native/expo/config) — scheme
* [../linking.md](/docs/react-native/linking) — RN Linking
* [../deeplinking.md](/docs/react-native/deeplinking) — deep links
* [../navigation.md](/docs/react-native/navigation) — navigation linking


# Notifications (Expo) (/docs/react-native/expo/notifications-expo)



# Notifications (Expo) [#notifications-expo]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**`expo-notifications`** handles local notifications, push permission, device push tokens, and listeners. Push delivery uses Expo push service or raw FCM/APNs. Configure icons/sounds via config plugin; request permissions at a sensible moment.

## 🔧 Core concepts [#-core-concepts]

| Piece          | Role                               |
| -------------- | ---------------------------------- |
| Permissions    | `requestPermissionsAsync`          |
| Device token   | `getExpoPushTokenAsync`            |
| Local schedule | `scheduleNotificationAsync`        |
| Listeners      | received / response (tap)          |
| Channels       | Android notification channels      |
| Plugin         | `expo-notifications` in `app.json` |

Physical device required for remote push.

## 💡 Examples [#-examples]

```tsx
import { useEffect, useRef } from "react";
import * as Notifications from "expo-notifications";
import Constants from "expo-constants";
import { Platform } from "react-native";

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowBanner: true,
    shouldShowList: true,
    shouldPlaySound: false,
    shouldSetBadge: false,
  }),
});

export async function registerForPush() {
  const { status } = await Notifications.requestPermissionsAsync();
  if (status !== "granted") return null;
  if (Platform.OS === "android") {
    await Notifications.setNotificationChannelAsync("default", {
      name: "default",
      importance: Notifications.AndroidImportance.DEFAULT,
    });
  }
  const projectId =
    Constants.expoConfig?.extra?.eas?.projectId ??
    Constants.easConfig?.projectId;
  return Notifications.getExpoPushTokenAsync({ projectId });
}

export function useNotificationObserver() {
  const responseListener = useRef<Notifications.EventSubscription | null>(null);
  useEffect(() => {
    responseListener.current =
      Notifications.addNotificationResponseReceivedListener((response) => {
        console.log(response.notification.request.content.data);
      });
    return () => responseListener.current?.remove();
  }, []);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Testing push on simulator/emulator without support.
* Missing EAS `projectId` for Expo tokens.
* Not creating Android channels → silent/wrong importance.
* Asking permission on first launch without context.

## 🔗 Related [#-related]

* [config.md](/docs/react-native/expo/config) — plugin / projectId
* [../notification.md](/docs/react-native/notification) — general notes
* [../permissions.md](/docs/react-native/permissions) — permission UX
* [linking\_expo.md](/docs/react-native/expo/linking-expo) — open from tap
* [constants.md](/docs/react-native/expo/constants) — project config


# Plugins (/docs/react-native/expo/plugins)



# Plugins [#plugins]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Config plugins** are JS functions that modify native projects during **prebuild**. They let managed/CNG apps add permissions, activities, Podfile changes, and Gradle tweaks without maintaining permanent `ios/` / `android/` forks.

## 🔧 Core concepts [#-core-concepts]

* **Declaration** — `plugins` array in `app.config`.
* **With options** — `["expo-camera", \{ cameraPermission: "..." \}]`.
* **Autolinking** — many `expo-*` packages ship a plugin; still list them when options are required.
* **Custom plugins** — `plugins/withMyNativeChange.js` using `@expo/config-plugins` mods.
* **Apply** — changes take effect on next `prebuild` / EAS Build, not in Expo Go unless the feature is already in the client.

## 💡 Examples [#-examples]

```ts
// app.config.ts
export default {
  expo: {
    plugins: [
      [
        "expo-camera",
        {
          cameraPermission: "Allow MyApp to take photos",
          microphonePermission: "Allow MyApp to record audio",
          recordAudioAndroid: true,
        },
      ],
      "expo-secure-store",
      ["./plugins/withAndroidQueries", { packages: ["com.android.vending"] }],
    ],
  },
};
```

```js
// plugins/withAndroidQueries.js
const { withAndroidManifest } = require("@expo/config-plugins");

function withAndroidQueries(config, { packages = [] }) {
  return withAndroidManifest(config, (cfg) => {
    const manifest = cfg.modResults.manifest;
    // mutate queries / intents as needed
    void packages;
    return cfg;
  });
}

module.exports = withAndroidQueries;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Expecting plugin native changes inside Expo Go — need a **dev client** or store build.
* Forgetting to rebuild after adding a plugin.
* Hand-editing `ios/`/`android/` then losing changes on `--clean` prebuild.

## 🔗 Related [#-related]

* [config.md](/docs/react-native/expo/config) — where plugins are listed
* [build.md](/docs/react-native/expo/build) — builds apply plugins
* [commands.md](/docs/react-native/expo/commands) — prebuild
* [gradle.md](/docs/react-native/expo/gradle) — Android mods


# Router (/docs/react-native/expo/router)



# Router [#router]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**Expo Router** is a file-based router built on React Navigation. Files under `app/` become routes; layouts wrap segments; deep links match paths. Use typed routes and `Link` / `router` for navigation.

## 🔧 Core concepts [#-core-concepts]

| Piece                  | Role                           |
| ---------------------- | ------------------------------ |
| `app/_layout.tsx`      | Root layout                    |
| `app/index.tsx`        | `/`                            |
| `app/[id].tsx`         | Dynamic segment                |
| `(groups)`             | Organizational, no URL segment |
| `Link` / `router.push` | Navigation                     |
| `Stack` / `Tabs`       | Navigators in layouts          |
| `+not-found`           | 404                            |

Enable plugin `"expo-router"` in app config; entry via `expo-router/entry`.

## 💡 Examples [#-examples]

```tsx
// app/_layout.tsx
import { Stack } from "expo-router";

export default function Layout() {
  return (
    <Stack>
      <Stack.Screen name="index" options={{ title: "Home" }} />
      <Stack.Screen name="post/[id]" options={{ title: "Post" }} />
    </Stack>
  );
}
```

```tsx
// app/index.tsx
import { Link } from "expo-router";
import { Text, View } from "react-native";

export default function Home() {
  return (
    <View>
      <Link href="/post/42">Open post</Link>
    </View>
  );
}
```

```tsx
// app/post/[id].tsx
import { useLocalSearchParams, router } from "expo-router";
import { Pressable, Text } from "react-native";

export default function Post() {
  const { id } = useLocalSearchParams<{ id: string }>();
  return (
    <>
      <Text>Post {id}</Text>
      <Pressable onPress={() => router.back()}>
        <Text>Back</Text>
      </Pressable>
    </>
  );
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Mixing React Navigation containers manually with Expo Router.
* Wrong folder names → unexpected URLs.
* Forgetting `scheme` in config for deep links.
* Heavy work in root layout blocking all screens.

## 🔗 Related [#-related]

* [config.md](/docs/react-native/expo/config) — scheme / plugins
* [linking\_expo.md](/docs/react-native/expo/linking-expo) — deep links
* [filestructure.md](/docs/react-native/expo/filestructure) — app dir
* [../navigation.md](/docs/react-native/navigation) — React Navigation concepts
* [../deeplinking.md](/docs/react-native/deeplinking) — native linking


# Secure Store (/docs/react-native/expo/secure-store)



# Secure Store [#secure-store]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**`expo-secure-store`** stores small secrets in iOS Keychain / Android Keystore. Use for tokens and keys—not large blobs. AsyncStorage is not secure. Configure the config plugin when required by your SDK version.

## 🔧 Core concepts [#-core-concepts]

| API                        | Role                                          |
| -------------------------- | --------------------------------------------- |
| `setItemAsync(key, value)` | Save                                          |
| `getItemAsync(key)`        | Read                                          |
| `deleteItemAsync(key)`     | Remove                                        |
| Options                    | `keychainAccessible`, biometrics auth options |

Size limits apply; errors on unavailable hardware/secure lock screen policies.

## 💡 Examples [#-examples]

```tsx
import * as SecureStore from "expo-secure-store";

const TOKEN_KEY = "session_token";

export async function saveToken(token: string) {
  await SecureStore.setItemAsync(TOKEN_KEY, token);
}

export async function loadToken() {
  return SecureStore.getItemAsync(TOKEN_KEY);
}

export async function clearToken() {
  await SecureStore.deleteItemAsync(TOKEN_KEY);
}
```

**With auth prompt (when supported):**

```tsx
await SecureStore.setItemAsync("pin", value, {
  requireAuthentication: true,
  authenticationPrompt: "Unlock secrets",
});
```

## ⚠️ Pitfalls [#️-pitfalls]

* Storing JWTs in AsyncStorage instead.
* Large JSON documents—use file encryption or server.
* Assuming values survive app uninstall (platform-specific).
* Missing error handling when device is locked / biometrics fail.

## 🔗 Related [#-related]

* [../biometrics.md](/docs/react-native/biometrics) — local auth
* [../storage.md](/docs/react-native/storage) — insecure storage
* [config.md](/docs/react-native/expo/config) — plugins
* [../appstate.md](/docs/react-native/appstate) — lock on background
* [plugins.md](/docs/react-native/expo/plugins) — native config


# Updates (OTA) (/docs/react-native/expo/updates-ota)



# Updates (OTA) [#updates-ota]

*Expo · Reference cheat sheet*

***

## 📋 Overview [#-overview]

**EAS Update** delivers JavaScript/asset over-the-air updates without a full store release—when native code is unchanged. Configure `expo-updates`, publish with `eas update`, and channel/branch to builds. Native module changes still need a new binary.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                                |
| --------------- | ----------------------------------- |
| Runtime version | Compatibility gate with binaries    |
| Channel         | Maps builds → update stream         |
| Branch          | Git-like update stream              |
| `expo-updates`  | Fetch/apply JS bundles              |
| Rollback        | Republish previous / serve rollback |

Policies: check on launch, reload when appropriate.

## 💡 Examples [#-examples]

```json
// app.json (excerpt)
{
  "expo": {
    "runtimeVersion": { "policy": "appVersion" },
    "updates": {
      "url": "https://u.expo.dev/<project-id>"
    },
    "extra": {
      "eas": { "projectId": "<project-id>" }
    }
  }
}
```

```shellscript
eas update --branch production --message "Fix checkout copy"
eas update:list --branch production
```

```tsx
import * as Updates from "expo-updates";
import { useEffect } from "react";

export function useApplyUpdate() {
  useEffect(() => {
    (async () => {
      if (__DEV__) return;
      const result = await Updates.checkForUpdateAsync();
      if (result.isAvailable) {
        await Updates.fetchUpdateAsync();
        await Updates.reloadAsync();
      }
    })();
  }, []);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Shipping native changes via OTA—won't load; binary required.
* Mismatched `runtimeVersion` → updates ignored.
* Forcing reload mid-checkout without UX.
* Testing only in dev (Updates disabled in `__DEV__`).

## 🔗 Related [#-related]

* [build.md](/docs/react-native/expo/build) — binaries
* [config.md](/docs/react-native/expo/config) — updates URL
* [eas\_submit.md](/docs/react-native/expo/eas-submit) — store submit
* [commands.md](/docs/react-native/expo/commands) — EAS CLI
* [plugins.md](/docs/react-native/expo/plugins) — native config


# Examples (/docs/sql/examples)



# Examples [#examples]

SQL notes in **Examples**.


# Report Join (/docs/sql/examples/report-join)



# Report Join [#report-join]

*SQL · Example / how-to*

***

## 📋 Overview [#-overview]

Build a sales report by joining orders, customers, and products, then aggregating totals per customer.

## 🔧 Core concepts [#-core-concepts]

| Piece        | Role                          |
| ------------ | ----------------------------- |
| `INNER JOIN` | Match related rows            |
| `LEFT JOIN`  | Keep parents without children |
| `GROUP BY`   | Aggregate per key             |
| `ORDER BY`   | Rank the report               |

## 💡 Examples [#-examples]

```sql
-- Schema sketch
-- customers(id, name)
-- products(id, name, unit_price)
-- orders(id, customer_id, created_at)
-- order_items(id, order_id, product_id, qty)

SELECT
  c.id AS customer_id,
  c.name AS customer_name,
  COUNT(DISTINCT o.id) AS order_count,
  COALESCE(SUM(oi.qty * p.unit_price), 0) AS revenue
FROM customers AS c
LEFT JOIN orders AS o
  ON o.customer_id = c.id
LEFT JOIN order_items AS oi
  ON oi.order_id = o.id
LEFT JOIN products AS p
  ON p.id = oi.product_id
WHERE o.created_at >= DATE '2026-01-01'
   OR o.id IS NULL
GROUP BY c.id, c.name
ORDER BY revenue DESC, customer_name ASC;
```

**Only customers with orders:**

```sql
SELECT c.name, SUM(oi.qty * p.unit_price) AS revenue
FROM customers c
INNER JOIN orders o ON o.customer_id = c.id
INNER JOIN order_items oi ON oi.order_id = o.id
INNER JOIN products p ON p.id = oi.product_id
GROUP BY c.name
HAVING SUM(oi.qty * p.unit_price) > 100
ORDER BY revenue DESC;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Joining to line items before aggregating can duplicate order-level rows.
* `WHERE` on the right table of a `LEFT JOIN` can accidentally turn it into an inner join.
* Always qualify columns (`c.name`) when names collide.

## 🔗 Related [#-related]

* [Upsert inventory](/docs/sql/examples/upsert-inventory)
* [Window rank](/docs/sql/examples/window-rank)


# Upsert Inventory (/docs/sql/examples/upsert-inventory)



# Upsert Inventory [#upsert-inventory]

*SQL · Example / how-to*

***

## 📋 Overview [#-overview]

Insert or update inventory quantities atomically with `INSERT ... ON CONFLICT` (PostgreSQL) or equivalent upsert patterns.

## 🔧 Core concepts [#-core-concepts]

| Piece         | Role                          |
| ------------- | ----------------------------- |
| Unique key    | Conflict target (SKU)         |
| `ON CONFLICT` | Upsert branch                 |
| `EXCLUDED`    | Proposed row values           |
| Atomicity     | Avoid racey read-modify-write |

## 💡 Examples [#-examples]

**PostgreSQL:**

```sql
CREATE TABLE inventory (
  sku TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  qty INTEGER NOT NULL CHECK (qty >= 0),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

INSERT INTO inventory (sku, name, qty)
VALUES ('ABC-1', 'Widget', 10)
ON CONFLICT (sku) DO UPDATE
SET
  name = EXCLUDED.name,
  qty = inventory.qty + EXCLUDED.qty,
  updated_at = NOW()
RETURNING sku, name, qty, updated_at;
```

**Set absolute quantity instead of increment:**

```sql
INSERT INTO inventory (sku, name, qty)
VALUES ('ABC-1', 'Widget', 25)
ON CONFLICT (sku) DO UPDATE
SET name = EXCLUDED.name,
    qty = EXCLUDED.qty,
    updated_at = NOW();
```

**SQLite (similar):**

```sql
INSERT INTO inventory (sku, name, qty)
VALUES ('ABC-1', 'Widget', 10)
ON CONFLICT(sku) DO UPDATE SET
  qty = inventory.qty + excluded.qty,
  name = excluded.name;
```

## ⚠️ Pitfalls [#️-pitfalls]

* Without a unique constraint, `ON CONFLICT` cannot target the row.
* Increment vs replace semantics differ — document which you mean.
* Check constraints still apply on the final row after update.

## 🔗 Related [#-related]

* [Report join](/docs/sql/examples/report-join)
* [Window rank](/docs/sql/examples/window-rank)


# Window Rank (/docs/sql/examples/window-rank)



# Window Rank [#window-rank]

*SQL · Example / how-to*

***

## 📋 Overview [#-overview]

Rank rows within partitions using window functions (`RANK`, `DENSE_RANK`, `ROW_NUMBER`) for leaderboards and top-N-per-group queries.

## 🔧 Core concepts [#-core-concepts]

| Piece                   | Role                     |
| ----------------------- | ------------------------ |
| `OVER (PARTITION BY …)` | Group without collapsing |
| `ORDER BY` in window    | Rank order               |
| `ROW_NUMBER`            | Unique sequence          |
| `RANK` / `DENSE_RANK`   | Tie handling             |

## 💡 Examples [#-examples]

```sql
-- scores(player_id, game, points, played_at)

SELECT
  player_id,
  game,
  points,
  ROW_NUMBER() OVER (
    PARTITION BY game
    ORDER BY points DESC, played_at ASC
  ) AS row_num,
  RANK() OVER (
    PARTITION BY game
    ORDER BY points DESC
  ) AS rank,
  DENSE_RANK() OVER (
    PARTITION BY game
    ORDER BY points DESC
  ) AS dense_rank
FROM scores;
```

**Top 3 per game:**

```sql
WITH ranked AS (
  SELECT
    player_id,
    game,
    points,
    ROW_NUMBER() OVER (
      PARTITION BY game
      ORDER BY points DESC, played_at ASC
    ) AS rn
  FROM scores
)
SELECT player_id, game, points
FROM ranked
WHERE rn <= 3
ORDER BY game, rn;
```

## ⚠️ Pitfalls [#️-pitfalls]

* `RANK` skips numbers after ties; `DENSE_RANK` does not; `ROW_NUMBER` never ties.
* Filtering on window results needs a subquery/CTE — `WHERE rank &lt;= 3` is invalid on the same select level in most engines.
* Missing `ORDER BY` in `OVER` makes ranking nondeterministic.

## 🔗 Related [#-related]

* [Report join](/docs/sql/examples/report-join)
* [Upsert inventory](/docs/sql/examples/upsert-inventory)


# Examples (/docs/typescript/examples)



# Examples [#examples]

TypeScript notes in **Examples**.


# Narrowing Demo (/docs/typescript/examples/narrowing-demo)



# Narrowing Demo [#narrowing-demo]

*Typescript · Example / how-to*

***

## 📋 Overview [#-overview]

Use control-flow narrowing (`typeof`, `in`, discriminated unions) so TypeScript knows which fields are safe after a check.

## 🔧 Core concepts [#-core-concepts]

| Piece               | Role                       |
| ------------------- | -------------------------- |
| `typeof`            | Narrow primitives          |
| `in` operator       | Narrow object shapes       |
| Discriminated union | Shared `kind` / `type` tag |
| Exhaustiveness      | `never` in default         |

## 💡 Examples [#-examples]

**narrowing\_demo.ts:**

```typescript
type Success = { kind: "ok"; value: string };
type Failure = { kind: "err"; error: Error };
type Result = Success | Failure;

function handle(result: Result): string {
  switch (result.kind) {
    case "ok":
      return result.value.toUpperCase();
    case "err":
      return `failed: ${result.error.message}`;
    default: {
      const _exhaustive: never = result;
      return _exhaustive;
    }
  }
}

function label(input: string | number | { name: string }): string {
  if (typeof input === "string") return input.trim();
  if (typeof input === "number") return input.toFixed(2);
  if ("name" in input) return input.name;
  return "unknown";
}

function readId(payload: unknown): number | null {
  if (typeof payload !== "object" || payload === null) return null;
  if (!("id" in payload)) return null;
  const id = (payload as { id: unknown }).id;
  return typeof id === "number" ? id : null;
}

console.log(handle({ kind: "ok", value: "hello" }));
console.log(label(42));
console.log(readId({ id: 7 }));
```

## ⚠️ Pitfalls [#️-pitfalls]

* `typeof null === "object"` — always null-check objects.
* Casting with `as` skips narrowing; prefer guards.
* Forgetting a union member breaks exhaustiveness — keep the `never` default.

## 🔗 Related [#-related]

* [Typed fetch](/docs/typescript/examples/typed-fetch)
* [Zod form](/docs/typescript/examples/zod-form)


# Typed Fetch (/docs/typescript/examples/typed-fetch)



# Typed Fetch [#typed-fetch]

*Typescript · Example / how-to*

***

## 📋 Overview [#-overview]

Wrap `fetch` with generics and runtime checks so callers get typed JSON without trusting the network blindly.

## 🔧 Core concepts [#-core-concepts]

| Piece           | Role                         |
| --------------- | ---------------------------- |
| Generics        | `fetchJson<T>()` return type |
| Type guards     | Narrow unknown JSON          |
| `Response.ok`   | HTTP error handling          |
| `unknown` first | Safer than `any`             |

## 💡 Examples [#-examples]

**typed\_fetch.ts:**

```typescript
export class HttpError extends Error {
  constructor(
    readonly status: number,
    message: string,
  ) {
    super(message);
    this.name = "HttpError";
  }
}

export async function fetchJson<T>(
  url: string,
  init?: RequestInit,
  guard?: (data: unknown) => data is T,
): Promise<T> {
  const response = await fetch(url, {
    ...init,
    headers: { Accept: "application/json", ...init?.headers },
  });
  if (!response.ok) {
    throw new HttpError(response.status, `HTTP ${response.status} for ${url}`);
  }
  const data: unknown = await response.json();
  if (guard && !guard(data)) {
    throw new Error(`Unexpected JSON shape from ${url}`);
  }
  return data as T;
}

type User = { id: number; email: string; name: string };

function isUser(data: unknown): data is User {
  if (typeof data !== "object" || data === null) return false;
  const u = data as Record<string, unknown>;
  return (
    typeof u.id === "number" &&
    typeof u.email === "string" &&
    typeof u.name === "string"
  );
}

async function main() {
  const user = await fetchJson<User>(
    "https://jsonplaceholder.typicode.com/users/1",
    undefined,
    isUser,
  );
  console.log(user.email);
}

main();
```

## ⚠️ Pitfalls [#️-pitfalls]

* `as T` without a guard lies to the type checker — prefer a type guard or Zod.
* Generics do not validate at runtime by themselves.
* Abort signals and timeouts still need to be passed via `init`.

## 🔗 Related [#-related]

* [Narrowing demo](/docs/typescript/examples/narrowing-demo)
* [Zod form](/docs/typescript/examples/zod-form)


# Zod Form (/docs/typescript/examples/zod-form)



# Zod Form [#zod-form]

*Typescript · Example / how-to*

***

## 📋 Overview [#-overview]

Validate form input with Zod: define a schema, parse values, and map field errors for the UI.

## 🔧 Core concepts [#-core-concepts]

| Piece                   | Role                    |
| ----------------------- | ----------------------- |
| `z.object`              | Schema for form fields  |
| `safeParse`             | Non-throwing validation |
| `flatten().fieldErrors` | Per-field messages      |
| `z.infer`               | Derive TypeScript type  |

## 💡 Examples [#-examples]

**zod\_form.ts:**

```typescript
import { z } from "zod";

const SignupSchema = z
  .object({
    email: z.string().email("Invalid email"),
    password: z.string().min(8, "At least 8 characters"),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: "Passwords must match",
    path: ["confirm"],
  });

type SignupInput = z.infer<typeof SignupSchema>;

export function validateSignup(raw: unknown): {
  ok: true;
  data: SignupInput;
} | {
  ok: false;
  fieldErrors: Record<string, string[]>;
  formErrors: string[];
} {
  const result = SignupSchema.safeParse(raw);
  if (result.success) {
    return { ok: true, data: result.data };
  }
  const flat = result.error.flatten();
  return {
    ok: false,
    fieldErrors: flat.fieldErrors,
    formErrors: flat.formErrors,
  };
}

// Example usage with FormData-like object
const outcome = validateSignup({
  email: "ada@example.com",
  password: "hunter2!!",
  confirm: "hunter2!!",
});

if (outcome.ok) {
  console.log("create user", outcome.data.email);
} else {
  console.log(outcome.fieldErrors);
}
```

## ⚠️ Pitfalls [#️-pitfalls]

* Use `safeParse` in UI code — `parse` throws and is awkward in forms.
* Refine/superRefine errors need a `path` to attach to a field.
* Coerce numbers from inputs with `z.coerce.number()` when values are strings.

## 🔗 Related [#-related]

* [Typed fetch](/docs/typescript/examples/typed-fetch)
* [Narrowing demo](/docs/typescript/examples/narrowing-demo)
* [../zod-integration.md](/docs/typescript/zod-integration)