diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000000..7a2fd0898a454 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,342 @@ +# Guide for Copilot + +This document provides a concise guide for writing TypeScript fourslash tests and compiler tests, along with build instructions. + +## Build Instructions Summary + +### Setup +1. Install Node.js (current or LTS) +2. Clone the repository: `git clone --depth=1 https://github.com/microsoft/TypeScript` +3. Install dependencies: `npm ci` + +### Common Build Tasks +```bash +npx hereby local # Build the compiler into built/local +npx hereby clean # Delete the built compiler +npx hereby tests # Build the test infrastructure +npx hereby runtests # Run all tests +npx hereby runtests-parallel # Run tests in parallel 🚨 MANDATORY BEFORE FINISHING! +npx hereby runtests --runner=fourslash # Run only fourslash tests +npx hereby runtests --runner=compiler # Run only compiler tests +npx hereby runtests --tests= # Run specific test +npx hereby baseline-accept # Accept new test baselines +npx hereby lint # Run eslint 🚨 MANDATORY BEFORE FINISHING! +npx hereby format # Run code formatting 🚨 MANDATORY BEFORE FINISHING! +``` + +## Fourslash Test Syntax Guide + +Fourslash tests are interactive TypeScript language service tests. They validate IDE features like completions, quick info, navigation, and refactoring. + +### Basic Structure +```typescript +/// + +////code goes here with /*markers*/ + +// Test assertions go here +``` + +### Key Syntax Elements + +#### 1. Source Code Definition +Use `////` to define source code lines: +```typescript +////function foo(x: number) { +//// return x + 1; +////} +////let result = foo(/*marker*/42); +``` + +#### 2. Markers for Positioning +Use `/**/` for anonymous markers or `/*name*/` for named markers: +```typescript +////let x = /*1*/someValue; +////let y = /*cursor*/anotherValue; +``` + +#### 3. Multi-file Tests +Use `// @Filename:` to define multiple files: +```typescript +// @Filename: /a.ts +////export const value = 42; + +// @Filename: /b.ts +////import { value } from './a'; +////console.log(/*marker*/value); +``` + +#### 4. Ranges +Use `[|text|]` to define text ranges: +```typescript +////function test() { +//// [|return 42;|] +////} +``` + +### Common API Patterns + +#### Navigation & Positioning +```typescript +goTo.marker("markerName"); // Navigate to marker +goTo.marker(); // Navigate to anonymous marker /**/ +``` + +#### Verification (Prefer these over baselines) +```typescript +verify.currentLineContentIs("expected content"); +verify.completions({ includes: "itemName" }); +verify.completions({ excludes: "itemName" }); +verify.quickInfoIs("expected info"); +verify.codeFix({ + description: "Fix description", + newFileContent: "expected content after fix" +}); +``` + +#### Completions Testing +```typescript +verify.completions({ + marker: "1", + includes: { name: "foo", source: "/a", hasAction: true }, + isNewIdentifierLocation: true, + preferences: { includeCompletionsForModuleExports: true } +}); +``` + +#### Code Fixes Testing +```typescript +verify.codeFix({ + description: "Add missing property", + index: 0, + newFileContent: `class C { + property: string; + method() { this.property = "value"; } +}` +}); +``` + +#### Formatting +```typescript +format.document(); +verify.currentLineContentIs("formatted content"); +``` + +### Simple Example +```typescript +/// + +////interface User { +//// name: string; +////} +//// +////const user: User = { +//// /*completion*/ +////}; + +verify.completions({ + marker: "completion", + includes: { name: "name", sortText: "0" } +}); +``` + +## Compiler Test Syntax Guide + +Compiler tests validate TypeScript compilation behavior, type checking, and error reporting. + +### Basic Structure +- Simple `.ts` files in `tests/cases/compiler/` +- Use comments to indicate expected behavior +- No special test harness - just TypeScript code + +### Compiler Directives +Use `// @directive: value` for compiler options: +```typescript +// @strict: true +// @target: ES2015 +// @lib: ES2015,DOM + +let x: string = 42; // Error expected +``` + +### Common Directives +```typescript +// @strict: true/false +// @noImplicitAny: true/false +// @target: ES5/ES2015/ES2020/ESNext +// @module: commonjs/amd/es6/esnext +// @lib: ES5,DOM/ES2015/ES2020 +// @declaration: true/false +// @skipLibCheck: true/false +``` + +### Multi-file Tests +```typescript +// @Filename: helper.ts +export function helper(x: number): string { + return x.toString(); +} + +// @Filename: main.ts +import { helper } from "./helper"; +const result = helper(42); +``` + +### Error Expectations +Use comments to document expected behavior: +```typescript +abstract class Base { + abstract method(): void; +} + +class Derived extends Base { + // Missing implementation - should error +} + +new Base(); // Should error - cannot instantiate abstract class +``` + +### Type Testing Patterns +```typescript +// Test type inference +let inferred = [1, 2, 3]; // Should infer number[] + +// Test type compatibility +type A = { x: number }; +type B = { x: number; y: string }; +let a: A = { x: 1 }; +let b: B = { x: 1, y: "hello" }; +a = b; // Should work - B is assignable to A +b = a; // Should error - A missing property y +``` + +### Simple Example +```typescript +// Test that optional properties work correctly +interface Config { + required: string; + optional?: number; +} + +const config1: Config = { required: "test" }; // Should work +const config2: Config = { required: "test", optional: 42 }; // Should work +const config3: Config = { optional: 42 }; // Should error - missing required +``` + +## Test Writing Best Practices + +### For Fourslash Tests +1. **Prefer validation over baselines** - Use `verify.currentLineContentIs()` instead of `verify.baseline*()` +2. **Use simple, focused examples** - Test one feature at a time +3. **Name markers clearly** - Use descriptive marker names like `/*completion*/` +4. **Test the simplest form first** - Start with basic cases before complex scenarios + +### For Compiler Tests +1. **Use clear file names** - Name tests after the feature being tested +2. **Add explanatory comments** - Document expected behavior with comments +3. **Test error cases** - Include both valid and invalid code examples +4. **Keep tests focused** - One primary feature per test file + +### General Guidelines +1. **Make tests deterministic** - Avoid random or environment-dependent behavior +2. **Use realistic examples** - Test scenarios developers actually encounter +3. **Start simple** - Begin with the most basic case of a feature +4. **Test edge cases** - Include boundary conditions and error scenarios + +## Running Specific Tests + +```bash +# Run a specific fourslash test +npx hereby runtests --tests=tests/cases/fourslash/completionForObjectProperty.ts + +# Run a specific compiler test +npx hereby runtests --tests=tests/cases/compiler/abstractClassUnionInstantiation.ts + +# Run tests matching a pattern +npx hereby runtests --tests=tests/cases/fourslash/completion*.ts +``` + +## Important Guidelines + +### 🚨 CRITICAL: Before Finishing Your Work 🚨 + +**THESE STEPS ARE MANDATORY BEFORE COMMITTING/PUSHING ANY CHANGES:** + +1. **MUST RUN:** `npx hereby runtests-parallel` (even though it takes 10-15 minutes) +2. **MUST RUN:** `npx hereby lint` and fix ALL lint issues +3. **MUST RUN:** `npx hereby format` as the final step + +**❌ PRs that fail these checks will be rejected without review.** + +### Keeping Things Tidy + +- You can assume lint, tests, and formatting are clean on a fresh clone +- Only run these verification steps AFTER making changes to code +- Run `npx hereby lint` and fix ALL issues after making changes +- Run `npx hereby format` as your final step after making changes + +### Test Locations + +- Only add testcases in `tests/cases/compiler` or `tests/cases/fourslash` +- Filenames in `tests/cases/compiler` must always end with `.ts`, not `.d.ts` +- Do not write direct unit tests as they are almost never the correct test format for our repo + +### Performance Expectations + +- Running a set of tests may take up to 4 minutes +- A full test run may take up to 15 minutes + +### Working with Issues + +- Maintainer comments in the issue should generally take priority over OP's comments +- Maintainers might give you hints on where to start. They are not always right, but a good place to start + +### Debugging Tips + +printf debugging is going to be very useful as you are figuring things out. +To do this, use `console.log`, but you'll need to `ts-ignore` it. +Write something like this: +```ts,diff +function checkSomething(n: Node) { + doSomething(n); ++ // @ts-ignore DEBUG CODE ONLY, REMOVE ME WHEN DONE ++ console.log(`Got node with pos = ${n.pos}`); + doSomethingElse(n); +} +``` +We have a lot of enums so you might want to print back their symbolic name, to do this, index back into the name of the enum +```ts + // @ts-ignore DEBUG CODE ONLY, REMOVE ME WHEN DONE + console.log(`Got node with kind = ${SyntaxKind[n.kind]}`); +``` + +## Recommended Workflow + +When fixing bugs or implementing features, follow this workflow: + +1. **Make a testcase that demonstrates the behavior** + - Run it (by itself) and review the baselines it generates to ensure it demonstrates the bug + - Add the test and its baselines in one commit + +2. **Fix the bug by changing code as appropriate** + - Put this fix in another commit + +3. **Run the test you wrote again** + - Ensure the baselines change in a way that demonstrates that the bug is fixed + - Put this baseline diff in its own commit + +4. **Add more testing** + - Once you've got the basics figured out, enhance your test to cover edge cases and other variations + - Run the test again and commit the baseline diff along with the test edit + +5. **🚨 MANDATORY: Run all other tests to ensure you didn't break anything** + - **REQUIRED:** Run `npx hereby runtests-parallel` and wait for it to finish (10-15 minutes is normal!) + - **THIS STEP CANNOT BE SKIPPED** - patience is essential! + - Some collateral baseline changes are normal, but review for correctness + - Put these diffs in another commit + +6. **🚨 MANDATORY: Lint and format your changes** + - **REQUIRED:** Run `npx hereby lint` and fix ALL issues + - **REQUIRED:** Run `npx hereby format` before you're done + - **YOU CANNOT FINISH WITHOUT THESE STEPS** + - Double-check your line endings. Source files in this repo typically use CRLF line endings. Fix all line endings to be consistent before you wrap up diff --git a/.github/pr_owners.txt b/.github/pr_owners.txt index 015655cb42508..20f3cd6a377a6 100644 --- a/.github/pr_owners.txt +++ b/.github/pr_owners.txt @@ -3,14 +3,9 @@ weswigham andrewbranch RyanCavanaugh sheetalkamat -rbuckton ahejlsberg -amcasey -minestarks -armanio123 gabritto jakebailey DanielRosenwasser navya9singh iisaduan -dependabot diff --git a/.github/workflows/accept-baselines-fix-lints.yaml b/.github/workflows/accept-baselines-fix-lints.yaml index 0b5fc8a49e306..f6b51d1d51c61 100644 --- a/.github/workflows/accept-baselines-fix-lints.yaml +++ b/.github/workflows/accept-baselines-fix-lints.yaml @@ -20,7 +20,7 @@ jobs: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: token: ${{ secrets.TS_BOT_GITHUB_TOKEN }} - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fbcf9e8f1cd48..21b21ed824f1f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -51,7 +51,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: Use node version ${{ matrix.node-version }} - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: ${{ matrix.node-version }} check-latest: true @@ -81,7 +81,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -95,7 +95,7 @@ jobs: name: coverage path: coverage - - uses: codecov/codecov-action@0565863a31f2c772f9f0395002a31e3f06189574 # v5.4.0 + - uses: codecov/codecov-action@18283e04ce6e62d37312384ff67231eb8fd56d24 # v5.4.3 with: use_oidc: ${{ !(github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork) }} disable_search: true @@ -106,7 +106,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -119,7 +119,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -132,7 +132,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -152,7 +152,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -168,7 +168,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -182,7 +182,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | @@ -230,7 +230,7 @@ jobs: path: base ref: ${{ github.base_ref }} - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | @@ -263,7 +263,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -279,7 +279,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci @@ -298,7 +298,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: npm ci diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 966bb2d33bd26..0d81accede3e3 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -46,7 +46,7 @@ jobs: # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL - uses: github/codeql-action/init@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3.28.13 + uses: github/codeql-action/init@39edc492dbe16b1465b0cafca41432d857bdb31a # v3.29.1 with: config-file: ./.github/codeql/codeql-configuration.yml # Override language selection by uncommenting this and choosing your languages @@ -56,7 +56,7 @@ jobs: # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). # If this step fails, then you should remove it and run the build manually (see below). - name: Autobuild - uses: github/codeql-action/autobuild@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3.28.13 + uses: github/codeql-action/autobuild@39edc492dbe16b1465b0cafca41432d857bdb31a # v3.29.1 # â„šī¸ Command-line programs to run using the OS shell. # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun @@ -70,4 +70,4 @@ jobs: # make release - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3.28.13 + uses: github/codeql-action/analyze@39edc492dbe16b1465b0cafca41432d857bdb31a # v3.29.1 diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml new file mode 100644 index 0000000000000..8fc19fa43684f --- /dev/null +++ b/.github/workflows/copilot-setup-steps.yml @@ -0,0 +1,22 @@ +name: 'Copilot Setup Steps' +on: workflow_dispatch + +jobs: + # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot. + copilot-setup-steps: + runs-on: ubuntu-latest + + # Set the permissions to the lowest permissions possible needed for your steps. + # Copilot will be given its own token for its operations. + permissions: + # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete. + contents: read + + # You can define any steps you want, and they will run before the agent starts. + # If you do not check out your code, Copilot will do this for you. + steps: + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 + - run: npm ci + # pull dprint caches before network access is blocked + - run: npx hereby check-format || true diff --git a/.github/workflows/insiders.yaml b/.github/workflows/insiders.yaml index 330ff6d42ee55..0069d5f476c0e 100644 --- a/.github/workflows/insiders.yaml +++ b/.github/workflows/insiders.yaml @@ -21,7 +21,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | @@ -43,7 +43,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' # Use NODE_AUTH_TOKEN environment variable to authenticate to this registry. diff --git a/.github/workflows/lkg.yml b/.github/workflows/lkg.yml index 734474388bd5d..427a78afbb313 100644 --- a/.github/workflows/lkg.yml +++ b/.github/workflows/lkg.yml @@ -31,7 +31,7 @@ jobs: with: ref: ${{ inputs.branch_name }} token: ${{ secrets.TS_BOT_GITHUB_TOKEN }} - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | diff --git a/.github/workflows/new-release-branch.yaml b/.github/workflows/new-release-branch.yaml index 91a857b652ecb..6cc38b0289173 100644 --- a/.github/workflows/new-release-branch.yaml +++ b/.github/workflows/new-release-branch.yaml @@ -55,7 +55,7 @@ jobs: filter: blob:none # https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/ fetch-depth: 0 # Default is 1; need to set to 0 to get the benefits of blob:none. token: ${{ secrets.TS_BOT_GITHUB_TOKEN }} - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | diff --git a/.github/workflows/nightly.yaml b/.github/workflows/nightly.yaml index 21af15be711ed..d25ce78731adf 100644 --- a/.github/workflows/nightly.yaml +++ b/.github/workflows/nightly.yaml @@ -22,7 +22,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | @@ -30,7 +30,7 @@ jobs: # corepack enable npm npm install -g $(jq -r '.packageManager' < package.json) npm --version - - name: Setup and publish nightly + - name: Setup and test nightly run: | npm ci npx hereby configure-nightly @@ -43,7 +43,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' # Use NODE_AUTH_TOKEN environment variable to authenticate to this registry. diff --git a/.github/workflows/release-branch-artifact.yaml b/.github/workflows/release-branch-artifact.yaml index 693166d5f8949..4cdafd08f49d4 100644 --- a/.github/workflows/release-branch-artifact.yaml +++ b/.github/workflows/release-branch-artifact.yaml @@ -20,7 +20,7 @@ jobs: steps: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml index 4aed0e4ac752d..9d588a44e6d0b 100644 --- a/.github/workflows/scorecard.yml +++ b/.github/workflows/scorecard.yml @@ -34,7 +34,7 @@ jobs: persist-credentials: false - name: 'Run analysis' - uses: ossf/scorecard-action@f49aabe0b5af0936a0987cfb85d86b75731b0186 # v2.4.1 + uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde # v2.4.2 with: results_file: results.sarif results_format: sarif @@ -55,6 +55,6 @@ jobs: # Upload the results to GitHub's code scanning dashboard. - name: 'Upload to code-scanning' - uses: github/codeql-action/upload-sarif@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3.28.13 + uses: github/codeql-action/upload-sarif@39edc492dbe16b1465b0cafca41432d857bdb31a # v3.29.1 with: sarif_file: results.sarif diff --git a/.github/workflows/set-version.yaml b/.github/workflows/set-version.yaml index 4aede772d5900..5c6834ce14674 100644 --- a/.github/workflows/set-version.yaml +++ b/.github/workflows/set-version.yaml @@ -53,7 +53,7 @@ jobs: with: ref: ${{ inputs.branch_name }} token: ${{ secrets.TS_BOT_GITHUB_TOKEN }} - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | diff --git a/.github/workflows/sync-branch.yaml b/.github/workflows/sync-branch.yaml index 391f3e50edeae..770e2e8dff0b9 100644 --- a/.github/workflows/sync-branch.yaml +++ b/.github/workflows/sync-branch.yaml @@ -42,7 +42,7 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 diff --git a/.github/workflows/twoslash-repros.yaml b/.github/workflows/twoslash-repros.yaml index 93cb170c8a673..41f27188e26cd 100644 --- a/.github/workflows/twoslash-repros.yaml +++ b/.github/workflows/twoslash-repros.yaml @@ -3,6 +3,8 @@ name: Twoslash Code Sample Repros on: schedule: - cron: '0 8 * * *' + repository_dispatch: + types: [run-twoslash-repros] workflow_dispatch: inputs: issue: @@ -55,7 +57,7 @@ jobs: fetch-depth: 0 # Default is 1; need to set to 0 to get the benefits of blob:none. - if: ${{ !github.event.inputs.bisect }} uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - uses: microsoft/TypeScript-Twoslash-Repro-Action@master diff --git a/.github/workflows/update-package-lock.yaml b/.github/workflows/update-package-lock.yaml index 7ed7da675044c..a7323313a3a15 100644 --- a/.github/workflows/update-package-lock.yaml +++ b/.github/workflows/update-package-lock.yaml @@ -25,7 +25,7 @@ jobs: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: token: ${{ secrets.TS_BOT_GITHUB_TOKEN }} - - uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0 + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0 with: node-version: 'lts/*' - run: | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56912a250f84a..3c755bb6d526a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,7 +49,7 @@ In general, things we find useful when reviewing suggestions are: ## What You'll Need -0. [A bug or feature you want to work on](https://github.com/microsoft/TypeScript/labels/help%20wanted)! +0. [A bug or feature you want to work on](https://github.com/microsoft/TypeScript/issues?q=is%3Aissue%20label%3A%22Help%20Wanted%22)! 1. [A GitHub account](https://github.com/join). 2. A copy of the TypeScript code. See the next steps for instructions. 3. [Node](https://nodejs.org), which runs JavaScript locally. Current or LTS will both work. diff --git a/azure-pipelines.release-publish.yml b/azure-pipelines.release-publish.yml index 2f3aac21446cc..7c58d3f82ae6b 100644 --- a/azure-pipelines.release-publish.yml +++ b/azure-pipelines.release-publish.yml @@ -3,17 +3,25 @@ pr: none parameters: - name: _REMINDER - default: Review & undraft the release at https://github.com/microsoft/TypeScript/releases once it appears! + displayName: Review & undraft the release at https://github.com/microsoft/TypeScript/releases once it appears! + type: boolean + default: true - name: PUBLISH_TAG + displayName: npm publish tag default: dev + values: + - dev + - beta + - rc + - latest - name: RELEASE_TITLE_NAME + displayName: GitHub release title name default: 0.0.0 Test - name: TAG_NAME + displayName: Git tag name default: v0.0.0-SetMe variables: - - name: _REMINDER - value: ${{ parameters._REMINDER }} - name: PUBLISH_TAG value: ${{ parameters.PUBLISH_TAG }} - name: RELEASE_TITLE_NAME @@ -47,11 +55,11 @@ extends: os: windows stages: - - stage: Stage_1 - displayName: Publish tarball + - stage: Publish + displayName: Publish jobs: - - job: Job_1 - displayName: Agent job + - job: tarball + displayName: Publish tarball condition: succeeded() timeoutInMinutes: 0 templateContext: @@ -66,12 +74,12 @@ extends: steps: - checkout: none - task: CmdLine@2 - displayName: Rename versioned drop to typescript.tgz + displayName: Copy versioned drop to typescript.tgz inputs: script: | pushd $(Pipeline.Workspace)/tgz ls -lhR - mv typescript-*.tgz typescript.tgz + cp typescript-*.tgz typescript.tgz - task: Npm@1 displayName: npm publish tarball inputs: @@ -79,16 +87,13 @@ extends: workingDir: $(Pipeline.Workspace)/tgz verbose: false customCommand: publish $(Pipeline.Workspace)/tgz/typescript.tgz --tag $(PUBLISH_TAG) - # This must match the service connection. + # This must match the service connection name. customEndpoint: Typescript NPM publishEndpoint: Typescript NPM - - stage: Stage_2 - displayName: Publish git tag - dependsOn: Stage_1 - jobs: - - job: Job_1 - displayName: Agent job + - job: github + displayName: Create github release + dependsOn: tarball condition: succeeded() timeoutInMinutes: 0 templateContext: @@ -104,7 +109,7 @@ extends: - task: GitHubRelease@1 displayName: GitHub release (create) inputs: - # This must match the service connection. + # This must match the service connection name. gitHubConnection: typescript-bot connection repositoryName: microsoft/TypeScript tagSource: userSpecifiedTag @@ -112,12 +117,14 @@ extends: title: TypeScript $(RELEASE_TITLE_NAME) releaseNotesSource: inline releaseNotesInline: | + assets: $(Pipeline.Workspace)/tgz/**/typescript-*.tgz - isDraft: true + isDraft: ${{ not(eq(parameters.PUBLISH_TAG, 'latest')) }} addChangeLog: false diff --git a/src/compiler/builderState.ts b/src/compiler/builderState.ts index cf9932e94631b..625a64e266fee 100644 --- a/src/compiler/builderState.ts +++ b/src/compiler/builderState.ts @@ -206,7 +206,7 @@ export namespace BuilderState { * Gets the path to reference file from file name, it could be resolvedPath if present otherwise path */ function getReferencedFileFromFileName(program: Program, fileName: string, sourceFileDirectory: Path, getCanonicalFileName: GetCanonicalFileName): Path { - return toPath(program.getProjectReferenceRedirect(fileName) || fileName, sourceFileDirectory, getCanonicalFileName); + return toPath(program.getRedirectFromSourceFile(fileName)?.outputDts || fileName, sourceFileDirectory, getCanonicalFileName); } /** diff --git a/src/compiler/checker.ts b/src/compiler/checker.ts index 67a733cbbb811..77f35376da785 100644 --- a/src/compiler/checker.ts +++ b/src/compiler/checker.ts @@ -374,6 +374,7 @@ import { getStrictOptionValue, getSuperContainer, getSymbolNameForPrivateIdentifier, + getSynthesizedDeepClone, getTextOfIdentifierOrLiteral, getTextOfJSDocComment, getTextOfJsxAttributeName, @@ -466,6 +467,7 @@ import { IntroducesNewScopeNode, isAccessExpression, isAccessor, + isAccessorModifier, isAliasableExpression, isAmbientModule, isArray, @@ -480,6 +482,7 @@ import { isAssignmentTarget, isAutoAccessorPropertyDeclaration, isAwaitExpression, + isBigIntLiteral, isBinaryExpression, isBinaryLogicalOperator, isBindableObjectDefinePropertyCall, @@ -881,6 +884,7 @@ import { moduleExportNameTextUnescaped, ModuleInstanceState, ModuleKind, + ModuleName, ModuleResolutionKind, ModuleSpecifierResolutionHost, moduleSupportsImportAttributes, @@ -1006,7 +1010,6 @@ import { SignatureFlags, SignatureKind, singleElementArray, - SingleSignatureType, skipOuterExpressions, skipParentheses, skipTrivia, @@ -1132,6 +1135,7 @@ import { WhileStatement, WideningContext, WithStatement, + WriterContextOut, YieldExpression, } from "./_namespaces/ts.js"; import * as moduleSpecifiers from "./_namespaces/ts.moduleSpecifiers.js"; @@ -1716,11 +1720,11 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { typePredicateToString: (predicate, enclosingDeclaration, flags) => { return typePredicateToString(predicate, getParseTreeNode(enclosingDeclaration), flags); }, - writeSignature: (signature, enclosingDeclaration, flags, kind, writer) => { - return signatureToString(signature, getParseTreeNode(enclosingDeclaration), flags, kind, writer); + writeSignature: (signature, enclosingDeclaration, flags, kind, writer, maximumLength, verbosityLevel, out) => { + return signatureToString(signature, getParseTreeNode(enclosingDeclaration), flags, kind, writer, maximumLength, verbosityLevel, out); }, - writeType: (type, enclosingDeclaration, flags, writer) => { - return typeToString(type, getParseTreeNode(enclosingDeclaration), flags, writer); + writeType: (type, enclosingDeclaration, flags, writer, maximumLength, verbosityLevel, out) => { + return typeToString(type, getParseTreeNode(enclosingDeclaration), flags, writer, maximumLength, verbosityLevel, out); }, writeSymbol: (symbol, enclosingDeclaration, meaning, flags, writer) => { return symbolToString(symbol, getParseTreeNode(enclosingDeclaration), meaning, flags, writer); @@ -1836,6 +1840,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { getNullType: () => nullType, getESSymbolType: () => esSymbolType, getNeverType: () => neverType, + getNonPrimitiveType: () => nonPrimitiveType, getOptionalType: () => optionalType, getPromiseType: () => getGlobalPromiseType(/*reportErrors*/ false), getPromiseLikeType: () => getGlobalPromiseLikeType(/*reportErrors*/ false), @@ -1932,6 +1937,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { typeHasCallOrConstructSignatures, getSymbolFlags, getTypeArgumentsForResolvedSignature, + isLibType, }; function getTypeArgumentsForResolvedSignature(signature: Signature) { @@ -2175,6 +2181,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { }; var anyIterationTypes = createIterationTypes(anyType, anyType, anyType); + var silentNeverIterationTypes = createIterationTypes(silentNeverType, silentNeverType, silentNeverType); var asyncIterationTypesResolver: IterationTypesResolver = { iterableCacheKey: "iterationTypesOfAsyncIterable", @@ -2316,6 +2323,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { var inferenceContexts: (InferenceContext | undefined)[] = []; var inferenceContextCount = 0; + var activeTypeMappers: TypeMapper[] = []; + var activeTypeMappersCaches: Map[] = []; + var activeTypeMappersCount = 0; + var emptyStringType = getStringLiteralType(""); var zeroType = getNumberLiteralType(0); var zeroBigIntType = getBigIntLiteralType({ negative: false, base10Value: "0" }); @@ -2517,6 +2528,20 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return diagnostic; } + function getVerbatimModuleSyntaxErrorMessage(node: Node): DiagnosticMessage { + const sourceFile = getSourceFileOfNode(node); + const fileName = sourceFile.fileName; + + // Check if the file is .cts or .cjs (CommonJS-specific extensions) + if (fileExtensionIsOneOf(fileName, [Extension.Cts, Extension.Cjs])) { + return Diagnostics.ECMAScript_imports_and_exports_cannot_be_written_in_a_CommonJS_file_under_verbatimModuleSyntax; + } + else { + // For .ts, .tsx, .js, etc. + return Diagnostics.ECMAScript_imports_and_exports_cannot_be_written_in_a_CommonJS_file_under_verbatimModuleSyntax_Adjust_the_type_field_in_the_nearest_package_json_to_make_this_file_an_ECMAScript_module_or_adjust_your_verbatimModuleSyntax_module_and_moduleResolution_settings_in_TypeScript; + } + } + function addErrorOrSuggestion(isError: boolean, diagnostic: Diagnostic) { if (isError) { diagnostics.add(diagnostic); @@ -3063,13 +3088,17 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return isForInOrOfStatement(grandparent) && isSameScopeDescendentOf(usage, grandparent.expression, declContainer); } - function isUsedInFunctionOrInstanceProperty(usage: Node, declaration: Node): boolean { + function isUsedInFunctionOrInstanceProperty(usage: Node, declaration: Node) { + return isUsedInFunctionOrInstancePropertyWorker(usage, declaration); + } + + function isUsedInFunctionOrInstancePropertyWorker(usage: Node, declaration: Node): boolean { return !!findAncestor(usage, current => { if (current === declContainer) { return "quit"; } if (isFunctionLike(current)) { - return true; + return !getImmediatelyInvokedFunctionExpression(current); } if (isClassStaticBlockDeclaration(current)) { return declaration.pos < usage.pos; @@ -3102,6 +3131,17 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } } + + const decorator = tryCast(current.parent, isDecorator); + if (decorator && decorator.expression === current) { + if (isParameter(decorator.parent)) { + return isUsedInFunctionOrInstancePropertyWorker(decorator.parent.parent.parent, declaration) ? true : "quit"; + } + if (isMethodDeclaration(decorator.parent)) { + return isUsedInFunctionOrInstancePropertyWorker(decorator.parent.parent, declaration) ? true : "quit"; + } + } + return false; }); } @@ -3663,6 +3703,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { getExternalModuleRequireArgument(node) || getExternalModuleImportEqualsDeclarationExpression(node), ); const resolved = resolveExternalModuleSymbol(immediate); + if (resolved && ModuleKind.Node20 <= moduleKind && moduleKind <= ModuleKind.NodeNext) { + const moduleExports = getExportOfModule(resolved, "module.exports" as __String, node, dontResolveAlias); + if (moduleExports) { + return moduleExports; + } + } markSymbolOfAliasDeclarationIfTypeOnly(node, immediate, resolved, /*overwriteEmpty*/ false); return resolved; } @@ -3778,16 +3824,44 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function getTargetofModuleDefault(moduleSymbol: Symbol, node: ImportClause | ImportOrExportSpecifier, dontResolveAlias: boolean) { + const file = moduleSymbol.declarations?.find(isSourceFile); + const specifier = getModuleSpecifierForImportOrExport(node); let exportDefaultSymbol: Symbol | undefined; + let exportModuleDotExportsSymbol: Symbol | undefined; if (isShorthandAmbientModuleSymbol(moduleSymbol)) { exportDefaultSymbol = moduleSymbol; } + else if ( + file && specifier && + ModuleKind.Node20 <= moduleKind && moduleKind <= ModuleKind.NodeNext && + getEmitSyntaxForModuleSpecifierExpression(specifier) === ModuleKind.CommonJS && + host.getImpliedNodeFormatForEmit(file) === ModuleKind.ESNext && + (exportModuleDotExportsSymbol = resolveExportByName(moduleSymbol, "module.exports" as __String, node, dontResolveAlias)) + ) { + // We have a transpiled default import where the `require` resolves to an ES module with a `module.exports` named + // export. If `esModuleInterop` is enabled, this will work: + // + // const dep_1 = __importDefault(require("./dep.mjs")); // wraps like { default: require("./dep.mjs") } + // dep_1.default; // require("./dep.mjs") -> the `module.exports` export value + // + // But without `esModuleInterop`, it will be broken: + // + // const dep_1 = require("./dep.mjs"); // the `module.exports` export value (could be primitive) + // dep_1.default; // `default` property access on the `module.exports` export value + // + // We could try to resolve the 'default' property in the latter case, but it's a mistake to run in this + // environment without `esModuleInterop`, so just error. + if (!getESModuleInterop(compilerOptions)) { + error(node.name, Diagnostics.Module_0_can_only_be_default_imported_using_the_1_flag, symbolToString(moduleSymbol), "esModuleInterop"); + return undefined; + } + markSymbolOfAliasDeclarationIfTypeOnly(node, exportModuleDotExportsSymbol, /*finalTarget*/ undefined, /*overwriteEmpty*/ false); + return exportModuleDotExportsSymbol; + } else { exportDefaultSymbol = resolveExportByName(moduleSymbol, InternalSymbolName.Default, node, dontResolveAlias); } - const file = moduleSymbol.declarations?.find(isSourceFile); - const specifier = getModuleSpecifierForImportOrExport(node); if (!specifier) { return exportDefaultSymbol; } @@ -4699,7 +4773,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ); } else if (resolvedModule.resolvedUsingTsExtension && shouldRewrite) { - const redirect = host.getResolvedProjectReferenceToRedirect(sourceFile.path); + const redirect = host.getRedirectFromSourceFile(sourceFile.path)?.resolvedRef; if (redirect) { const ignoreCase = !host.useCaseSensitiveFileNames(); const ownRootDir = host.getCommonSourceDirectory(); @@ -4794,9 +4868,9 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (moduleNotFoundError) { // See if this was possibly a projectReference redirect if (resolvedModule) { - const redirect = host.getProjectReferenceRedirect(resolvedModule.resolvedFileName); - if (redirect) { - error(errorNode, Diagnostics.Output_file_0_has_not_been_built_from_source_file_1, redirect, resolvedModule.resolvedFileName); + const redirect = host.getRedirectFromSourceFile(resolvedModule.resolvedFileName); + if (redirect?.outputDts) { + error(errorNode, Diagnostics.Output_file_0_has_not_been_built_from_source_file_1, redirect.outputDts, resolvedModule.resolvedFileName); return undefined; } } @@ -4933,10 +5007,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } const referenceParent = referencingLocation.parent; - if ( - (isImportDeclaration(referenceParent) && getNamespaceDeclarationNode(referenceParent)) || - isImportCall(referenceParent) - ) { + const namespaceImport = isImportDeclaration(referenceParent) && getNamespaceDeclarationNode(referenceParent); + if (namespaceImport || isImportCall(referenceParent)) { const reference = isImportCall(referenceParent) ? referenceParent.arguments[0] : referenceParent.moduleSpecifier; const type = getTypeOfSymbol(symbol); const defaultOnlyType = getTypeWithSyntheticDefaultOnly(type, symbol, moduleSymbol!, reference); @@ -4945,14 +5017,27 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } const targetFile = moduleSymbol?.declarations?.find(isSourceFile); - const isEsmCjsRef = targetFile && isESMFormatImportImportingCommonjsFormatFile(getEmitSyntaxForModuleSpecifierExpression(reference), host.getImpliedNodeFormatForEmit(targetFile)); - if (getESModuleInterop(compilerOptions) || isEsmCjsRef) { - let sigs = getSignaturesOfStructuredType(type, SignatureKind.Call); - if (!sigs || !sigs.length) { - sigs = getSignaturesOfStructuredType(type, SignatureKind.Construct); + const usageMode = getEmitSyntaxForModuleSpecifierExpression(reference); + let exportModuleDotExportsSymbol: Symbol | undefined; + if ( + namespaceImport && targetFile && + ModuleKind.Node20 <= moduleKind && moduleKind <= ModuleKind.NodeNext && + usageMode === ModuleKind.CommonJS && host.getImpliedNodeFormatForEmit(targetFile) === ModuleKind.ESNext && + (exportModuleDotExportsSymbol = resolveExportByName(symbol, "module.exports" as __String, namespaceImport, dontResolveAlias)) + ) { + if (!suppressInteropError && !(symbol.flags & (SymbolFlags.Module | SymbolFlags.Variable))) { + error(referencingLocation, Diagnostics.This_module_can_only_be_referenced_with_ECMAScript_imports_Slashexports_by_turning_on_the_0_flag_and_referencing_its_default_export, "esModuleInterop"); } + if (getESModuleInterop(compilerOptions) && hasSignatures(type)) { + return cloneTypeAsModuleType(exportModuleDotExportsSymbol, type, referenceParent); + } + return exportModuleDotExportsSymbol; + } + + const isEsmCjsRef = targetFile && isESMFormatImportImportingCommonjsFormatFile(usageMode, host.getImpliedNodeFormatForEmit(targetFile)); + if (getESModuleInterop(compilerOptions) || isEsmCjsRef) { if ( - (sigs && sigs.length) || + hasSignatures(type) || getPropertyOfType(type, InternalSymbolName.Default, /*skipObjectFunctionPropertyAugment*/ true) || isEsmCjsRef ) { @@ -4967,6 +5052,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return symbol; } + function hasSignatures(type: Type): boolean { + return some(getSignaturesOfStructuredType(type, SignatureKind.Call)) || some(getSignaturesOfStructuredType(type, SignatureKind.Construct)); + } + /** * Create a new symbol which has the module's type less the call and construct signatures */ @@ -5908,7 +5997,14 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return addVisibleAlias(declaration, declaration.parent.parent.parent.parent); } else if (symbol.flags & SymbolFlags.BlockScopedVariable) { - const variableStatement = findAncestor(declaration, isVariableStatement)!; + const rootDeclaration = walkUpBindingElementsAndPatterns(declaration); + if (rootDeclaration.kind === SyntaxKind.Parameter) { + return false; + } + const variableStatement = rootDeclaration.parent.parent; + if (variableStatement.kind !== SyntaxKind.VariableStatement) { + return false; + } if (hasSyntacticModifier(variableStatement, ModifierFlags.Export)) { return true; } @@ -6027,7 +6123,16 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } - function signatureToString(signature: Signature, enclosingDeclaration?: Node, flags = TypeFormatFlags.None, kind?: SignatureKind, writer?: EmitTextWriter): string { + function signatureToString( + signature: Signature, + enclosingDeclaration?: Node, + flags = TypeFormatFlags.None, + kind?: SignatureKind, + writer?: EmitTextWriter, + maximumLength?: number, + verbosityLevel?: number, + out?: WriterContextOut, + ): string { return writer ? signatureToStringWorker(writer).getText() : usingSingleLineStringWriter(signatureToStringWorker); function signatureToStringWorker(writer: EmitTextWriter) { @@ -6038,7 +6143,17 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { else { sigOutput = kind === SignatureKind.Construct ? SyntaxKind.ConstructSignature : SyntaxKind.CallSignature; } - const sig = nodeBuilder.signatureToSignatureDeclaration(signature, sigOutput, enclosingDeclaration, toNodeBuilderFlags(flags) | NodeBuilderFlags.IgnoreErrors | NodeBuilderFlags.WriteTypeParametersInQualifiedName); + const sig = nodeBuilder.signatureToSignatureDeclaration( + signature, + sigOutput, + enclosingDeclaration, + toNodeBuilderFlags(flags) | NodeBuilderFlags.IgnoreErrors | NodeBuilderFlags.WriteTypeParametersInQualifiedName, + /*internalFlags*/ undefined, + /*tracker*/ undefined, + maximumLength, + verbosityLevel, + out, + ); const printer = createPrinterWithRemoveCommentsOmitTrailingSemicolon(); const sourceFile = enclosingDeclaration && getSourceFileOfNode(enclosingDeclaration); printer.writeNode(EmitHint.Unspecified, sig!, /*sourceFile*/ sourceFile, getTrailingSemicolonDeferringWriter(writer)); // TODO: GH#18217 @@ -6046,9 +6161,27 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } - function typeToString(type: Type, enclosingDeclaration?: Node, flags: TypeFormatFlags = TypeFormatFlags.AllowUniqueESSymbolType | TypeFormatFlags.UseAliasDefinedOutsideCurrentScope, writer: EmitTextWriter = createTextWriter("")): string { - const noTruncation = compilerOptions.noErrorTruncation || flags & TypeFormatFlags.NoTruncation; - const typeNode = nodeBuilder.typeToTypeNode(type, enclosingDeclaration, toNodeBuilderFlags(flags) | NodeBuilderFlags.IgnoreErrors | (noTruncation ? NodeBuilderFlags.NoTruncation : NodeBuilderFlags.None), /*internalFlags*/ undefined); + function typeToString( + type: Type, + enclosingDeclaration?: Node, + flags: TypeFormatFlags = TypeFormatFlags.AllowUniqueESSymbolType | TypeFormatFlags.UseAliasDefinedOutsideCurrentScope, + writer: EmitTextWriter = createTextWriter(""), + maximumLength?: number, + verbosityLevel?: number, + out?: WriterContextOut, + ): string { + const noTruncation = !maximumLength && compilerOptions.noErrorTruncation || + flags & TypeFormatFlags.NoTruncation; + const typeNode = nodeBuilder.typeToTypeNode( + type, + enclosingDeclaration, + toNodeBuilderFlags(flags) | NodeBuilderFlags.IgnoreErrors | (noTruncation ? NodeBuilderFlags.NoTruncation : 0), + /*internalFlags*/ undefined, + /*tracker*/ undefined, + maximumLength, + verbosityLevel, + out, + ); if (typeNode === undefined) return Debug.fail("should always get typenode"); // The unresolved type gets a synthesized comment on `any` to hint to users that it's not a plain `any`. // Otherwise, we always strip comments out. @@ -6057,7 +6190,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { printer.writeNode(EmitHint.Unspecified, typeNode, /*sourceFile*/ sourceFile, writer); const result = writer.getText(); - const maxLength = noTruncation ? noTruncationMaximumTruncationLength * 2 : defaultMaximumTruncationLength * 2; + const maxLength = maximumLength || (noTruncation ? noTruncationMaximumTruncationLength * 2 : defaultMaximumTruncationLength * 2); if (maxLength && result && result.length >= maxLength) { return result.substr(0, maxLength - "...".length) + "..."; } @@ -6127,7 +6260,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { }, isOptionalParameter, isUndefinedIdentifierExpression(node: Identifier) { - Debug.assert(isExpressionNode(node)); return getSymbolAtLocation(node) === undefinedSymbol; }, isEntityNameVisible(context, entityName, shouldComputeAliasToMakeVisible) { @@ -6270,20 +6402,21 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { }; return { syntacticBuilderResolver, - typeToTypeNode: (type: Type, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => typeToTypeNodeHelper(type, context)), - typePredicateToTypePredicateNode: (typePredicate: TypePredicate, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => typePredicateToTypePredicateNodeHelper(typePredicate, context)), - serializeTypeForExpression: (expr: Expression, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => syntacticNodeBuilder.serializeTypeOfExpression(expr, context)), - serializeTypeForDeclaration: (declaration: HasInferredType, symbol: Symbol, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => syntacticNodeBuilder.serializeTypeOfDeclaration(declaration, symbol, context)), - serializeReturnTypeForSignature: (signature: SignatureDeclaration, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => syntacticNodeBuilder.serializeReturnTypeForSignature(signature, getSymbolOfDeclaration(signature), context)), - indexInfoToIndexSignatureDeclaration: (indexInfo: IndexInfo, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => indexInfoToIndexSignatureDeclarationHelper(indexInfo, context, /*typeNode*/ undefined)), - signatureToSignatureDeclaration: (signature: Signature, kind: SignatureDeclaration["kind"], enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => signatureToSignatureDeclarationHelper(signature, kind, context)), - symbolToEntityName: (symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => symbolToName(symbol, context, meaning, /*expectsIdentifier*/ false)), - symbolToExpression: (symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => symbolToExpression(symbol, context, meaning)), - symbolToTypeParameterDeclarations: (symbol: Symbol, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => typeParametersToTypeParameterDeclarations(symbol, context)), - symbolToParameterDeclaration: (symbol: Symbol, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => symbolToParameterDeclaration(symbol, context)), - typeParameterToDeclaration: (parameter: TypeParameter, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => typeParameterToDeclaration(parameter, context)), - symbolTableToDeclarationStatements: (symbolTable: SymbolTable, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => symbolTableToDeclarationStatements(symbolTable, context)), - symbolToNode: (symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, context => symbolToNode(symbol, context, meaning)), + typeToTypeNode: (type: Type, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker, maximumLength?: number, verbosityLevel?: number, out?: WriterContextOut) => withContext(enclosingDeclaration, flags, internalFlags, tracker, maximumLength, verbosityLevel, context => typeToTypeNodeHelper(type, context), out), + typePredicateToTypePredicateNode: (typePredicate: TypePredicate, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => typePredicateToTypePredicateNodeHelper(typePredicate, context)), + serializeTypeForDeclaration: (declaration: HasInferredType, symbol: Symbol, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => syntacticNodeBuilder.serializeTypeOfDeclaration(declaration, symbol, context)), + serializeReturnTypeForSignature: (signature: SignatureDeclaration, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => syntacticNodeBuilder.serializeReturnTypeForSignature(signature, getSymbolOfDeclaration(signature), context)), + serializeTypeForExpression: (expr: Expression, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => syntacticNodeBuilder.serializeTypeOfExpression(expr, context)), + indexInfoToIndexSignatureDeclaration: (indexInfo: IndexInfo, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => indexInfoToIndexSignatureDeclarationHelper(indexInfo, context, /*typeNode*/ undefined)), + signatureToSignatureDeclaration: (signature: Signature, kind: SignatureDeclaration["kind"], enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker, maximumLength?: number, verbosityLevel?: number, out?: WriterContextOut) => withContext(enclosingDeclaration, flags, internalFlags, tracker, maximumLength, verbosityLevel, context => signatureToSignatureDeclarationHelper(signature, kind, context), out), + symbolToEntityName: (symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => symbolToName(symbol, context, meaning, /*expectsIdentifier*/ false)), + symbolToExpression: (symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => symbolToExpression(symbol, context, meaning)), + symbolToTypeParameterDeclarations: (symbol: Symbol, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => typeParametersToTypeParameterDeclarations(symbol, context)), + symbolToParameterDeclaration: (symbol: Symbol, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => symbolToParameterDeclaration(symbol, context)), + typeParameterToDeclaration: (parameter: TypeParameter, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker, maximumLength?: number, verbosityLevel?: number, out?: WriterContextOut) => withContext(enclosingDeclaration, flags, internalFlags, tracker, maximumLength, verbosityLevel, context => typeParameterToDeclaration(parameter, context), out), + symbolTableToDeclarationStatements: (symbolTable: SymbolTable, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => symbolTableToDeclarationStatements(symbolTable, context)), + symbolToNode: (symbol: Symbol, meaning: SymbolFlags, enclosingDeclaration?: Node, flags?: NodeBuilderFlags, internalFlags?: InternalNodeBuilderFlags, tracker?: SymbolTracker) => withContext(enclosingDeclaration, flags, internalFlags, tracker, /*maximumLength*/ undefined, /*verbosityLevel*/ undefined, context => symbolToNode(symbol, context, meaning)), + symbolToDeclarations, }; function getTypeFromTypeNode(context: NodeBuilderContext, node: TypeNode, noMappedTypes?: false): Type; @@ -6343,16 +6476,101 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return symbolToExpression(symbol, context, meaning); } - function withContext(enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined, internalFlags: InternalNodeBuilderFlags | undefined, tracker: SymbolTracker | undefined, cb: (context: NodeBuilderContext) => T): T | undefined { + function symbolToDeclarations(symbol: Symbol, meaning: SymbolFlags, flags: NodeBuilderFlags, maximumLength?: number, verbosityLevel?: number, out?: WriterContextOut): Declaration[] { + const nodes = withContext( + /*enclosingDeclaration*/ undefined, + flags, + /*internalFlags*/ undefined, + /*tracker*/ undefined, + maximumLength, + verbosityLevel, + context => symbolToDeclarationsWorker(symbol, context), + out, + ); + return mapDefined(nodes, node => { + switch (node.kind) { + case SyntaxKind.ClassDeclaration: + return simplifyClassDeclaration(node as ClassDeclaration, symbol); + case SyntaxKind.EnumDeclaration: + return simplifyModifiers(node as EnumDeclaration, isEnumDeclaration, symbol); + case SyntaxKind.InterfaceDeclaration: + return simplifyInterfaceDeclaration(node as InterfaceDeclaration, symbol, meaning); + case SyntaxKind.ModuleDeclaration: + return simplifyModifiers(node as ModuleDeclaration, isModuleDeclaration, symbol); + default: + return undefined; + } + }); + } + + function simplifyClassDeclaration(classDecl: ClassDeclaration, symbol: Symbol): Declaration { + const classDeclarations = filter(symbol.declarations, isClassLike); + const originalClassDecl = classDeclarations && classDeclarations.length > 0 ? classDeclarations[0] : classDecl; + const modifiers = getEffectiveModifierFlags(originalClassDecl) & ~(ModifierFlags.Export | ModifierFlags.Ambient); + const isAnonymous = isClassExpression(originalClassDecl); + if (isAnonymous) { + classDecl = factory.updateClassDeclaration( + classDecl, + classDecl.modifiers, + /*name*/ undefined, + classDecl.typeParameters, + classDecl.heritageClauses, + classDecl.members, + ); + } + return factory.replaceModifiers(classDecl, modifiers); + } + + function simplifyModifiers(newDecl: Declaration & HasModifiers, isDeclKind: (d: Declaration) => boolean, symbol: Symbol): Declaration & HasModifiers { + const decls = filter(symbol.declarations, isDeclKind); + const declWithModifiers = decls && decls.length > 0 ? decls[0] : newDecl; + const modifiers = getEffectiveModifierFlags(declWithModifiers) & ~(ModifierFlags.Export | ModifierFlags.Ambient); + return factory.replaceModifiers(newDecl, modifiers); + } + + function simplifyInterfaceDeclaration(interfaceDecl: InterfaceDeclaration, symbol: Symbol, meaning: SymbolFlags): Declaration | undefined { + if (!(meaning & SymbolFlags.Interface)) { + return undefined; + } + return simplifyModifiers(interfaceDecl, isInterfaceDeclaration, symbol); + } + + function symbolToDeclarationsWorker(symbol: Symbol, context: NodeBuilderContext): Statement[] { + // We're already expanding the type: set it in the stack to avoid expanding it again. + const type = getDeclaredTypeOfSymbol(symbol); + context.typeStack.push(type.id); + context.typeStack.push(-1); + const table = createSymbolTable([symbol]); + const statements = symbolTableToDeclarationStatements(table, context); + context.typeStack.pop(); + context.typeStack.pop(); + return statements; + } + + function withContext( + enclosingDeclaration: Node | undefined, + flags: NodeBuilderFlags | undefined, + internalFlags: InternalNodeBuilderFlags | undefined, + tracker: SymbolTracker | undefined, + maximumLength: number | undefined, + verbosityLevel: number | undefined, + cb: (context: NodeBuilderContext) => T, + out?: WriterContextOut, + ): T | undefined { const moduleResolverHost = tracker?.trackSymbol ? tracker.moduleResolverHost : (internalFlags || InternalNodeBuilderFlags.None) & InternalNodeBuilderFlags.DoNotIncludeSymbolChain ? createBasicNodeBuilderModuleSpecifierResolutionHost(host) : undefined; + flags = flags || NodeBuilderFlags.None; + const maxTruncationLength = maximumLength || + (flags & NodeBuilderFlags.NoTruncation ? noTruncationMaximumTruncationLength : defaultMaximumTruncationLength); const context: NodeBuilderContext = { enclosingDeclaration, enclosingFile: enclosingDeclaration && getSourceFileOfNode(enclosingDeclaration), - flags: flags || NodeBuilderFlags.None, + flags, internalFlags: internalFlags || InternalNodeBuilderFlags.None, tracker: undefined!, + maxTruncationLength, + maxExpansionDepth: verbosityLevel ?? -1, encounteredError: false, suppressReportInferenceFallback: false, reportedDiagnostic: false, @@ -6375,12 +6593,22 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { typeParameterNamesByTextNextNameCount: undefined, enclosingSymbolTypes: new Map(), mapper: undefined, + depth: 0, + typeStack: [], + out: { + canIncreaseExpansionDepth: false, + truncated: false, + }, }; context.tracker = new SymbolTrackerImpl(context, tracker, moduleResolverHost); const resultingNode = cb(context); if (context.truncating && context.flags & NodeBuilderFlags.NoTruncation) { context.tracker.reportTruncationError(); } + if (out) { + out.canIncreaseExpansionDepth = context.out.canIncreaseExpansionDepth; + out.truncated = context.out.truncated; + } return context.encounteredError ? undefined : resultingNode; } @@ -6401,23 +6629,65 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function saveRestoreFlags(context: NodeBuilderContext) { const flags = context.flags; const internalFlags = context.internalFlags; + const depth = context.depth; return restore; function restore() { context.flags = flags; context.internalFlags = internalFlags; + context.depth = depth; } } + function checkTruncationLengthIfExpanding(context: NodeBuilderContext): boolean { + return context.maxExpansionDepth >= 0 && checkTruncationLength(context); + } + function checkTruncationLength(context: NodeBuilderContext): boolean { if (context.truncating) return context.truncating; - return context.truncating = context.approximateLength > ((context.flags & NodeBuilderFlags.NoTruncation) ? noTruncationMaximumTruncationLength : defaultMaximumTruncationLength); + return context.truncating = context.approximateLength > context.maxTruncationLength; + } + + /** + * Returns true if it's possible the type or one of its components can be expanded. + */ + function canPossiblyExpandType(type: Type, context: NodeBuilderContext): boolean { + for (let i = 0; i < context.typeStack.length - 1; i++) { + if (context.typeStack[i] === type.id) { + return false; + } + } + return context.depth < context.maxExpansionDepth || + context.depth === context.maxExpansionDepth && !context.out.canIncreaseExpansionDepth; + } + + /** + * Determines if the input type should be expanded, based on how many layers of names we're allowed to expand. + * @param isAlias - Whether we're expanding a type alias or not. + */ + function shouldExpandType(type: Type, context: NodeBuilderContext, isAlias = false): boolean { + if (!isAlias && isLibType(type)) { + return false; + } + for (let i = 0; i < context.typeStack.length - 1; i++) { + if (context.typeStack[i] === type.id) { + return false; + } + } + const result = context.depth < context.maxExpansionDepth; + if (!result) { + // This type would have been expanded if `maxExpansionDepth` was increased. + context.out.canIncreaseExpansionDepth = true; + } + return result; } function typeToTypeNodeHelper(type: Type, context: NodeBuilderContext): TypeNode { const restoreFlags = saveRestoreFlags(context); + if (type) context.typeStack.push(type.id); const typeNode = typeToTypeNodeWorker(type, context); + if (type) context.typeStack.pop(); restoreFlags(); return typeNode; } @@ -6428,6 +6698,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } const inTypeAlias = context.flags & NodeBuilderFlags.InTypeAlias; context.flags &= ~NodeBuilderFlags.InTypeAlias; + let expandingEnum = false; if (!type) { if (!(context.flags & NodeBuilderFlags.AllowEmptyUnionOrIntersection)) { @@ -6496,7 +6767,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return Debug.fail("Unhandled type node kind returned from `symbolToTypeNode`."); } } - return symbolToTypeNode(type.symbol, context, SymbolFlags.Type); + if (!shouldExpandType(type, context)) { + return symbolToTypeNode(type.symbol, context, SymbolFlags.Type); + } + else { + expandingEnum = true; + } } if (type.flags & TypeFlags.StringLiteral) { context.approximateLength += (type as StringLiteralType).value.length + 2; @@ -6564,18 +6840,25 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } if (!inTypeAlias && type.aliasSymbol && (context.flags & NodeBuilderFlags.UseAliasDefinedOutsideCurrentScope || isTypeSymbolAccessible(type.aliasSymbol, context.enclosingDeclaration))) { - const typeArgumentNodes = mapToTypeNodes(type.aliasTypeArguments, context); - if (isReservedMemberName(type.aliasSymbol.escapedName) && !(type.aliasSymbol.flags & SymbolFlags.Class)) return factory.createTypeReferenceNode(factory.createIdentifier(""), typeArgumentNodes); - if (length(typeArgumentNodes) === 1 && type.aliasSymbol === globalArrayType.symbol) { - return factory.createArrayTypeNode(typeArgumentNodes![0]); + if (!shouldExpandType(type, context, /*isAlias*/ true)) { + const typeArgumentNodes = mapToTypeNodes(type.aliasTypeArguments, context); + if (isReservedMemberName(type.aliasSymbol.escapedName) && !(type.aliasSymbol.flags & SymbolFlags.Class)) return factory.createTypeReferenceNode(factory.createIdentifier(""), typeArgumentNodes); + if (length(typeArgumentNodes) === 1 && type.aliasSymbol === globalArrayType.symbol) { + return factory.createArrayTypeNode(typeArgumentNodes![0]); + } + return symbolToTypeNode(type.aliasSymbol, context, SymbolFlags.Type, typeArgumentNodes); } - return symbolToTypeNode(type.aliasSymbol, context, SymbolFlags.Type, typeArgumentNodes); + context.depth += 1; } const objectFlags = getObjectFlags(type); if (objectFlags & ObjectFlags.Reference) { Debug.assert(!!(type.flags & TypeFlags.Object)); + if (shouldExpandType(type, context)) { + context.depth += 1; + return createAnonymousTypeNode(type as TypeReference, /*forceClassExpansion*/ true, /*forceExpansion*/ true); + } return (type as TypeReference).node ? visitAndTransformType(type as TypeReference, typeReferenceToTypeNode) : typeReferenceToTypeNode(type as TypeReference); } if (type.flags & TypeFlags.TypeParameter || objectFlags & ObjectFlags.ClassOrInterface) { @@ -6604,6 +6887,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { context.approximateLength += idText(name).length; return factory.createTypeReferenceNode(factory.createIdentifier(idText(name)), /*typeArguments*/ undefined); } + if (objectFlags & ObjectFlags.ClassOrInterface && shouldExpandType(type, context)) { + context.depth += 1; + return createAnonymousTypeNode(type as InterfaceType, /*forceClassExpansion*/ true, /*forceExpansion*/ true); + } // Ignore constraint/default when creating a usage (as opposed to declaration) of a type parameter. if (type.symbol) { return symbolToTypeNode(type.symbol, context, SymbolFlags.Type); @@ -6616,7 +6903,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { type = (type as UnionType).origin!; } if (type.flags & (TypeFlags.Union | TypeFlags.Intersection)) { - const types = type.flags & TypeFlags.Union ? formatUnionTypes((type as UnionType).types) : (type as IntersectionType).types; + const types = type.flags & TypeFlags.Union ? formatUnionTypes((type as UnionType).types, expandingEnum) : (type as IntersectionType).types; if (length(types) === 1) { return typeToTypeNodeHelper(types[0], context); } @@ -6752,6 +7039,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const questionToken = type.declaration.questionToken ? factory.createToken(type.declaration.questionToken.kind) as QuestionToken | PlusToken | MinusToken : undefined; let appropriateConstraintTypeNode: TypeNode; let newTypeVariable: TypeReferenceNode | undefined; + let templateType = getTemplateTypeFromMappedType(type); + const typeParameter = getTypeParameterFromMappedType(type); // If the mapped type isn't `keyof` constraint-declared, _but_ still has modifiers preserved, and its naive instantiation won't preserve modifiers because its constraint isn't `keyof` constrained, we have work to do const needsModifierPreservingWrapper = !isMappedTypeWithKeyofConstraintDeclaration(type) && !(getModifiersTypeFromMappedType(type).flags & TypeFlags.Unknown) @@ -6761,9 +7050,14 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // We have a { [P in keyof T]: X } // We do this to ensure we retain the toplevel keyof-ness of the type which may be lost due to keyof distribution during `getConstraintTypeFromMappedType` if (isHomomorphicMappedTypeWithNonHomomorphicInstantiation(type) && context.flags & NodeBuilderFlags.GenerateNamesForShadowedTypeParams) { - const newParam = createTypeParameter(createSymbol(SymbolFlags.TypeParameter, "T" as __String)); - const name = typeParameterToName(newParam, context); + const newConstraintParam = createTypeParameter(createSymbol(SymbolFlags.TypeParameter, "T" as __String)); + const name = typeParameterToName(newConstraintParam, context); + const target = type.target as MappedType; newTypeVariable = factory.createTypeReferenceNode(name); + templateType = instantiateType( + getTemplateTypeFromMappedType(target), + makeArrayTypeMapper([getTypeParameterFromMappedType(target), getModifiersTypeFromMappedType(target)], [typeParameter, newConstraintParam]), + ); } appropriateConstraintTypeNode = factory.createTypeOperatorNode(SyntaxKind.KeyOfKeyword, newTypeVariable || typeToTypeNodeHelper(getModifiersTypeFromMappedType(type), context)); } @@ -6778,9 +7072,14 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { else { appropriateConstraintTypeNode = typeToTypeNodeHelper(getConstraintTypeFromMappedType(type), context); } - const typeParameterNode = typeParameterToDeclarationWithConstraint(getTypeParameterFromMappedType(type), context, appropriateConstraintTypeNode); + const typeParameterNode = typeParameterToDeclarationWithConstraint(typeParameter, context, appropriateConstraintTypeNode); + + // nameType and templateType nodes have to be in the new scope + const cleanup = enterNewScope(context, type.declaration, /*expandedParams*/ undefined, [getDeclaredTypeOfTypeParameter(getSymbolOfDeclaration(type.declaration.typeParameter))]); const nameTypeNode = type.declaration.nameType ? typeToTypeNodeHelper(getNameTypeFromMappedType(type)!, context) : undefined; - const templateTypeNode = typeToTypeNodeHelper(removeMissingType(getTemplateTypeFromMappedType(type), !!(getMappedTypeModifiers(type) & MappedTypeModifiers.IncludeOptional)), context); + const templateTypeNode = typeToTypeNodeHelper(removeMissingType(templateType, !!(getMappedTypeModifiers(type) & MappedTypeModifiers.IncludeOptional)), context); + cleanup(); + const mappedTypeNode = factory.createMappedTypeNode(readonlyToken, typeParameterNode, nameTypeNode, questionToken, templateTypeNode, /*members*/ undefined); context.approximateLength += 10; const result = setEmitFlags(mappedTypeNode, EmitFlags.SingleLine); @@ -6811,7 +7110,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return result; } - function createAnonymousTypeNode(type: ObjectType): TypeNode { + function createAnonymousTypeNode(type: ObjectType, forceClassExpansion = false, forceExpansion = false): TypeNode { const typeId = type.id; const symbol = type.symbol; if (symbol) { @@ -6844,15 +7143,26 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } // Always use 'typeof T' for type of class, enum, and module objects else if ( - symbol.flags & SymbolFlags.Class - && !getBaseTypeVariableOfClass(symbol) - && !(symbol.valueDeclaration && isClassLike(symbol.valueDeclaration) && context.flags & NodeBuilderFlags.WriteClassExpressionAsTypeLiteral && (!isClassDeclaration(symbol.valueDeclaration) || isSymbolAccessible(symbol, context.enclosingDeclaration, isInstanceType, /*shouldComputeAliasesToMakeVisible*/ false).accessibility !== SymbolAccessibility.Accessible)) || - symbol.flags & (SymbolFlags.Enum | SymbolFlags.ValueModule) || - shouldWriteTypeOfFunctionSymbol() + !forceExpansion && + (symbol.flags & SymbolFlags.Class + && !forceClassExpansion + && !getBaseTypeVariableOfClass(symbol) + && !(symbol.valueDeclaration + && isClassLike(symbol.valueDeclaration) + && context.flags & NodeBuilderFlags.WriteClassExpressionAsTypeLiteral + && (!isClassDeclaration(symbol.valueDeclaration) + || isSymbolAccessible(symbol, context.enclosingDeclaration, isInstanceType, /*shouldComputeAliasesToMakeVisible*/ false).accessibility !== SymbolAccessibility.Accessible)) + || symbol.flags & (SymbolFlags.Enum | SymbolFlags.ValueModule) + || shouldWriteTypeOfFunctionSymbol()) ) { - return symbolToTypeNode(symbol, context, isInstanceType); + if (shouldExpandType(type, context)) { + context.depth += 1; + } + else { + return symbolToTypeNode(symbol, context, isInstanceType); + } } - else if (context.visitedTypes?.has(typeId)) { + if (context.visitedTypes?.has(typeId)) { // If type is an anonymous type literal in a type alias declaration, use type alias name const typeAlias = getTypeAliasForTypeLiteral(type); if (typeAlias) { @@ -6901,7 +7211,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { context.symbolDepth = new Map(); } - const links = context.enclosingDeclaration && getNodeLinks(context.enclosingDeclaration); + // Don't rely on type cache if we're expand a type, because we need to compute `canIncreaseExpansionDepth`. + const links = context.maxExpansionDepth >= 0 ? undefined : context.enclosingDeclaration && getNodeLinks(context.enclosingDeclaration); const key = `${getTypeId(type)}|${context.flags}|${context.internalFlags}`; if (links) { links.serializedTypes ||= new Map(); @@ -6980,7 +7291,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (isGenericMappedType(type) || (type as MappedType).containsError) { return createMappedTypeNodeFromType(type as MappedType); } - const resolved = resolveStructuredTypeMembers(type); if (!resolved.properties.length && !resolved.indexInfos.length) { if (!resolved.callSignatures.length && !resolved.constructSignatures.length) { @@ -7003,7 +7313,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const abstractSignatures = filter(resolved.constructSignatures, signature => !!(signature.flags & SignatureFlags.Abstract)); if (some(abstractSignatures)) { - const types = map(abstractSignatures, s => getOrCreateTypeFromSignature(s)); + const types = map(abstractSignatures, getOrCreateTypeFromSignature); // count the number of type elements excluding abstract constructors const typeElementCount = resolved.callSignatures.length + (resolved.constructSignatures.length - abstractSignatures.length) + @@ -7262,11 +7572,13 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function createTypeNodesFromResolvedType(resolvedType: ResolvedType): TypeElement[] | undefined { if (checkTruncationLength(context)) { + context.out.truncated = true; if (context.flags & NodeBuilderFlags.NoTruncation) { return [addSyntheticTrailingComment(factory.createNotEmittedTypeElement(), SyntaxKind.MultiLineCommentTrivia, "elided")]; } return [factory.createPropertySignature(/*modifiers*/ undefined, "...", /*questionToken*/ undefined, /*type*/ undefined)]; } + context.typeStack.push(-1); const typeElements: TypeElement[] = []; for (const signature of resolvedType.callSignatures) { typeElements.push(signatureToSignatureDeclarationHelper(signature, SyntaxKind.CallSignature, context) as CallSignatureDeclaration); @@ -7281,11 +7593,15 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const properties = resolvedType.properties; if (!properties) { + context.typeStack.pop(); return typeElements; } let i = 0; for (const propertySymbol of properties) { + if (isExpanding(context) && propertySymbol.flags & SymbolFlags.Prototype) { + continue; + } i++; if (context.flags & NodeBuilderFlags.WriteClassExpressionAsTypeLiteral) { if (propertySymbol.flags & SymbolFlags.Prototype) { @@ -7296,6 +7612,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } if (checkTruncationLength(context) && (i + 2 < properties.length - 1)) { + context.out.truncated = true; if (context.flags & NodeBuilderFlags.NoTruncation) { const typeElement = typeElements.pop()!; typeElements.push(addSyntheticTrailingComment(typeElement, SyntaxKind.MultiLineCommentTrivia, `... ${properties.length - i} more elided ...`)); @@ -7308,6 +7625,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } addPropertyToElementList(propertySymbol, context, typeElements); } + context.typeStack.pop(); return typeElements.length ? typeElements : undefined; } } @@ -7387,27 +7705,51 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (propertySymbol.flags & SymbolFlags.Accessor) { const writeType = getWriteTypeOfSymbol(propertySymbol); - if (propertyType !== writeType && !isErrorType(propertyType) && !isErrorType(writeType)) { + if (!isErrorType(propertyType) && !isErrorType(writeType)) { const symbolMapper = getSymbolLinks(propertySymbol).mapper; - const getterDeclaration = getDeclarationOfKind(propertySymbol, SyntaxKind.GetAccessor)!; - const getterSignature = getSignatureFromDeclaration(getterDeclaration); - typeElements.push( - setCommentRange( - context, - signatureToSignatureDeclarationHelper(symbolMapper ? instantiateSignature(getterSignature, symbolMapper) : getterSignature, SyntaxKind.GetAccessor, context, { name: propertyName }) as GetAccessorDeclaration, - getterDeclaration, - ), - ); - const setterDeclaration = getDeclarationOfKind(propertySymbol, SyntaxKind.SetAccessor)!; - const setterSignature = getSignatureFromDeclaration(setterDeclaration); - typeElements.push( - setCommentRange( - context, - signatureToSignatureDeclarationHelper(symbolMapper ? instantiateSignature(setterSignature, symbolMapper) : setterSignature, SyntaxKind.SetAccessor, context, { name: propertyName }) as SetAccessorDeclaration, - setterDeclaration, - ), - ); - return; + const propDeclaration = getDeclarationOfKind(propertySymbol, SyntaxKind.PropertyDeclaration); + if (propertyType !== writeType || propertySymbol.parent!.flags & SymbolFlags.Class && !propDeclaration) { + const getterDeclaration = getDeclarationOfKind(propertySymbol, SyntaxKind.GetAccessor); + if (getterDeclaration) { + const getterSignature = getSignatureFromDeclaration(getterDeclaration); + typeElements.push( + setCommentRange( + context, + signatureToSignatureDeclarationHelper(symbolMapper ? instantiateSignature(getterSignature, symbolMapper) : getterSignature, SyntaxKind.GetAccessor, context, { name: propertyName }) as GetAccessorDeclaration, + getterDeclaration, + ), + ); + } + const setterDeclaration = getDeclarationOfKind(propertySymbol, SyntaxKind.SetAccessor); + if (setterDeclaration) { + const setterSignature = getSignatureFromDeclaration(setterDeclaration); + typeElements.push( + setCommentRange( + context, + signatureToSignatureDeclarationHelper(symbolMapper ? instantiateSignature(setterSignature, symbolMapper) : setterSignature, SyntaxKind.SetAccessor, context, { name: propertyName }) as SetAccessorDeclaration, + setterDeclaration, + ), + ); + } + return; + } + if (propertySymbol.parent!.flags & SymbolFlags.Class && propDeclaration && find(propDeclaration.modifiers, isAccessorModifier)) { + const fakeGetterSignature = createSignature(/*declaration*/ undefined, /*typeParameters*/ undefined, /*thisParameter*/ undefined, emptyArray, propertyType, /*resolvedTypePredicate*/ undefined, 0, SignatureFlags.None); + typeElements.push( + setCommentRange( + context, + signatureToSignatureDeclarationHelper(fakeGetterSignature, SyntaxKind.GetAccessor, context, { name: propertyName }) as GetAccessorDeclaration, + propDeclaration, + ), + ); + const setterParam = createSymbol(SymbolFlags.FunctionScopedVariable, "arg" as __String); + setterParam.links.type = writeType; + const fakeSetterSignature = createSignature(/*declaration*/ undefined, /*typeParameters*/ undefined, /*thisParameter*/ undefined, [setterParam], voidType, /*resolvedTypePredicate*/ undefined, 0, SignatureFlags.None); + typeElements.push( + signatureToSignatureDeclarationHelper(fakeSetterSignature, SyntaxKind.SetAccessor, context, { name: propertyName }) as SetAccessorDeclaration, + ); + return; + } } } @@ -7477,6 +7819,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function mapToTypeNodes(types: readonly Type[] | undefined, context: NodeBuilderContext, isBareList?: boolean): TypeNode[] | undefined { if (some(types)) { if (checkTruncationLength(context)) { + context.out.truncated = true; if (!isBareList) { return [ context.flags & NodeBuilderFlags.NoTruncation @@ -7502,6 +7845,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { for (const type of types) { i++; if (checkTruncationLength(context) && (i + 2 < types.length - 1)) { + context.out.truncated = true; result.push( context.flags & NodeBuilderFlags.NoTruncation ? addSyntheticLeadingComment(factory.createKeywordTypeNode(SyntaxKind.AnyKeyword), SyntaxKind.MultiLineCommentTrivia, `... ${types.length - i} more elided ...`) @@ -7928,7 +8272,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function typeToTypeNodeHelperWithPossibleReusableTypeNode(type: Type, typeNode: TypeNode | undefined, context: NodeBuilderContext) { - return typeNode && getTypeFromTypeNode(context, typeNode) === type && syntacticNodeBuilder.tryReuseExistingTypeNode(context, typeNode) + return !canPossiblyExpandType(type, context) && typeNode && getTypeFromTypeNode(context, typeNode) === type && syntacticNodeBuilder.tryReuseExistingTypeNode(context, typeNode) || typeToTypeNodeHelper(type, context); } @@ -8501,13 +8845,15 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { let firstChar = symbolName.charCodeAt(0); if (isSingleOrDoubleQuote(firstChar) && some(symbol.declarations, hasNonGlobalAugmentationExternalModuleSymbol)) { - return factory.createStringLiteral(getSpecifierForModuleSymbol(symbol, context)); + const specifier = getSpecifierForModuleSymbol(symbol, context); + context.approximateLength += 2 + specifier.length; // "specifier" + return factory.createStringLiteral(specifier); } if (index === 0 || canUsePropertyAccess(symbolName, languageVersion)) { const identifier = setEmitFlags(factory.createIdentifier(symbolName), EmitFlags.NoAsciiEscaping); if (typeParameterNodes) setIdentifierTypeArguments(identifier, factory.createNodeArray(typeParameterNodes)); identifier.symbol = symbol; - + context.approximateLength += 1 + symbolName.length; // .symbolName return index > 0 ? factory.createPropertyAccessExpression(createExpressionFromSymbolChain(chain, index - 1), identifier) : identifier; } else { @@ -8517,17 +8863,22 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } let expression: Expression | undefined; if (isSingleOrDoubleQuote(firstChar) && !(symbol.flags & SymbolFlags.EnumMember)) { - expression = factory.createStringLiteral(stripQuotes(symbolName).replace(/\\./g, s => s.substring(1)), firstChar === CharacterCodes.singleQuote); + const literalText = stripQuotes(symbolName).replace(/\\./g, s => s.substring(1)); + context.approximateLength += literalText.length + 2; // "literalText" + expression = factory.createStringLiteral(literalText, firstChar === CharacterCodes.singleQuote); } else if (("" + +symbolName) === symbolName) { + context.approximateLength += symbolName.length; // +symbolName expression = factory.createNumericLiteral(+symbolName); } if (!expression) { const identifier = setEmitFlags(factory.createIdentifier(symbolName), EmitFlags.NoAsciiEscaping); if (typeParameterNodes) setIdentifierTypeArguments(identifier, factory.createNodeArray(typeParameterNodes)); identifier.symbol = symbol; + context.approximateLength += symbolName.length; // symbolName expression = identifier; } + context.approximateLength += 2; // [] return factory.createElementAccessExpression(createExpressionFromSymbolChain(chain, index - 1), expression); } } @@ -8555,6 +8906,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function getPropertyNameNodeForSymbol(symbol: Symbol, context: NodeBuilderContext) { + const hashPrivateName = getClonedHashPrivateName(symbol); + if (hashPrivateName) { + return hashPrivateName; + } const stringNamed = !!length(symbol.declarations) && every(symbol.declarations, isStringNamed); const singleQuote = !!length(symbol.declarations) && every(symbol.declarations, isSingleQuotedStringNamed); const isMethod = !!(symbol.flags & SymbolFlags.Method); @@ -8667,7 +9022,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { let result; const addUndefinedForParameter = declaration && (isParameter(declaration) || isJSDocParameterTag(declaration)) && requiresAddingImplicitUndefined(declaration, context.enclosingDeclaration); const decl = declaration ?? symbol.valueDeclaration ?? getDeclarationWithTypeAnnotation(symbol) ?? symbol.declarations?.[0]; - if (decl) { + if (!canPossiblyExpandType(type, context) && decl) { const restore = addSymbolTypeToContext(context, symbol, type); if (isAccessor(decl)) { result = syntacticNodeBuilder.serializeTypeOfAccessor(decl, symbol, context); @@ -8717,7 +9072,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const returnType = getReturnTypeOfSignature(signature); if (!(suppressAny && isTypeAny(returnType))) { - if (signature.declaration && !nodeIsSynthesized(signature.declaration)) { + if (signature.declaration && !nodeIsSynthesized(signature.declaration) && !canPossiblyExpandType(returnType, context)) { const declarationSymbol = getSymbolOfDeclaration(signature.declaration); const restore = addSymbolTypeToContext(context, declarationSymbol, returnType); returnTypeNode = syntacticNodeBuilder.serializeReturnTypeForSignature(signature.declaration, declarationSymbol, context); @@ -9146,9 +9501,18 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (!suppressNewPrivateContext) { deferredPrivatesStack.push(new Map()); } - symbolTable.forEach((symbol: Symbol) => { + let i = 0; + const symbols = Array.from(symbolTable.values()); + for (const symbol of symbols) { + i++; + if (checkTruncationLengthIfExpanding(context) && (i + 2 < symbolTable.size - 1)) { + context.out.truncated = true; + results.push(createTruncationStatement(`... (${symbolTable.size - i} more ...)`)); + serializeSymbol(symbols[symbols.length - 1], /*isPrivate*/ false, !!propertyAsAlias); + break; + } serializeSymbol(symbol, /*isPrivate*/ false, !!propertyAsAlias); - }); + } if (!suppressNewPrivateContext) { // deferredPrivates will be filled up by visiting the symbol table // And will continue to iterate as elements are added while visited `deferredPrivates` @@ -9274,6 +9638,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { && type.symbol?.valueDeclaration && isSourceFile(type.symbol.valueDeclaration) ) { const alias = localName === propertyAccessRequire.parent.right.escapedText ? undefined : propertyAccessRequire.parent.right; + context.approximateLength += 12 + ((alias?.escapedText as string | undefined)?.length ?? 0); // `export { alias };` addResult( factory.createExportDeclaration( /*modifiers*/ undefined, @@ -9295,6 +9660,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ), textRange, ); + context.approximateLength += 7 + name.length; // `var name: ;` addResult(statement, name !== localName ? modifierFlags & ~ModifierFlags.Export : modifierFlags); if (name !== localName && !isPrivate) { // We rename the variable declaration we generate for Property symbols since they may have a name which @@ -9318,6 +9684,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // export { g_1 as g }; // ``` // To create an export named `g` that does _not_ shadow the local `g` + context.approximateLength += 16 + name.length + localName.length; // `export { name as localName };` addResult( factory.createExportDeclaration( /*modifiers*/ undefined, @@ -9372,19 +9739,26 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { for (const node of symbol.declarations) { const resolvedModule = resolveExternalModuleName(node, (node as ExportDeclaration).moduleSpecifier!); if (!resolvedModule) continue; - addResult(factory.createExportDeclaration(/*modifiers*/ undefined, /*isTypeOnly*/ (node as ExportDeclaration).isTypeOnly, /*exportClause*/ undefined, factory.createStringLiteral(getSpecifierForModuleSymbol(resolvedModule, context))), ModifierFlags.None); + const isTypeOnly = (node as ExportDeclaration).isTypeOnly; + const specifier = getSpecifierForModuleSymbol(resolvedModule, context); + context.approximateLength += 17 + specifier.length; // `export * from "specifier";` + addResult(factory.createExportDeclaration(/*modifiers*/ undefined, isTypeOnly, /*exportClause*/ undefined, factory.createStringLiteral(specifier)), ModifierFlags.None); } } } if (needsPostExportDefault) { - addResult(factory.createExportAssignment(/*modifiers*/ undefined, /*isExportEquals*/ false, factory.createIdentifier(getInternalSymbolName(symbol, symbolName))), ModifierFlags.None); + const internalSymbolName = getInternalSymbolName(symbol, symbolName); + context.approximateLength += 16 + internalSymbolName.length; // `export default internalName;` + addResult(factory.createExportAssignment(/*modifiers*/ undefined, /*isExportEquals*/ false, factory.createIdentifier(internalSymbolName)), ModifierFlags.None); } else if (needsExportDeclaration) { + const internalSymbolName = getInternalSymbolName(symbol, symbolName); + context.approximateLength += 22 + symbolName.length + internalSymbolName.length; // `export { internalName as symbolName };` addResult( factory.createExportDeclaration( /*modifiers*/ undefined, /*isTypeOnly*/ false, - factory.createNamedExports([factory.createExportSpecifier(/*isTypeOnly*/ false, getInternalSymbolName(symbol, symbolName), symbolName)]), + factory.createNamedExports([factory.createExportSpecifier(/*isTypeOnly*/ false, internalSymbolName, symbolName)]), ), ModifierFlags.None, ); @@ -9415,6 +9789,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // Prepends a `declare` and/or `export` modifier if the context requires it, and then adds `node` to `result` and returns `node` function addResult(node: Statement, additionalModifierFlags: ModifierFlags) { if (canHaveModifiers(node)) { + const oldModifierFlags = getEffectiveModifierFlags(node); let newModifierFlags: ModifierFlags = ModifierFlags.None; const enclosingDeclaration = context.enclosingDeclaration && (isJSDocTypeAlias(context.enclosingDeclaration) ? getSourceFileOfNode(context.enclosingDeclaration) : context.enclosingDeclaration); @@ -9438,8 +9813,9 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { newModifierFlags |= ModifierFlags.Default; } if (newModifierFlags) { - node = factory.replaceModifiers(node, newModifierFlags | getEffectiveModifierFlags(node)); + node = factory.replaceModifiers(node, newModifierFlags | oldModifierFlags); } + context.approximateLength += modifiersLength(newModifierFlags | oldModifierFlags); } results.push(node); } @@ -9458,9 +9834,11 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { && isJSDocTypeExpression(jsdocAliasDecl.typeExpression) && syntacticNodeBuilder.tryReuseExistingTypeNode(context, jsdocAliasDecl.typeExpression.type) || typeToTypeNodeHelper(aliasType, context); + const internalSymbolName = getInternalSymbolName(symbol, symbolName); + context.approximateLength += 8 + (commentText?.length ?? 0) + internalSymbolName.length; // `/* comment */ type name = ...` addResult( setSyntheticLeadingComments( - factory.createTypeAliasDeclaration(/*modifiers*/ undefined, getInternalSymbolName(symbol, symbolName), typeParamDecls, typeNode), + factory.createTypeAliasDeclaration(/*modifiers*/ undefined, internalSymbolName, typeParamDecls, typeNode), !commentText ? [] : [{ kind: SyntaxKind.MultiLineCommentTrivia, text: "*\n * " + commentText.replace(/\n/g, "\n * ") + "\n ", pos: -1, end: -1, hasTrailingNewLine: true }], ), modifierFlags, @@ -9470,12 +9848,14 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function serializeInterface(symbol: Symbol, symbolName: string, modifierFlags: ModifierFlags) { + const internalSymbolName = getInternalSymbolName(symbol, symbolName); + context.approximateLength += 14 + internalSymbolName.length; // `interface name { }` const interfaceType = getDeclaredTypeOfClassOrInterface(symbol); const localParams = getLocalTypeParametersOfClassOrInterfaceOrTypeAlias(symbol); const typeParamDecls = map(localParams, p => typeParameterToDeclaration(p, context)); const baseTypes = getBaseTypes(interfaceType); const baseType = length(baseTypes) ? getIntersectionType(baseTypes) : undefined; - const members = flatMap(getPropertiesOfType(interfaceType), p => serializePropertySymbolForInterface(p, baseType)); + const members = serializePropertySymbolsForClassOrInterface(getPropertiesOfType(interfaceType), /*isClass*/ false, baseType); const callSignatures = serializeSignatures(SignatureKind.Call, interfaceType, baseType, SyntaxKind.CallSignature) as CallSignatureDeclaration[]; const constructSignatures = serializeSignatures(SignatureKind.Construct, interfaceType, baseType, SyntaxKind.ConstructSignature) as ConstructSignatureDeclaration[]; const indexSignatures = serializeIndexSignatures(interfaceType, baseType); @@ -9484,7 +9864,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { addResult( factory.createInterfaceDeclaration( /*modifiers*/ undefined, - getInternalSymbolName(symbol, symbolName), + internalSymbolName, typeParamDecls, heritageClauses, [...indexSignatures, ...constructSignatures, ...callSignatures, ...members], @@ -9493,6 +9873,63 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ); } + function serializePropertySymbolsForClassOrInterface(props: readonly Symbol[], isClass: false, baseType: Type | undefined): TypeElement[]; + function serializePropertySymbolsForClassOrInterface(props: readonly Symbol[], isClass: true, baseType: Type | undefined, isStatic: boolean): ClassElement[]; + function serializePropertySymbolsForClassOrInterface(props: readonly Symbol[], isClass: boolean, baseType: Type | undefined, isStatic?: boolean): (ClassElement | TypeElement)[] { + const elements: (ClassElement | TypeElement)[] = []; + let i = 0; + for (const prop of props) { + i++; + if (checkTruncationLengthIfExpanding(context) && (i + 2 < props.length - 1)) { + context.out.truncated = true; + const placeholder = createTruncationProperty(`... ${props.length - i} more ... `, isClass); + elements.push(placeholder); + const result = isClass ? + serializePropertySymbolForClass(props[props.length - 1], isStatic!, baseType) : + serializePropertySymbolForInterface(props[props.length - 1], baseType); + if (isArray(result)) { + elements.push(...result); + } + else { + elements.push(result); + } + break; + } + + context.approximateLength += 1; // separator + const result = isClass ? + serializePropertySymbolForClass(prop, isStatic!, baseType) : + serializePropertySymbolForInterface(prop, baseType); + if (isArray(result)) { + elements.push(...result); + } + else { + elements.push(result); + } + } + return elements; + } + + function createTruncationProperty(dotDotDotText: string, isClass: boolean): TypeElement | ClassElement { + if (context.flags & NodeBuilderFlags.NoTruncation) { + return addSyntheticLeadingComment(factory.createNotEmittedTypeElement(), SyntaxKind.MultiLineCommentTrivia, dotDotDotText); + } + return isClass ? + factory.createPropertyDeclaration( + /*modifiers*/ undefined, + dotDotDotText, + /*questionOrExclamationToken*/ undefined, + /*type*/ undefined, + /*initializer*/ undefined, + ) : + factory.createPropertySignature( + /*modifiers*/ undefined, + dotDotDotText, + /*questionToken*/ undefined, + /*type*/ undefined, + ); + } + function getNamespaceMembersForSerialization(symbol: Symbol) { let exports = arrayFrom(getExportsOfSymbol(symbol).values()); const merged = getMergedSymbol(symbol); @@ -9514,15 +9951,28 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function serializeModule(symbol: Symbol, symbolName: string, modifierFlags: ModifierFlags) { const members = getNamespaceMembersForSerialization(symbol); + const expanding = isExpanding(context); // Split NS members up by declaration - members whose parent symbol is the ns symbol vs those whose is not (but were added in later via merging) - const locationMap = arrayToMultiMap(members, m => m.parent && m.parent === symbol ? "real" : "merged"); + const locationMap = arrayToMultiMap(members, m => m.parent && m.parent === symbol || expanding ? "real" : "merged"); const realMembers = locationMap.get("real") || emptyArray; const mergedMembers = locationMap.get("merged") || emptyArray; // TODO: `suppressNewPrivateContext` is questionable -we need to simply be emitting privates in whatever scope they were declared in, rather // than whatever scope we traverse to them in. That's a bit of a complex rewrite, since we're not _actually_ tracking privates at all in advance, // so we don't even have placeholders to fill in. - if (length(realMembers)) { - const localName = getInternalSymbolName(symbol, symbolName); + if (length(realMembers) || expanding) { + let localName: ModuleName; + if (expanding) { + // Use the same name as symbol display. + const oldFlags = context.flags; + context.flags |= NodeBuilderFlags.WriteTypeParametersInQualifiedName | SymbolFormatFlags.UseOnlyExternalAliasing; + localName = symbolToNode(symbol, context, /*meaning*/ SymbolFlags.All) as ModuleName; + context.flags = oldFlags; + } + else { + const localText = getInternalSymbolName(symbol, symbolName); + localName = factory.createIdentifier(localText); + context.approximateLength += localText.length; + } serializeAsNamespaceDeclaration(realMembers, localName, modifierFlags, !!(symbol.flags & (SymbolFlags.Function | SymbolFlags.Assignment))); } if (length(mergedMembers)) { @@ -9558,23 +10008,62 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function serializeEnum(symbol: Symbol, symbolName: string, modifierFlags: ModifierFlags) { + const internalSymbolName = getInternalSymbolName(symbol, symbolName); + context.approximateLength += 9 + internalSymbolName.length; // `enum internalName { }` + const members: EnumMember[] = []; + const memberProps = filter(getPropertiesOfType(getTypeOfSymbol(symbol)), p => !!(p.flags & SymbolFlags.EnumMember)); + let i = 0; + for (const p of memberProps) { + i++; + if (checkTruncationLengthIfExpanding(context) && (i + 2 < memberProps.length - 1)) { + context.out.truncated = true; + members.push(factory.createEnumMember(` ... ${memberProps.length - i} more ... `)); + const last = memberProps[memberProps.length - 1]; + const initializedValue = last.declarations && last.declarations[0] && isEnumMember(last.declarations[0]) ? getConstantValue(last.declarations[0]) : undefined; + const initializer = initializedValue === undefined ? undefined : + typeof initializedValue === "string" ? factory.createStringLiteral(initializedValue) : + factory.createNumericLiteral(initializedValue); + const memberName = unescapeLeadingUnderscores(last.escapedName); + const member = factory.createEnumMember( + memberName, + initializer, + ); + members.push(member); + break; + } + // TODO: Handle computed names + // I hate that to get the initialized value we need to walk back to the declarations here; but there's no + // other way to get the possible const value of an enum member that I'm aware of, as the value is cached + // _on the declaration_, not on the declaration's symbol... + const memberDecl = p.declarations && p.declarations[0] && isEnumMember(p.declarations[0]) ? + p.declarations[0] : + undefined; + let initializer: Expression | undefined; + let initializerLength: number; + if (isExpanding(context) && memberDecl && memberDecl.initializer) { + initializer = getSynthesizedDeepClone(memberDecl.initializer); + initializerLength = memberDecl.initializer.end - memberDecl.initializer.pos; + } + else { + const initializedValue = memberDecl && getConstantValue(memberDecl); + initializer = initializedValue === undefined ? undefined : + typeof initializedValue === "string" ? factory.createStringLiteral(initializedValue) : + factory.createNumericLiteral(initializedValue); + initializerLength = (initializer as StringLiteral | NumericLiteral | undefined)?.text.length ?? 0; + } + const memberName = unescapeLeadingUnderscores(p.escapedName); + context.approximateLength += 4 + memberName.length + initializerLength; // `member = initializer,` + const member = factory.createEnumMember( + memberName, + initializer, + ); + members.push(member); + } addResult( factory.createEnumDeclaration( factory.createModifiersFromModifierFlags(isConstEnumSymbol(symbol) ? ModifierFlags.Const : 0), - getInternalSymbolName(symbol, symbolName), - map(filter(getPropertiesOfType(getTypeOfSymbol(symbol)), p => !!(p.flags & SymbolFlags.EnumMember)), p => { - // TODO: Handle computed names - // I hate that to get the initialized value we need to walk back to the declarations here; but there's no - // other way to get the possible const value of an enum member that I'm aware of, as the value is cached - // _on the declaration_, not on the declaration's symbol... - const initializedValue = p.declarations && p.declarations[0] && isEnumMember(p.declarations[0]) ? getConstantValue(p.declarations[0]) : undefined; - return factory.createEnumMember( - unescapeLeadingUnderscores(p.escapedName), - initializedValue === undefined ? undefined : - typeof initializedValue === "string" ? factory.createStringLiteral(initializedValue) : - factory.createNumericLiteral(initializedValue), - ); - }), + internalSymbolName, + members, ), modifierFlags, ); @@ -9583,6 +10072,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function serializeAsFunctionNamespaceMerge(type: Type, symbol: Symbol, localName: string, modifierFlags: ModifierFlags) { const signatures = getSignaturesOfType(type, SignatureKind.Call); for (const sig of signatures) { + context.approximateLength += 1; // ; // Each overload becomes a separate function declaration, in order const decl = signatureToSignatureDeclarationHelper(sig, SyntaxKind.FunctionDeclaration, context, { name: factory.createIdentifier(localName) }) as FunctionDeclaration; addResult(setTextRange(context, decl, getSignatureTextRangeLocation(sig)), modifierFlags); @@ -9590,8 +10080,16 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // Module symbol emit will take care of module-y members, provided it has exports if (!(symbol.flags & (SymbolFlags.ValueModule | SymbolFlags.NamespaceModule) && !!symbol.exports && !!symbol.exports.size)) { const props = filter(getPropertiesOfType(type), isNamespaceMember); - serializeAsNamespaceDeclaration(props, localName, modifierFlags, /*suppressNewPrivateContext*/ true); + context.approximateLength += localName.length; + serializeAsNamespaceDeclaration(props, factory.createIdentifier(localName), modifierFlags, /*suppressNewPrivateContext*/ true); + } + } + + function createTruncationStatement(dotDotDotText: string): Statement { + if (context.flags & NodeBuilderFlags.NoTruncation) { + return addSyntheticLeadingComment(factory.createEmptyStatement(), SyntaxKind.MultiLineCommentTrivia, dotDotDotText); } + return factory.createExpressionStatement(factory.createIdentifier(dotDotDotText)); } function getSignatureTextRangeLocation(signature: Signature) { @@ -9607,9 +10105,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return signature.declaration; } - function serializeAsNamespaceDeclaration(props: readonly Symbol[], localName: string, modifierFlags: ModifierFlags, suppressNewPrivateContext: boolean) { + function serializeAsNamespaceDeclaration(props: readonly Symbol[], localName: ModuleName, modifierFlags: ModifierFlags, suppressNewPrivateContext: boolean) { + const nodeFlags = isIdentifier(localName) ? NodeFlags.Namespace : NodeFlags.None; + const expanding = isExpanding(context); if (length(props)) { - const localVsRemoteMap = arrayToMultiMap(props, p => !length(p.declarations) || some(p.declarations, d => getSourceFileOfNode(d) === getSourceFileOfNode(context.enclosingDeclaration!)) ? "local" : "remote"); + context.approximateLength += 14; // "namespace { }" + const localVsRemoteMap = arrayToMultiMap(props, p => !length(p.declarations) || some(p.declarations, d => getSourceFileOfNode(d) === getSourceFileOfNode(context.enclosingDeclaration!)) || expanding ? "local" : "remote"); const localProps = localVsRemoteMap.get("local") || emptyArray; // handle remote props first - we need to make an `import` declaration that points at the module containing each remote // prop in the outermost scope (TODO: a namespace within a namespace would need to be appropriately handled by this) @@ -9628,7 +10129,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // Add a namespace // Create namespace as non-synthetic so it is usable as an enclosing declaration - let fakespace = parseNodeFactory.createModuleDeclaration(/*modifiers*/ undefined, factory.createIdentifier(localName), factory.createModuleBlock([]), NodeFlags.Namespace); + let fakespace = parseNodeFactory.createModuleDeclaration(/*modifiers*/ undefined, localName, factory.createModuleBlock([]), nodeFlags); setParent(fakespace, enclosingDeclaration as SourceFile | NamespaceDeclaration); fakespace.locals = createSymbolTable(props); fakespace.symbol = props[0].parent!; @@ -9662,6 +10163,18 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ); addResult(fakespace, modifierFlags); // namespaces can never be default exported } + else if (expanding) { + context.approximateLength += 14; // "namespace { }" + addResult( + factory.createModuleDeclaration( + /*modifiers*/ undefined, + localName, + factory.createModuleBlock([]), + nodeFlags, + ), + modifierFlags, + ); + } } function isNamespaceMember(p: Symbol) { @@ -9703,11 +10216,13 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function serializeAsClass(symbol: Symbol, localName: string, modifierFlags: ModifierFlags) { + context.approximateLength += 9 + localName.length; // `class localName { }` const originalDecl = symbol.declarations?.find(isClassLike); const oldEnclosing = context.enclosingDeclaration; context.enclosingDeclaration = originalDecl || oldEnclosing; const localParams = getLocalTypeParametersOfClassOrInterfaceOrTypeAlias(symbol); const typeParamDecls = map(localParams, p => typeParameterToDeclaration(p, context)); + forEach(localParams, p => context.approximateLength += symbolName(p.symbol).length); const classType = getTypeWithThisArgument(getDeclaredTypeOfClassOrInterface(symbol)) as InterfaceType; const baseTypes = getBaseTypes(classType); const originalImplements = originalDecl && getEffectiveImplementsTypeNodes(originalDecl); @@ -9718,40 +10233,36 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const staticBaseType = isClass ? getBaseConstructorTypeOfClass(staticType as InterfaceType) : anyType; + context.approximateLength += (length(baseTypes) ? 8 : 0) + (length(implementsExpressions) ? 11 : 0); // `extends ` and `implements ` const heritageClauses = [ ...!length(baseTypes) ? [] : [factory.createHeritageClause(SyntaxKind.ExtendsKeyword, map(baseTypes, b => serializeBaseType(b, staticBaseType, localName)))], ...!length(implementsExpressions) ? [] : [factory.createHeritageClause(SyntaxKind.ImplementsKeyword, implementsExpressions)], ]; const symbolProps = getNonInheritedProperties(classType, baseTypes, getPropertiesOfType(classType)); - const publicSymbolProps = filter(symbolProps, s => { - // `valueDeclaration` could be undefined if inherited from - // a union/intersection base type, but inherited properties - // don't matter here. - const valueDecl = s.valueDeclaration; - return !!valueDecl && !(isNamedDeclaration(valueDecl) && isPrivateIdentifier(valueDecl.name)); - }); - const hasPrivateIdentifier = some(symbolProps, s => { - // `valueDeclaration` could be undefined if inherited from - // a union/intersection base type, but inherited properties - // don't matter here. - const valueDecl = s.valueDeclaration; - return !!valueDecl && isNamedDeclaration(valueDecl) && isPrivateIdentifier(valueDecl.name); - }); + const publicSymbolProps = filter(symbolProps, s => !isHashPrivate(s)); + const hasPrivateIdentifier = some(symbolProps, isHashPrivate); // Boil down all private properties into a single one. const privateProperties = hasPrivateIdentifier ? - [factory.createPropertyDeclaration( - /*modifiers*/ undefined, - factory.createPrivateIdentifier("#private"), - /*questionOrExclamationToken*/ undefined, - /*type*/ undefined, - /*initializer*/ undefined, - )] : + isExpanding(context) ? + serializePropertySymbolsForClassOrInterface(filter(symbolProps, isHashPrivate), /*isClass*/ true, baseTypes[0], /*isStatic*/ false) : + [factory.createPropertyDeclaration( + /*modifiers*/ undefined, + factory.createPrivateIdentifier("#private"), + /*questionOrExclamationToken*/ undefined, + /*type*/ undefined, + /*initializer*/ undefined, + )] : emptyArray; - const publicProperties = flatMap(publicSymbolProps, p => serializePropertySymbolForClass(p, /*isStatic*/ false, baseTypes[0])); + if (hasPrivateIdentifier && !isExpanding(context)) { + context.approximateLength += 9; // `#private;` + } + const publicProperties = serializePropertySymbolsForClassOrInterface(publicSymbolProps, /*isClass*/ true, baseTypes[0], /*isStatic*/ false); // Consider static members empty if symbol also has function or module meaning - function namespacey emit will handle statics - const staticMembers = flatMap( + const staticMembers = serializePropertySymbolsForClassOrInterface( filter(getPropertiesOfType(staticType), p => !(p.flags & SymbolFlags.Prototype) && p.escapedName !== "prototype" && !isNamespaceMember(p)), - p => serializePropertySymbolForClass(p, /*isStatic*/ true, staticBaseType), + /*isClass*/ true, + staticBaseType, + /*isStatic*/ true, ); // When we encounter an `X.prototype.y` assignment in a JS file, we bind `X` as a class regardless as to whether // the value is ever initialized with a class or function-like value. For cases where `X` could never be @@ -9760,6 +10271,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { !!symbol.valueDeclaration && isInJSFile(symbol.valueDeclaration) && !some(getSignaturesOfType(staticType, SignatureKind.Construct)); + if (isNonConstructableClassLikeInJsFile) context.approximateLength += 21; // `private constructor()` const constructors = isNonConstructableClassLikeInJsFile ? [factory.createConstructorDeclaration(factory.createModifiersFromModifierFlags(ModifierFlags.Private), [], /*body*/ undefined)] : serializeSignatures(SignatureKind.Construct, staticType, staticBaseType, SyntaxKind.Constructor) as ConstructorDeclaration[]; @@ -9828,15 +10340,17 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // const { SomeClass } = require('./lib'); const specifier = getSpecifierForModuleSymbol(target.parent || target, context); // './lib' const { propertyName } = node as BindingElement; + const propertyNameText = propertyName && isIdentifier(propertyName) ? idText(propertyName) : undefined; + context.approximateLength += 24 + localName.length + specifier.length + (propertyNameText?.length ?? 0); // `import { propertyName as name } from "specifier";` addResult( factory.createImportDeclaration( /*modifiers*/ undefined, factory.createImportClause( - /*isTypeOnly*/ false, + /*phaseModifier*/ undefined, /*name*/ undefined, factory.createNamedImports([factory.createImportSpecifier( /*isTypeOnly*/ false, - propertyName && isIdentifier(propertyName) ? factory.createIdentifier(idText(propertyName)) : undefined, + propertyNameText ? factory.createIdentifier(propertyNameText) : undefined, factory.createIdentifier(localName), )]), ), @@ -9867,6 +10381,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const uniqueName = factory.createUniqueName(localName); // _x const specifier = getSpecifierForModuleSymbol(target.parent || target, context); // 'y' // import _x = require('y'); + context.approximateLength += 22 + specifier.length + idText(uniqueName).length; // `import uniqueName = require("specifier");` addResult( factory.createImportEqualsDeclaration( /*modifiers*/ undefined, @@ -9877,6 +10392,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ModifierFlags.None, ); // import x = _x.z + context.approximateLength += 12 + localName.length + idText(uniqueName).length + idText(initializer.name).length; // `import localName = uniqueName.initializerName;` addResult( factory.createImportEqualsDeclaration( /*modifiers*/ undefined, @@ -9899,6 +10415,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // Could be a local `import localName = ns.member` or // an external `import localName = require("whatever")` const isLocalImport = !(target.flags & SymbolFlags.ValueModule) && !isVariableDeclaration(node); + context.approximateLength += 11 + localName.length + unescapeLeadingUnderscores(target.escapedName).length; // `import localName = target;` addResult( factory.createImportEqualsDeclaration( /*modifiers*/ undefined, @@ -9922,10 +10439,15 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const specifier = context.bundled ? factory.createStringLiteral(generatedSpecifier) : (node as ImportClause).parent.moduleSpecifier; const attributes = isImportDeclaration(node.parent) ? node.parent.attributes : undefined; const isTypeOnly = isJSDocImportTag((node as ImportClause).parent); + context.approximateLength += 14 + localName.length + 3 + (isTypeOnly ? 4 : 0); // `import localName from specifier;`, approximate specifier addResult( factory.createImportDeclaration( /*modifiers*/ undefined, - factory.createImportClause(isTypeOnly, factory.createIdentifier(localName), /*namedBindings*/ undefined), + factory.createImportClause( + /* phaseModifier */ isTypeOnly ? SyntaxKind.TypeKeyword : undefined, + factory.createIdentifier(localName), + /*namedBindings*/ undefined, + ), specifier, attributes, ), @@ -9937,10 +10459,15 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const generatedSpecifier = getSpecifierForModuleSymbol(target.parent || target, context); // generate specifier (even though we're reusing and existing one) for ambient module reference include side effects const specifier = context.bundled ? factory.createStringLiteral(generatedSpecifier) : (node as NamespaceImport).parent.parent.moduleSpecifier; const isTypeOnly = isJSDocImportTag((node as NamespaceImport).parent.parent); + context.approximateLength += 19 + localName.length + 3 + (isTypeOnly ? 4 : 0); // `import * as localName from specifier;`, approximate specifier addResult( factory.createImportDeclaration( /*modifiers*/ undefined, - factory.createImportClause(isTypeOnly, /*name*/ undefined, factory.createNamespaceImport(factory.createIdentifier(localName))), + factory.createImportClause( + /* phaseModifier */ isTypeOnly ? SyntaxKind.TypeKeyword : undefined, + /*name*/ undefined, + factory.createNamespaceImport(factory.createIdentifier(localName)), + ), specifier, (node as ImportClause).parent.attributes, ), @@ -9949,6 +10476,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { break; } case SyntaxKind.NamespaceExport: + context.approximateLength += 19 + localName.length + 3; // `export * as localName from specifier;`, approximate specifier addResult( factory.createExportDeclaration( /*modifiers*/ undefined, @@ -9963,11 +10491,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const generatedSpecifier = getSpecifierForModuleSymbol(target.parent || target, context); // generate specifier (even though we're reusing and existing one) for ambient module reference include side effects const specifier = context.bundled ? factory.createStringLiteral(generatedSpecifier) : (node as ImportSpecifier).parent.parent.parent.moduleSpecifier; const isTypeOnly = isJSDocImportTag((node as ImportSpecifier).parent.parent.parent); + context.approximateLength += 19 + localName.length + 3 + (isTypeOnly ? 4 : 0); // `import { localName } from specifier;`, approximate specifier addResult( factory.createImportDeclaration( /*modifiers*/ undefined, factory.createImportClause( - isTypeOnly, + /* phaseModifier */ isTypeOnly ? SyntaxKind.TypeKeyword : undefined, /*name*/ undefined, factory.createNamedImports([ factory.createImportSpecifier( @@ -10024,6 +10553,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function serializeExportSpecifier(localName: string, targetName: string, specifier?: Expression) { + context.approximateLength += 16 + localName.length + (localName !== targetName ? targetName.length : 0); // `export { targetName as localName };` addResult( factory.createExportDeclaration( /*modifiers*/ undefined, @@ -10072,6 +10602,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const prevDisableTrackSymbol = context.tracker.disableTrackSymbol; context.tracker.disableTrackSymbol = true; if (isExportAssignmentCompatibleSymbolName) { + context.approximateLength += 10; // `export = ;` results.push(factory.createExportAssignment( /*modifiers*/ undefined, isExportEquals, @@ -10089,6 +10620,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { else { // serialize as `import _Ref = t.arg.et; export { _Ref as name }` const varName = getUnusedName(name, symbol); + context.approximateLength += varName.length + 10; // `import name = ;` addResult( factory.createImportEqualsDeclaration( /*modifiers*/ undefined, @@ -10116,6 +10648,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } else { const flags = context.enclosingDeclaration?.kind === SyntaxKind.ModuleDeclaration && (!(symbol.flags & SymbolFlags.Accessor) || symbol.flags & SymbolFlags.SetAccessor) ? NodeFlags.Let : NodeFlags.Const; + context.approximateLength += varName.length + 5; // `var name: ;` const statement = factory.createVariableStatement( /*modifiers*/ undefined, factory.createVariableDeclarationList([ @@ -10132,6 +10665,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ); } if (isExportAssignmentCompatibleSymbolName) { + context.approximateLength += varName.length + 10; // `export = name;` results.push(factory.createExportAssignment( /*modifiers*/ undefined, isExportEquals, @@ -10208,7 +10742,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ): (p: Symbol, isStatic: boolean, baseType: Type | undefined) => T | AccessorDeclaration | (T | AccessorDeclaration)[] { return function serializePropertySymbol(p: Symbol, isStatic: boolean, baseType: Type | undefined): T | AccessorDeclaration | (T | AccessorDeclaration)[] { const modifierFlags = getDeclarationModifierFlagsFromSymbol(p); - const isPrivate = !!(modifierFlags & ModifierFlags.Private); + const omitType = !!(modifierFlags & ModifierFlags.Private) && !isExpanding(context); if (isStatic && (p.flags & (SymbolFlags.Type | SymbolFlags.Namespace | SymbolFlags.Alias))) { // Only value-only-meaning symbols can be correctly encoded as class statics, type/namespace/alias meaning symbols // need to be merged namespace members @@ -10246,6 +10780,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { Debug.assert(!!setter); const paramSymbol = isFunctionLikeDeclaration(setter) ? getSignatureFromDeclaration(setter).parameters[0] : undefined; const setterDeclaration = p.declarations?.find(isSetAccessor); + context.approximateLength += modifiersLength(flag) + 7 + (paramSymbol ? symbolName(paramSymbol).length : 5) + (omitType ? 0 : 2); // `modifiers set name(param);`, approximate name result.push(setTextRange( context, factory.createSetAccessorDeclaration( @@ -10256,7 +10791,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { /*dotDotDotToken*/ undefined, paramSymbol ? parameterToParameterDeclarationName(paramSymbol, getEffectiveParameterDeclaration(paramSymbol), context) : "value", /*questionToken*/ undefined, - isPrivate ? undefined : serializeTypeForDeclaration(context, setterDeclaration, getWriteTypeOfSymbol(p), p), + omitType ? undefined : serializeTypeForDeclaration(context, setterDeclaration, getWriteTypeOfSymbol(p), p), )], /*body*/ undefined, ), @@ -10264,15 +10799,15 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { )); } if (p.flags & SymbolFlags.GetAccessor) { - const isPrivate = modifierFlags & ModifierFlags.Private; const getterDeclaration = p.declarations?.find(isGetAccessor); + context.approximateLength += modifiersLength(flag) + 8 + (omitType ? 0 : 2); // `modifiers get name(): ;`, approximate name result.push(setTextRange( context, factory.createGetAccessorDeclaration( factory.createModifiersFromModifierFlags(flag), name, [], - isPrivate ? undefined : serializeTypeForDeclaration(context, getterDeclaration, getTypeOfSymbol(p), p), + omitType ? undefined : serializeTypeForDeclaration(context, getterDeclaration, getTypeOfSymbol(p), p), /*body*/ undefined, ), getterDeclaration ?? firstPropertyLikeDecl, @@ -10283,13 +10818,15 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // This is an else/if as accessors and properties can't merge in TS, but might in JS // If this happens, we assume the accessor takes priority, as it imposes more constraints else if (p.flags & (SymbolFlags.Property | SymbolFlags.Variable | SymbolFlags.Accessor)) { + const modifierFlags = (isReadonlySymbol(p) ? ModifierFlags.Readonly : 0) | flag; + context.approximateLength += 2 + (omitType ? 0 : 2) + modifiersLength(modifierFlags); // `modifiers name: ;`, approximate name return setTextRange( context, createProperty( - factory.createModifiersFromModifierFlags((isReadonlySymbol(p) ? ModifierFlags.Readonly : 0) | flag), + factory.createModifiersFromModifierFlags(modifierFlags), name, p.flags & SymbolFlags.Optional ? factory.createToken(SyntaxKind.QuestionToken) : undefined, - isPrivate ? undefined : serializeTypeForDeclaration(context, p.declarations?.find(isSetAccessorDeclaration), getWriteTypeOfSymbol(p), p), + omitType ? undefined : serializeTypeForDeclaration(context, p.declarations?.find(isSetAccessorDeclaration), getWriteTypeOfSymbol(p), p), // TODO: https://github.com/microsoft/TypeScript/pull/32372#discussion_r328386357 // interface members can't have initializers, however class members _can_ /*initializer*/ undefined, @@ -10300,11 +10837,13 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (p.flags & (SymbolFlags.Method | SymbolFlags.Function)) { const type = getTypeOfSymbol(p); const signatures = getSignaturesOfType(type, SignatureKind.Call); - if (flag & ModifierFlags.Private) { + if (omitType) { + const modifierFlags = (isReadonlySymbol(p) ? ModifierFlags.Readonly : 0) | flag; + context.approximateLength += 1 + modifiersLength(modifierFlags); // `modifiers name;`, approximate name return setTextRange( context, createProperty( - factory.createModifiersFromModifierFlags((isReadonlySymbol(p) ? ModifierFlags.Readonly : 0) | flag), + factory.createModifiersFromModifierFlags(modifierFlags), name, p.flags & SymbolFlags.Optional ? factory.createToken(SyntaxKind.QuestionToken) : undefined, /*type*/ undefined, @@ -10316,6 +10855,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const results = []; for (const sig of signatures) { + context.approximateLength += 1; // ; // Each overload becomes a separate method declaration, in order const decl = signatureToSignatureDeclarationHelper( sig, @@ -10337,6 +10877,27 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { }; } + function modifiersLength(flags: ModifierFlags): number { + let result = 0; + // Include the trailing space after the modifier keyword. + if (flags & ModifierFlags.Export) result += 7; + if (flags & ModifierFlags.Ambient) result += 8; + if (flags & ModifierFlags.Default) result += 8; + if (flags & ModifierFlags.Const) result += 6; + if (flags & ModifierFlags.Public) result += 7; + if (flags & ModifierFlags.Private) result += 8; + if (flags & ModifierFlags.Protected) result += 10; + if (flags & ModifierFlags.Abstract) result += 9; + if (flags & ModifierFlags.Static) result += 7; + if (flags & ModifierFlags.Override) result += 9; + if (flags & ModifierFlags.Readonly) result += 9; + if (flags & ModifierFlags.Accessor) result += 9; + if (flags & ModifierFlags.Async) result += 6; + if (flags & ModifierFlags.In) result += 3; + if (flags & ModifierFlags.Out) result += 4; + return result; + } + function serializePropertySymbolForInterface(p: Symbol, baseType: Type | undefined) { return serializePropertySymbolForInterfaceWorker(p, /*isStatic*/ false, baseType); } @@ -10387,6 +10948,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const results = []; for (const sig of signatures) { + context.approximateLength += 1; // ; // Each overload becomes a separate constructor declaration, in order const decl = signatureToSignatureDeclarationHelper(sig, outputKind, context); results.push(setTextRange(context, decl, sig.declaration)); @@ -10506,6 +11068,31 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return localName; } } + + function isExpanding(context: NodeBuilderContext) { + return context.maxExpansionDepth !== -1; + } + + function isHashPrivate(s: Symbol): boolean { + // `valueDeclaration` could be undefined if inherited from + // a union/intersection base type, but inherited properties + // don't matter here. + return !!s.valueDeclaration && isNamedDeclaration(s.valueDeclaration) && isPrivateIdentifier(s.valueDeclaration.name); + } + + function getClonedHashPrivateName(s: Symbol): PrivateIdentifier | undefined { + if (s.valueDeclaration && isNamedDeclaration(s.valueDeclaration) && isPrivateIdentifier(s.valueDeclaration.name)) { + return factory.cloneNode(s.valueDeclaration.name); + } + return undefined; + } + } + + /** Returns true if a type is declared in a lib file. */ + // Don't expand types like `Array` or `Promise`, instead treating them as opaque. + function isLibType(type: Type): boolean { + const symbol = (getObjectFlags(type) & ObjectFlags.Reference) !== 0 ? (type as TypeReference).target.symbol : type.symbol; + return isTupleType(type) || !!(symbol?.declarations?.some(decl => host.isSourceFileDefaultLibrary(getSourceFileOfNode(decl)))); } function typePredicateToString(typePredicate: TypePredicate, enclosingDeclaration?: Node, flags: TypeFormatFlags = TypeFormatFlags.UseAliasDefinedOutsideCurrentScope, writer?: EmitTextWriter): string { @@ -10521,14 +11108,14 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } - function formatUnionTypes(types: readonly Type[]): Type[] { + function formatUnionTypes(types: readonly Type[], expandingEnum: boolean): Type[] { const result: Type[] = []; let flags = 0 as TypeFlags; for (let i = 0; i < types.length; i++) { const t = types[i]; flags |= t.flags; if (!(t.flags & TypeFlags.Nullable)) { - if (t.flags & (TypeFlags.BooleanLiteral | TypeFlags.EnumLike)) { + if (t.flags & (TypeFlags.BooleanLiteral) || !expandingEnum && (t.flags | TypeFlags.EnumLike)) { const baseType = t.flags & TypeFlags.BooleanLiteral ? booleanType : getBaseTypeOfEnumLikeType(t as LiteralType); if (baseType.flags & TypeFlags.Union) { const count = (baseType as UnionType).types.length; @@ -12268,13 +12855,14 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { */ function getWriteTypeOfSymbol(symbol: Symbol): Type { const checkFlags = getCheckFlags(symbol); + if (checkFlags & CheckFlags.SyntheticProperty) { + return checkFlags & CheckFlags.DeferredType ? + getWriteTypeOfSymbolWithDeferredType(symbol) || getTypeOfSymbolWithDeferredType(symbol) : + // NOTE: cast to TransientSymbol should be safe because only TransientSymbols can have CheckFlags.SyntheticProperty + (symbol as TransientSymbol).links.writeType || (symbol as TransientSymbol).links.type!; + } if (symbol.flags & SymbolFlags.Property) { - return checkFlags & CheckFlags.SyntheticProperty ? - checkFlags & CheckFlags.DeferredType ? - getWriteTypeOfSymbolWithDeferredType(symbol) || getTypeOfSymbolWithDeferredType(symbol) : - // NOTE: cast to TransientSymbol should be safe because only TransientSymbols can have CheckFlags.SyntheticProperty - (symbol as TransientSymbol).links.writeType || (symbol as TransientSymbol).links.type! : - removeMissingType(getTypeOfSymbol(symbol), !!(symbol.flags & SymbolFlags.Optional)); + return removeMissingType(getTypeOfSymbol(symbol), !!(symbol.flags & SymbolFlags.Optional)); } if (symbol.flags & SymbolFlags.Accessor) { return checkFlags & CheckFlags.Instantiated ? @@ -13178,9 +13766,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { symbol.declarations.push(member); } if (symbolFlags & SymbolFlags.Value) { - if (!symbol.valueDeclaration || symbol.valueDeclaration.kind !== member.kind) { - symbol.valueDeclaration = member; - } + setValueDeclaration(symbol, member); } } @@ -14893,6 +15479,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function createUnionOrIntersectionProperty(containingType: UnionOrIntersectionType, name: __String, skipObjectFunctionPropertyAugment?: boolean): Symbol | undefined { + let propFlags = SymbolFlags.None; let singleProp: Symbol | undefined; let propSet: Map | undefined; let indexTypes: Type[] | undefined; @@ -14919,6 +15506,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } if (!singleProp) { singleProp = prop; + propFlags = (prop.flags & SymbolFlags.Accessor) || SymbolFlags.Property; } else if (prop !== singleProp) { const isInstantiation = (getTargetSymbol(prop) || prop) === (getTargetSymbol(singleProp) || singleProp); @@ -14941,6 +15529,13 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { propSet.set(id, prop); } } + // classes created by mixins are represented as intersections + // and overriding a property in a derived class redefines it completely at runtime + // so a get accessor can't be merged with a set accessor in a base class, + // for that reason the accessor flags are only used when they are the same in all constituents + if (propFlags & SymbolFlags.Accessor && (prop.flags & SymbolFlags.Accessor) !== (propFlags & SymbolFlags.Accessor)) { + propFlags = (propFlags & ~SymbolFlags.Accessor) | SymbolFlags.Property; + } } if (isUnion && isReadonlySymbol(prop)) { checkFlags |= CheckFlags.Readonly; @@ -14959,6 +15554,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { else if (isUnion) { const indexInfo = !isLateBoundName(name) && getApplicableIndexInfoForName(type, name); if (indexInfo) { + propFlags = (propFlags & ~SymbolFlags.Accessor) | SymbolFlags.Property; checkFlags |= CheckFlags.WritePartial | (indexInfo.isReadonly ? CheckFlags.Readonly : 0); indexTypes = append(indexTypes, isTupleType(type) ? getRestTypeOfTupleType(type) || undefinedType : indexInfo.type); } @@ -15037,7 +15633,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { propTypes.push(type); } addRange(propTypes, indexTypes); - const result = createSymbol(SymbolFlags.Property | (optionalFlag ?? 0), name, syntheticFlag | checkFlags); + const result = createSymbol(propFlags | (optionalFlag ?? 0), name, syntheticFlag | checkFlags); result.links.containingType = containingType; if (!hasNonUniformValueDeclaration && firstValueDeclaration) { result.valueDeclaration = firstValueDeclaration; @@ -15507,6 +16103,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { isInJSFile(declaration) && isValueSignatureDeclaration(declaration) && !hasJSDocParameterTags(declaration) && + !some(declaration.parameters, p => !!getJSDocType(p)) && !getJSDocType(declaration) && !getContextualSignatureForFunctionLikeDeclaration(declaration); if (isUntypedSignatureInJSFile) { @@ -15875,15 +16472,17 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return undefined; } - function getSignatureInstantiation(signature: Signature, typeArguments: readonly Type[] | undefined, isJavascript: boolean, inferredTypeParameters?: readonly TypeParameter[]): Signature { + function getSignatureInstantiation(signature: Signature, typeArguments: Type[] | undefined, isJavascript: boolean, inferredTypeParameters?: readonly TypeParameter[]): Signature { const instantiatedSignature = getSignatureInstantiationWithoutFillingInTypeArguments(signature, fillMissingTypeArguments(typeArguments, signature.typeParameters, getMinTypeArgumentCount(signature.typeParameters), isJavascript)); if (inferredTypeParameters) { const returnSignature = getSingleCallOrConstructSignature(getReturnTypeOfSignature(instantiatedSignature)); if (returnSignature) { const newReturnSignature = cloneSignature(returnSignature); newReturnSignature.typeParameters = inferredTypeParameters; + const newReturnType = getOrCreateTypeFromSignature(newReturnSignature) as AnonymousType; + newReturnType.mapper = instantiatedSignature.mapper; const newInstantiatedSignature = cloneSignature(instantiatedSignature); - newInstantiatedSignature.resolvedReturnType = getOrCreateTypeFromSignature(newReturnSignature); + newInstantiatedSignature.resolvedReturnType = newReturnType; return newInstantiatedSignature; } } @@ -15943,16 +16542,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ); } - function getImplementationSignature(signature: Signature) { - return signature.typeParameters ? - signature.implementationSignatureCache ||= createImplementationSignature(signature) : - signature; - } - - function createImplementationSignature(signature: Signature) { - return signature.typeParameters ? instantiateSignature(signature, createTypeMapper([], [])) : signature; - } - function getBaseSignature(signature: Signature) { const typeParameters = signature.typeParameters; if (typeParameters) { @@ -15974,7 +16563,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return signature; } - function getOrCreateTypeFromSignature(signature: Signature, outerTypeParameters?: TypeParameter[]): ObjectType { + function getOrCreateTypeFromSignature(signature: Signature): ObjectType { // There are two ways to declare a construct signature, one is by declaring a class constructor // using the constructor keyword, and the other is declaring a bare construct signature in an // object type literal or interface (using the new keyword). Each way of declaring a constructor @@ -15985,16 +16574,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // If declaration is undefined, it is likely to be the signature of the default constructor. const isConstructor = kind === undefined || kind === SyntaxKind.Constructor || kind === SyntaxKind.ConstructSignature || kind === SyntaxKind.ConstructorType; - // The type must have a symbol with a `Function` flag and a declaration in order to be correctly flagged as possibly containing - // type variables by `couldContainTypeVariables` - const type = createObjectType(ObjectFlags.Anonymous | ObjectFlags.SingleSignatureType, createSymbol(SymbolFlags.Function, InternalSymbolName.Function)) as SingleSignatureType; - if (signature.declaration && !nodeIsSynthesized(signature.declaration)) { // skip synthetic declarations - keeping those around could be bad, since they lack a parent pointer - type.symbol.declarations = [signature.declaration]; - type.symbol.valueDeclaration = signature.declaration; - } - outerTypeParameters ||= signature.declaration && getOuterTypeParameters(signature.declaration, /*includeThisTypes*/ true); - type.outerTypeParameters = outerTypeParameters; - + const type = createObjectType(ObjectFlags.Anonymous | ObjectFlags.SingleSignatureType, signature.declaration?.symbol); type.members = emptySymbols; type.properties = emptyArray; type.callSignatures = !isConstructor ? [signature] : emptyArray; @@ -19984,6 +20564,14 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return createTypeMapper(map(forwardInferences, i => i.typeParameter), map(forwardInferences, () => unknownType)); } + /** + * Return a type mapper that combines the context's return mapper with a mapper that erases any additional type parameters + * to their inferences at the time of creation. + */ + function createOuterReturnMapper(context: InferenceContext) { + return context.outerReturnMapper ??= mergeTypeMappers(context.returnMapper, cloneInferenceContext(context).mapper); + } + function combineTypeMappers(mapper1: TypeMapper | undefined, mapper2: TypeMapper): TypeMapper { return mapper1 ? makeCompositeTypeMapper(TypeMapKind.Composite, mapper1, mapper2) : mapper2; } @@ -20080,7 +20668,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const links = getNodeLinks(declaration); const target = type.objectFlags & ObjectFlags.Reference ? links.resolvedType! as DeferredTypeReference : type.objectFlags & ObjectFlags.Instantiated ? type.target! : type; - let typeParameters = type.objectFlags & ObjectFlags.SingleSignatureType ? (type as SingleSignatureType).outerTypeParameters : links.outerTypeParameters; + let typeParameters = links.outerTypeParameters; if (!typeParameters) { // The first time an anonymous type is instantiated we compute and store a list of the type // parameters that are in scope (and therefore potentially referenced). For type literals that @@ -20106,19 +20694,17 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const typeArguments = map(typeParameters, t => getMappedType(t, combinedMapper)); const newAliasSymbol = aliasSymbol || type.aliasSymbol; const newAliasTypeArguments = aliasSymbol ? aliasTypeArguments : instantiateTypes(type.aliasTypeArguments, mapper); - const id = (type.objectFlags & ObjectFlags.SingleSignatureType ? "S" : "") + getTypeListId(typeArguments) + getAliasId(newAliasSymbol, newAliasTypeArguments); + const id = getTypeListId(typeArguments) + getAliasId(newAliasSymbol, newAliasTypeArguments); if (!target.instantiations) { target.instantiations = new Map(); target.instantiations.set(getTypeListId(typeParameters) + getAliasId(target.aliasSymbol, target.aliasTypeArguments), target); } let result = target.instantiations.get(id); if (!result) { - if (type.objectFlags & ObjectFlags.SingleSignatureType) { - result = instantiateAnonymousType(type, mapper); - target.instantiations.set(id, result); - return result; + let newMapper = createTypeMapper(typeParameters, typeArguments); + if (target.objectFlags & ObjectFlags.SingleSignatureType && mapper) { + newMapper = combineTypeMappers(newMapper, mapper); } - const newMapper = createTypeMapper(typeParameters, typeArguments); result = target.objectFlags & ObjectFlags.Reference ? createDeferredTypeReference((type as DeferredTypeReference).target, (type as DeferredTypeReference).node, newMapper, newAliasSymbol, newAliasTypeArguments) : target.objectFlags & ObjectFlags.Mapped ? instantiateMappedType(target as MappedType, newMapper, newAliasSymbol, newAliasTypeArguments) : instantiateAnonymousType(target, newMapper, newAliasSymbol, newAliasTypeArguments); @@ -20316,9 +20902,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (type.objectFlags & ObjectFlags.InstantiationExpressionType) { (result as InstantiationExpressionType).node = (type as InstantiationExpressionType).node; } - if (type.objectFlags & ObjectFlags.SingleSignatureType) { - (result as SingleSignatureType).outerTypeParameters = (type as SingleSignatureType).outerTypeParameters; - } result.target = type; result.mapper = mapper; result.aliasSymbol = aliasSymbol || type.aliasSymbol; @@ -20371,10 +20954,26 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { error(currentNode, Diagnostics.Type_instantiation_is_excessively_deep_and_possibly_infinite); return errorType; } + const index = findActiveMapper(mapper); + if (index === -1) { + pushActiveMapper(mapper); + } + const key = type.id + getAliasId(aliasSymbol, aliasTypeArguments); + const mapperCache = activeTypeMappersCaches[index !== -1 ? index : activeTypeMappersCount - 1]; + const cached = mapperCache.get(key); + if (cached) { + return cached; + } totalInstantiationCount++; instantiationCount++; instantiationDepth++; const result = instantiateTypeWorker(type, mapper, aliasSymbol, aliasTypeArguments); + if (index === -1) { + popActiveMapper(); + } + else { + mapperCache.set(key, result); + } instantiationDepth--; return result; } @@ -22894,6 +23493,24 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } } + if (sourceFlags & TypeFlags.TemplateLiteral) { + if (arrayIsEqualTo((source as TemplateLiteralType).texts, (target as TemplateLiteralType).texts)) { + const sourceTypes = (source as TemplateLiteralType).types; + const targetTypes = (target as TemplateLiteralType).types; + result = Ternary.True; + for (let i = 0; i < sourceTypes.length; i++) { + if (!(result &= isRelatedTo(sourceTypes[i], targetTypes[i], RecursionFlags.Both, /*reportErrors*/ false))) { + break; + } + } + return result; + } + } + if (sourceFlags & TypeFlags.StringMapping) { + if ((source as StringMappingType).symbol === (target as StringMappingType).symbol) { + return isRelatedTo((source as StringMappingType).type, (target as StringMappingType).type, RecursionFlags.Both, /*reportErrors*/ false); + } + } if (!(sourceFlags & TypeFlags.Object)) { return Ternary.False; } @@ -23589,6 +24206,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function isPropertySymbolTypeRelated(sourceProp: Symbol, targetProp: Symbol, getTypeOfSourceProperty: (sym: Symbol) => Type, reportErrors: boolean, intersectionState: IntersectionState): Ternary { const targetIsOptional = strictNullChecks && !!(getCheckFlags(targetProp) & CheckFlags.Partial); const effectiveTarget = addOptionality(getNonMissingTypeOfSymbol(targetProp), /*isProperty*/ false, targetIsOptional); + // source could resolve to `any` and that's not related to `unknown` target under strict subtype relation + if (effectiveTarget.flags & (relation === strictSubtypeRelation ? TypeFlags.Any : TypeFlags.AnyOrUnknown)) { + return Ternary.True; + } const effectiveSource = getTypeOfSourceProperty(sourceProp); return isRelatedTo(effectiveSource, effectiveTarget, RecursionFlags.Both, reportErrors, /*headMessage*/ undefined, intersectionState); } @@ -24239,11 +24860,13 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { for (let i = 0; i < types.length; i++) { if (include[i]) { const targetType = getTypeOfPropertyOrIndexSignatureOfType(types[i], propertyName); - if (targetType && someType(getDiscriminatingType(), t => !!related(t, targetType))) { - matched = true; - } - else { - include[i] = Ternary.Maybe; + if (targetType) { + if (someType(getDiscriminatingType(), t => !!related(t, targetType))) { + matched = true; + } + else { + include[i] = Ternary.Maybe; + } } } } @@ -24775,11 +25398,21 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // right is a supertype. const superTypeOrUnion = literalTypesWithSameBaseType(primaryTypes) ? getUnionType(primaryTypes) : - reduceLeft(primaryTypes, (s, t) => isTypeSubtypeOf(s, t) ? t : s)!; + getSingleCommonSupertype(primaryTypes); // Add any nullable types that occurred in the candidates back to the result. return primaryTypes === types ? superTypeOrUnion : getNullableType(superTypeOrUnion, getCombinedTypeFlags(types) & TypeFlags.Nullable); } + function getSingleCommonSupertype(types: Type[]) { + // First, find the leftmost type for which no type to the right is a strict supertype, and if that + // type is a strict supertype of all other candidates, return it. Otherwise, return the leftmost type + // for which no type to the right is a (regular) supertype. + const candidate = reduceLeft(types, (s, t) => isTypeStrictSubtypeOf(s, t) ? t : s)!; + return every(types, t => t === candidate || isTypeStrictSubtypeOf(t, candidate)) ? + candidate : + reduceLeft(types, (s, t) => isTypeSubtypeOf(s, t) ? t : s)!; + } + // Return the leftmost type for which no type to the right is a subtype. function getCommonSubtype(types: Type[]) { return reduceLeft(types, (s, t) => isTypeSubtypeOf(t, s) ? t : s)!; @@ -25663,7 +26296,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const result = !!(type.flags & TypeFlags.Instantiable || type.flags & TypeFlags.Object && !isNonGenericTopLevelType(type) && ( objectFlags & ObjectFlags.Reference && ((type as TypeReference).node || some(getTypeArguments(type as TypeReference), couldContainTypeVariables)) || - objectFlags & ObjectFlags.SingleSignatureType && !!length((type as SingleSignatureType).outerTypeParameters) || objectFlags & ObjectFlags.Anonymous && type.symbol && type.symbol.flags & (SymbolFlags.Function | SymbolFlags.Method | SymbolFlags.Class | SymbolFlags.TypeLiteral | SymbolFlags.ObjectLiteral) && type.symbol.declarations || objectFlags & (ObjectFlags.Mapped | ObjectFlags.ReverseMapped | ObjectFlags.ObjectRestType | ObjectFlags.InstantiationExpressionType) ) || @@ -26045,13 +26677,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } - /** - * @returns `true` if `type` has the shape `[T[0]]` where `T` is `typeParameter` - */ - function isTupleOfSelf(typeParameter: TypeParameter, type: Type) { - return isTupleType(type) && getTupleElementType(type, 0) === getIndexedAccessType(typeParameter, getNumberLiteralType(0)) && !getTypeOfPropertyOfType(type, "1" as __String); - } - function inferTypes(inferences: InferenceInfo[], originalSource: Type, originalTarget: Type, priority = InferencePriority.None, contravariant = false) { let bivariant = false; let propagationType: Type; @@ -26180,11 +26805,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { inference.priority = priority; } if (priority === inference.priority) { - // Inferring A to [A[0]] is a zero information inference (it guarantees A becomes its constraint), but oft arises from generic argument list inferences - // By discarding it early, we can allow more fruitful results to be used instead. - if (isTupleOfSelf(inference.typeParameter, candidate)) { - return; - } // We make contravariant inferences only if we are in a pure contravariant position, // i.e. only if we have not descended into a bivariant position. if (contravariant && !bivariant) { @@ -26947,6 +27567,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { inference.inferredType = fallbackType && context.compareTypes(fallbackType, getTypeWithThisArgument(instantiatedConstraint, fallbackType)) ? fallbackType : instantiatedConstraint; } } + clearActiveMapperCaches(); } return inference.inferredType; @@ -30285,8 +30906,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // To avoid that we will give an error to users if they use arguments objects in arrow function so that they // can explicitly bound arguments objects if (symbol === argumentsSymbol) { - if (isInPropertyInitializerOrClassStaticBlock(node)) { - error(node, Diagnostics.arguments_cannot_be_referenced_in_property_initializers); + if (isInPropertyInitializerOrClassStaticBlock(node, /*ignoreArrowFunctions*/ true)) { + error(node, Diagnostics.arguments_cannot_be_referenced_in_property_initializers_or_class_static_initialization_blocks); return; } @@ -32134,6 +32755,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function popContextualType() { contextualTypeCount--; + // Clear out the popped element's referenced objects. + contextualTypeNodes[contextualTypeCount] = undefined!; + contextualTypes[contextualTypeCount] = undefined; + contextualIsCache[contextualTypeCount] = undefined!; } function findContextualNode(node: Node, includeCaches: boolean) { @@ -32153,6 +32778,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function popInferenceContext() { inferenceContextCount--; + inferenceContextNodes[inferenceContextCount] = undefined!; + inferenceContexts[inferenceContextCount] = undefined; } function getInferenceContext(node: Node) { @@ -32163,6 +32790,34 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } + function pushActiveMapper(mapper: TypeMapper) { + activeTypeMappers[activeTypeMappersCount] = mapper; + activeTypeMappersCaches[activeTypeMappersCount] ??= new Map(); + activeTypeMappersCount++; + } + + function popActiveMapper() { + activeTypeMappersCount--; + // Clear out the popped element's referenced objects. + activeTypeMappers[activeTypeMappersCount] = undefined!; + activeTypeMappersCaches[activeTypeMappersCount].clear(); + } + + function findActiveMapper(mapper: TypeMapper) { + for (let i = activeTypeMappersCount - 1; i >= 0; i--) { + if (mapper === activeTypeMappers[i]) { + return i; + } + } + return -1; + } + + function clearActiveMapperCaches() { + for (let i = activeTypeMappersCount - 1; i >= 0; i--) { + activeTypeMappersCaches[i].clear(); + } + } + function getContextualImportAttributeType(node: ImportAttribute) { return getTypeOfPropertyOfContextualType(getGlobalImportAttributesType(/*reportErrors*/ false), getNameFromImportAttribute(node)); } @@ -34335,31 +34990,21 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } - function isInPropertyInitializerOrClassStaticBlock(node: Node): boolean { + function isInPropertyInitializerOrClassStaticBlock(node: Node, ignoreArrowFunctions?: boolean): boolean { return !!findAncestor(node, node => { switch (node.kind) { case SyntaxKind.PropertyDeclaration: + case SyntaxKind.ClassStaticBlockDeclaration: return true; - case SyntaxKind.PropertyAssignment: - case SyntaxKind.MethodDeclaration: - case SyntaxKind.GetAccessor: - case SyntaxKind.SetAccessor: - case SyntaxKind.SpreadAssignment: - case SyntaxKind.ComputedPropertyName: - case SyntaxKind.TemplateSpan: - case SyntaxKind.JsxExpression: - case SyntaxKind.JsxAttribute: - case SyntaxKind.JsxAttributes: - case SyntaxKind.JsxSpreadAttribute: - case SyntaxKind.JsxOpeningElement: - case SyntaxKind.ExpressionWithTypeArguments: - case SyntaxKind.HeritageClause: - return false; + case SyntaxKind.TypeQuery: + case SyntaxKind.JsxClosingElement: // already reported in JsxOpeningElement + return "quit"; case SyntaxKind.ArrowFunction: - case SyntaxKind.ExpressionStatement: - return isBlock(node.parent) && isClassStaticBlockDeclaration(node.parent.parent) ? true : "quit"; + return ignoreArrowFunctions ? false : "quit"; + case SyntaxKind.Block: + return isFunctionLikeDeclaration(node.parent) && node.parent.kind !== SyntaxKind.ArrowFunction ? "quit" : false; default: - return isExpressionNode(node) ? false : "quit"; + return false; } }); } @@ -35124,8 +35769,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // from the return type. We need a separate inference pass here because (a) instantiation of // the source type uses the outer context's return mapper (which excludes inferences made from // outer arguments), and (b) we don't want any further inferences going into this context. + // We use `createOuterReturnMapper` to ensure that all occurrences of outer type parameters are + // replaced with inferences produced from the outer return type or preceding outer arguments. + // This protects against circular inferences, i.e. avoiding situations where inferences reference + // type parameters for which the inferences are being made. const returnContext = createInferenceContext(signature.typeParameters!, signature, context.flags); - const returnSourceType = instantiateType(contextualType, outerContext && outerContext.returnMapper); + const returnSourceType = instantiateType(contextualType, outerContext && createOuterReturnMapper(outerContext)); inferTypes(returnContext.inferences, returnSourceType, inferenceTargetType); context.returnMapper = some(returnContext.inferences, hasInferenceCandidates) ? getMapperFromContext(cloneInferredPartOfContext(returnContext)) : undefined; } @@ -35400,7 +36049,6 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { checkMode: CheckMode, reportErrors: boolean, containingMessageChain: (() => DiagnosticMessageChain | undefined) | undefined, - inferenceContext: InferenceContext | undefined, ): readonly Diagnostic[] | undefined { const errorOutputContainer: ErrorOutputContainer = { errors: undefined, skipLogging: true }; if (isJsxCallLike(node)) { @@ -35435,10 +36083,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // If one or more arguments are still excluded (as indicated by CheckMode.SkipContextSensitive), // we obtain the regular type of any object literal arguments because we may not have inferred complete // parameter types yet and therefore excess property checks may yield false positives (see #17041). - const regularArgType = checkMode & CheckMode.SkipContextSensitive ? getRegularTypeOfObjectLiteral(argType) : argType; - // If this was inferred under a given inference context, we may need to instantiate the expression type to finish resolving - // the type variables in the expression. - const checkArgType = inferenceContext ? instantiateType(regularArgType, inferenceContext.nonFixingMapper) : regularArgType; + const checkArgType = checkMode & CheckMode.SkipContextSensitive ? getRegularTypeOfObjectLiteral(argType) : argType; const effectiveCheckArgumentNode = getEffectiveCheckNode(arg); if (!checkTypeRelatedToAndOptionallyElaborate(checkArgType, paramType, relation, reportErrors ? effectiveCheckArgumentNode : undefined, effectiveCheckArgumentNode, headMessage, containingMessageChain, errorOutputContainer)) { Debug.assert(!reportErrors || !!errorOutputContainer.errors, "parameter should have errors when reporting errors"); @@ -35836,7 +36481,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // reorderCandidates fills up the candidates array directly reorderCandidates(signatures, candidates, callChainFlags); if (!isJsxOpenFragment) { - Debug.assert(candidates.length, "Revert #54442 and add a testcase with whatever triggered this"); + if (!candidates.length) { + if (reportErrors) { + diagnostics.add(getDiagnosticForCallNode(node, Diagnostics.Call_target_does_not_contain_any_signatures)); + } + return resolveErrorCall(node); + } } const args = getEffectiveCallArguments(node); @@ -35931,7 +36581,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (headMessage) { chain = chainDiagnosticMessages(chain, headMessage); } - const diags = getSignatureApplicabilityError(node, args, last, assignableRelation, CheckMode.Normal, /*reportErrors*/ true, () => chain, /*inferenceContext*/ undefined); + const diags = getSignatureApplicabilityError(node, args, last, assignableRelation, CheckMode.Normal, /*reportErrors*/ true, () => chain); if (diags) { for (const d of diags) { if (last.declaration && candidatesForArgumentError.length > 3) { @@ -35953,7 +36603,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { let i = 0; for (const c of candidatesForArgumentError) { const chain = () => chainDiagnosticMessages(/*details*/ undefined, Diagnostics.Overload_0_of_1_2_gave_the_following_error, i + 1, candidates.length, signatureToString(c)); - const diags = getSignatureApplicabilityError(node, args, c, assignableRelation, CheckMode.Normal, /*reportErrors*/ true, chain, /*inferenceContext*/ undefined); + const diags = getSignatureApplicabilityError(node, args, c, assignableRelation, CheckMode.Normal, /*reportErrors*/ true, chain); if (diags) { if (diags.length <= min) { min = diags.length; @@ -36042,7 +36692,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (some(typeArguments) || !hasCorrectArity(node, args, candidate, signatureHelpTrailingComma)) { return undefined; } - if (getSignatureApplicabilityError(node, args, candidate, relation, CheckMode.Normal, /*reportErrors*/ false, /*containingMessageChain*/ undefined, /*inferenceContext*/ undefined)) { + if (getSignatureApplicabilityError(node, args, candidate, relation, CheckMode.Normal, /*reportErrors*/ false, /*containingMessageChain*/ undefined)) { candidatesForArgumentError = [candidate]; return undefined; } @@ -36050,7 +36700,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } for (let candidateIndex = 0; candidateIndex < candidates.length; candidateIndex++) { - let candidate = candidates[candidateIndex]; + const candidate = candidates[candidateIndex]; if (!hasCorrectTypeArgumentArity(candidate, typeArguments) || !hasCorrectArity(node, args, candidate, signatureHelpTrailingComma)) { continue; } @@ -36059,14 +36709,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { let inferenceContext: InferenceContext | undefined; if (candidate.typeParameters) { - // If we are *inside the body of candidate*, we need to create a clone of `candidate` with differing type parameter identities, - // so our inference results for this call doesn't pollute expression types referencing the outer type parameter! - const paramLocation = candidate.typeParameters[0].symbol.declarations?.[0]?.parent; - const candidateParameterContext = paramLocation || (candidate.declaration && isConstructorDeclaration(candidate.declaration) ? candidate.declaration.parent : candidate.declaration); - if (candidateParameterContext && findAncestor(node, a => a === candidateParameterContext)) { - candidate = getImplementationSignature(candidate); - } - let typeArgumentTypes: readonly Type[] | undefined; + let typeArgumentTypes: Type[] | undefined; if (some(typeArguments)) { typeArgumentTypes = checkTypeArguments(candidate, typeArguments, /*reportErrors*/ false); if (!typeArgumentTypes) { @@ -36075,10 +36718,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } else { - inferenceContext = createInferenceContext(candidate.typeParameters!, candidate, /*flags*/ isInJSFile(node) ? InferenceFlags.AnyDefault : InferenceFlags.None); - // The resulting type arguments are instantiated with the inference context mapper, as the inferred types may still contain references to the inference context's - // type variables via contextual projection. These are kept generic until all inferences are locked in, so the dependencies expressed can pass constraint checks. - typeArgumentTypes = instantiateTypes(inferTypeArguments(node, candidate, args, argCheckMode | CheckMode.SkipGenericFunctions, inferenceContext), inferenceContext.nonFixingMapper); + inferenceContext = createInferenceContext(candidate.typeParameters, candidate, /*flags*/ isInJSFile(node) ? InferenceFlags.AnyDefault : InferenceFlags.None); + typeArgumentTypes = inferTypeArguments(node, candidate, args, argCheckMode | CheckMode.SkipGenericFunctions, inferenceContext); argCheckMode |= inferenceContext.flags & InferenceFlags.SkippedGenericFunction ? CheckMode.SkipGenericFunctions : CheckMode.Normal; } checkCandidate = getSignatureInstantiation(candidate, typeArgumentTypes, isInJSFile(candidate.declaration), inferenceContext && inferenceContext.inferredTypeParameters); @@ -36092,7 +36733,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { else { checkCandidate = candidate; } - if (getSignatureApplicabilityError(node, args, checkCandidate, relation, argCheckMode, /*reportErrors*/ false, /*containingMessageChain*/ undefined, inferenceContext)) { + if (getSignatureApplicabilityError(node, args, checkCandidate, relation, argCheckMode, /*reportErrors*/ false, /*containingMessageChain*/ undefined)) { // Give preference to error candidates that have no rest parameters (as they are more specific) (candidatesForArgumentError || (candidatesForArgumentError = [])).push(checkCandidate); continue; @@ -36103,7 +36744,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // round of type inference and applicability checking for this particular candidate. argCheckMode = CheckMode.Normal; if (inferenceContext) { - const typeArgumentTypes = instantiateTypes(inferTypeArguments(node, candidate, args, argCheckMode, inferenceContext), inferenceContext.mapper); + const typeArgumentTypes = inferTypeArguments(node, candidate, args, argCheckMode, inferenceContext); checkCandidate = getSignatureInstantiation(candidate, typeArgumentTypes, isInJSFile(candidate.declaration), inferenceContext.inferredTypeParameters); // If the original signature has a generic rest type, instantiation may produce a // signature with different arity and we need to perform another arity check. @@ -36112,7 +36753,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { continue; } } - if (getSignatureApplicabilityError(node, args, checkCandidate, relation, argCheckMode, /*reportErrors*/ false, /*containingMessageChain*/ undefined, inferenceContext)) { + if (getSignatureApplicabilityError(node, args, checkCandidate, relation, argCheckMode, /*reportErrors*/ false, /*containingMessageChain*/ undefined)) { // Give preference to error candidates that have no rest parameters (as they are more specific) (candidatesForArgumentError || (candidatesForArgumentError = [])).push(checkCandidate); continue; @@ -37527,6 +38168,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } if (node.keywordToken === SyntaxKind.ImportKeyword) { + if (node.name.escapedText === "defer") { + Debug.assert(!isCallExpression(node.parent) || node.parent.expression !== node, "Trying to get the type of `import.defer` in `import.defer(...)`"); + return errorType; + } return checkImportMetaProperty(node); } @@ -37568,7 +38213,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } else if (moduleKind < ModuleKind.ES2020 && moduleKind !== ModuleKind.System) { - error(node, Diagnostics.The_import_meta_meta_property_is_only_allowed_when_the_module_option_is_es2020_es2022_esnext_system_node16_node18_or_nodenext); + error(node, Diagnostics.The_import_meta_meta_property_is_only_allowed_when_the_module_option_is_es2020_es2022_esnext_system_node16_node18_node20_or_nodenext); } const file = getSourceFileOfNode(node); Debug.assert(!!(file.flags & NodeFlags.PossiblyContainsImportMeta), "Containing file is missing import meta node flag."); @@ -38579,6 +39224,9 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function getYieldedTypeOfYieldExpression(node: YieldExpression, expressionType: Type, sentType: Type, isAsync: boolean): Type | undefined { + if (expressionType === silentNeverType) { + return silentNeverType; + } const errorNode = node.expression || node; // A `yield*` expression effectively yields everything that its operand yields const yieldedType = node.asteriskToken ? checkIteratedTypeOrElementType(isAsync ? IterationUse.AsyncYieldStar : IterationUse.YieldStar, expressionType, sentType, errorNode) : expressionType; @@ -39150,6 +39798,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { switch (moduleKind) { case ModuleKind.Node16: case ModuleKind.Node18: + case ModuleKind.Node20: case ModuleKind.NodeNext: if (sourceFile.impliedNodeFormat === ModuleKind.CommonJS) { span ??= getSpanOfTokenAtPosition(sourceFile, node.pos); @@ -39170,8 +39819,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // fallthrough default: span ??= getSpanOfTokenAtPosition(sourceFile, node.pos); - const message = isAwaitExpression(node) ? Diagnostics.Top_level_await_expressions_are_only_allowed_when_the_module_option_is_set_to_es2022_esnext_system_node16_node18_nodenext_or_preserve_and_the_target_option_is_set_to_es2017_or_higher : - Diagnostics.Top_level_await_using_statements_are_only_allowed_when_the_module_option_is_set_to_es2022_esnext_system_node16_node18_nodenext_or_preserve_and_the_target_option_is_set_to_es2017_or_higher; + const message = isAwaitExpression(node) ? Diagnostics.Top_level_await_expressions_are_only_allowed_when_the_module_option_is_set_to_es2022_esnext_system_node16_node18_node20_nodenext_or_preserve_and_the_target_option_is_set_to_es2017_or_higher : + Diagnostics.Top_level_await_using_statements_are_only_allowed_when_the_module_option_is_set_to_es2022_esnext_system_node16_node18_node20_nodenext_or_preserve_and_the_target_option_is_set_to_es2017_or_higher; diagnostics.add(createFileDiagnostic(sourceFile, span.start, span.length, message)); hasError = true; break; @@ -39846,18 +40495,29 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function checkNullishCoalesceOperands(node: BinaryExpression) { - const { left, operatorToken, right } = node; - if (operatorToken.kind === SyntaxKind.QuestionQuestionToken) { - if (isBinaryExpression(left) && (left.operatorToken.kind === SyntaxKind.BarBarToken || left.operatorToken.kind === SyntaxKind.AmpersandAmpersandToken)) { - grammarErrorOnNode(left, Diagnostics._0_and_1_operations_cannot_be_mixed_without_parentheses, tokenToString(left.operatorToken.kind), tokenToString(operatorToken.kind)); + if (node.operatorToken.kind !== SyntaxKind.QuestionQuestionToken) { + return; + } + if (isBinaryExpression(node.parent)) { + const { left, operatorToken } = node.parent; + if (isBinaryExpression(left) && operatorToken.kind === SyntaxKind.BarBarToken) { + grammarErrorOnNode(left, Diagnostics._0_and_1_operations_cannot_be_mixed_without_parentheses, tokenToString(SyntaxKind.QuestionQuestionToken), tokenToString(operatorToken.kind)); } - if (isBinaryExpression(right) && (right.operatorToken.kind === SyntaxKind.BarBarToken || right.operatorToken.kind === SyntaxKind.AmpersandAmpersandToken)) { - grammarErrorOnNode(right, Diagnostics._0_and_1_operations_cannot_be_mixed_without_parentheses, tokenToString(right.operatorToken.kind), tokenToString(operatorToken.kind)); + } + else if (isBinaryExpression(node.left)) { + const { operatorToken } = node.left; + if (operatorToken.kind === SyntaxKind.BarBarToken || operatorToken.kind === SyntaxKind.AmpersandAmpersandToken) { + grammarErrorOnNode(node.left, Diagnostics._0_and_1_operations_cannot_be_mixed_without_parentheses, tokenToString(operatorToken.kind), tokenToString(SyntaxKind.QuestionQuestionToken)); + } + } + else if (isBinaryExpression(node.right)) { + const { operatorToken } = node.right; + if (operatorToken.kind === SyntaxKind.AmpersandAmpersandToken) { + grammarErrorOnNode(node.right, Diagnostics._0_and_1_operations_cannot_be_mixed_without_parentheses, tokenToString(SyntaxKind.QuestionQuestionToken), tokenToString(operatorToken.kind)); } - - checkNullishCoalesceOperandLeft(node); - checkNullishCoalesceOperandRight(node); } + checkNullishCoalesceOperandLeft(node); + checkNullishCoalesceOperandRight(node); } function checkNullishCoalesceOperandLeft(node: BinaryExpression) { @@ -40819,10 +41479,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } } - // TODO: The signature may reference any outer inference contexts, but we map pop off and then apply new inference contexts, and thus get different inferred types. - // That this is cached on the *first* such attempt is not currently an issue, since expression types *also* get cached on the first pass. If we ever properly speculate, though, - // the cached "isolatedSignatureType" signature field absolutely needs to be included in the list of speculative caches. - return getOrCreateTypeFromSignature(instantiateSignatureInContextOf(signature, contextualSignature, context), flatMap(inferenceContexts, c => c && map(c.inferences, i => i.typeParameter)).slice()); + return getOrCreateTypeFromSignature(instantiateSignatureInContextOf(signature, contextualSignature, context)); } } } @@ -40965,7 +41622,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } // Optimize for the common case of a call to a function with a single non-generic call // signature where we can just fetch the return type without checking the arguments. - if (isCallExpression(expr) && expr.expression.kind !== SyntaxKind.SuperKeyword && !isRequireCall(expr, /*requireStringLiteralLikeArgument*/ true) && !isSymbolOrSymbolForCall(expr)) { + if (isCallExpression(expr) && expr.expression.kind !== SyntaxKind.SuperKeyword && !isRequireCall(expr, /*requireStringLiteralLikeArgument*/ true) && !isSymbolOrSymbolForCall(expr) && !isImportCall(expr)) { return isCallChain(expr) ? getReturnTypeOfSingleNonGenericSignatureOfCallChain(expr) : getReturnTypeOfSingleNonGenericCallSignature(checkNonNullExpression(expr.expression)); } @@ -41044,7 +41701,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { ) { Debug.assert(!!(type.symbol.flags & SymbolFlags.ConstEnum)); const constEnumDeclaration = type.symbol.valueDeclaration as EnumDeclaration; - const redirect = host.getRedirectReferenceForResolutionFromSourceOfProject(getSourceFileOfNode(constEnumDeclaration).resolvedPath); + const redirect = host.getRedirectFromOutput(getSourceFileOfNode(constEnumDeclaration).resolvedPath)?.resolvedRef; if (constEnumDeclaration.flags & NodeFlags.Ambient && !isValidTypeOnlyAliasUseSite(node) && (!redirect || !shouldPreserveConstEnums(redirect.commandLine.options))) { error(node, Diagnostics.Cannot_access_ambient_const_enums_when_0_is_enabled, isolatedModulesLikeFlagName); } @@ -41119,8 +41776,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { case SyntaxKind.ElementAccessExpression: return checkIndexedAccess(node as ElementAccessExpression, checkMode); case SyntaxKind.CallExpression: - if ((node as CallExpression).expression.kind === SyntaxKind.ImportKeyword) { - return checkImportCallExpression(node as ImportCall); + if (isImportCall(node)) { + return checkImportCallExpression(node); } // falls through case SyntaxKind.NewExpression: @@ -45080,6 +45737,9 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { * the `[Symbol.asyncIterator]()` method first, and then the `[Symbol.iterator]()` method. */ function getIterationTypesOfIterable(type: Type, use: IterationUse, errorNode: Node | undefined) { + if (type === silentNeverType) { + return silentNeverIterationTypes; + } if (isTypeAny(type)) { return anyIterationTypes; } @@ -46008,7 +46668,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { languageVersion >= ScriptTarget.ES5 && name.escapedText === "Object" && host.getEmitModuleFormatOfFile(getSourceFileOfNode(name)) < ModuleKind.ES2015 ) { - error(name, Diagnostics.Class_name_cannot_be_Object_when_targeting_ES5_with_module_0, ModuleKind[moduleKind]); // https://github.com/Microsoft/TypeScript/issues/17494 + error(name, Diagnostics.Class_name_cannot_be_Object_when_targeting_ES5_and_above_with_module_0, ModuleKind[moduleKind]); // https://github.com/Microsoft/TypeScript/issues/17494 } } @@ -47055,6 +47715,9 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (isComputedNonLiteralName(member.name)) { error(member.name, Diagnostics.Computed_property_names_are_not_allowed_in_enums); } + else if (isBigIntLiteral(member.name)) { + error(member.name, Diagnostics.An_enum_member_cannot_have_a_numeric_name); + } else { const text = getTextOfPropertyName(member.name); if (isNumericLiteralName(text) && !isInfinityOrNaNString(text)) { @@ -47676,7 +48339,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { !isInJSFile(node) && host.getEmitModuleFormatOfFile(getSourceFileOfNode(node)) === ModuleKind.CommonJS ) { - error(node, Diagnostics.ESM_syntax_is_not_allowed_in_a_CommonJS_module_when_verbatimModuleSyntax_is_enabled); + error(node, getVerbatimModuleSyntaxErrorMessage(node)); } else if ( moduleKind === ModuleKind.Preserve && @@ -47688,7 +48351,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // when we look at the `impliedNodeFormat` of this file and decide it's CommonJS (i.e., currently, // only if the file extension is .cjs/.cts). To avoid that inconsistency, we disallow ESM syntax // in files that are unambiguously CommonJS in this mode. - error(node, Diagnostics.ESM_syntax_is_not_allowed_in_a_CommonJS_module_when_module_is_set_to_preserve); + error(node, Diagnostics.ECMAScript_module_syntax_is_not_allowed_in_a_CommonJS_module_when_module_is_set_to_preserve); } if ( @@ -47698,7 +48361,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { targetFlags & SymbolFlags.ConstEnum ) { const constEnumDeclaration = target.valueDeclaration as EnumDeclaration; - const redirect = host.getRedirectReferenceForResolutionFromSourceOfProject(getSourceFileOfNode(constEnumDeclaration).resolvedPath); + const redirect = host.getRedirectFromOutput(getSourceFileOfNode(constEnumDeclaration).resolvedPath)?.resolvedRef; if (constEnumDeclaration.flags & NodeFlags.Ambient && (!redirect || !shouldPreserveConstEnums(redirect.commandLine.options))) { error(node, Diagnostics.Cannot_access_ambient_const_enums_when_0_is_enabled, isolatedModulesLikeFlagName); } @@ -47778,12 +48441,12 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return grammarErrorOnNode( node, isImportAttributes - ? Diagnostics.Import_attributes_are_only_supported_when_the_module_option_is_set_to_esnext_node18_nodenext_or_preserve - : Diagnostics.Import_assertions_are_only_supported_when_the_module_option_is_set_to_esnext_node18_nodenext_or_preserve, + ? Diagnostics.Import_attributes_are_only_supported_when_the_module_option_is_set_to_esnext_node18_node20_nodenext_or_preserve + : Diagnostics.Import_assertions_are_only_supported_when_the_module_option_is_set_to_esnext_node18_node20_nodenext_or_preserve, ); } - if (moduleKind === ModuleKind.NodeNext && !isImportAttributes) { + if (ModuleKind.Node20 <= moduleKind && moduleKind <= ModuleKind.NodeNext && !isImportAttributes) { return grammarErrorOnFirstToken(node, Diagnostics.Import_assertions_have_been_replaced_by_import_attributes_Use_with_instead_of_assert); } @@ -48120,7 +48783,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } if (isIllegalExportDefaultInCJS) { - error(node, Diagnostics.ESM_syntax_is_not_allowed_in_a_CommonJS_module_when_verbatimModuleSyntax_is_enabled); + error(node, getVerbatimModuleSyntaxErrorMessage(node)); } checkExternalModuleExports(container); @@ -49387,6 +50050,10 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { return isExportAssignment(node.parent) ? Debug.checkDefined(node.parent.symbol) : undefined; case SyntaxKind.ImportKeyword: + if (isMetaProperty(node.parent) && node.parent.name.escapedText === "defer") { + return undefined; + } + // falls through case SyntaxKind.NewKeyword: return isMetaProperty(node.parent) ? checkMetaPropertyKeyword(node.parent).symbol : undefined; case SyntaxKind.InstanceOfKeyword: @@ -50576,6 +51243,9 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } } }, + symbolToDeclarations: (symbol, meaning, flags, maximumLength, verbosityLevel, out) => { + return nodeBuilder.symbolToDeclarations(symbol, meaning, flags, maximumLength, verbosityLevel, out); + }, }; function isImportRequiredByAugmentation(node: ImportDeclaration) { @@ -51824,6 +52494,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { switch (moduleKind) { case ModuleKind.Node16: case ModuleKind.Node18: + case ModuleKind.Node20: case ModuleKind.NodeNext: if (sourceFile.impliedNodeFormat === ModuleKind.CommonJS) { diagnostics.add( @@ -51842,7 +52513,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { // fallthrough default: diagnostics.add( - createDiagnosticForNode(forInOrOfStatement.awaitModifier, Diagnostics.Top_level_for_await_loops_are_only_allowed_when_the_module_option_is_set_to_es2022_esnext_system_node16_node18_nodenext_or_preserve_and_the_target_option_is_set_to_es2017_or_higher), + createDiagnosticForNode(forInOrOfStatement.awaitModifier, Diagnostics.Top_level_for_await_loops_are_only_allowed_when_the_module_option_is_set_to_es2022_esnext_system_node16_node18_node20_nodenext_or_preserve_and_the_target_option_is_set_to_es2017_or_higher), ); break; } @@ -52301,17 +52972,28 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } const blockScopeFlags = declarationList.flags & NodeFlags.BlockScoped; - if ((blockScopeFlags === NodeFlags.Using || blockScopeFlags === NodeFlags.AwaitUsing) && isForInStatement(declarationList.parent)) { - return grammarErrorOnNode( - declarationList, - blockScopeFlags === NodeFlags.Using ? - Diagnostics.The_left_hand_side_of_a_for_in_statement_cannot_be_a_using_declaration : - Diagnostics.The_left_hand_side_of_a_for_in_statement_cannot_be_an_await_using_declaration, - ); - } + if (blockScopeFlags === NodeFlags.Using || blockScopeFlags === NodeFlags.AwaitUsing) { + if (isForInStatement(declarationList.parent)) { + return grammarErrorOnNode( + declarationList, + blockScopeFlags === NodeFlags.Using ? + Diagnostics.The_left_hand_side_of_a_for_in_statement_cannot_be_a_using_declaration : + Diagnostics.The_left_hand_side_of_a_for_in_statement_cannot_be_an_await_using_declaration, + ); + } - if (blockScopeFlags === NodeFlags.AwaitUsing) { - return checkAwaitGrammar(declarationList); + if (declarationList.flags & NodeFlags.Ambient) { + return grammarErrorOnNode( + declarationList, + blockScopeFlags === NodeFlags.Using ? + Diagnostics.using_declarations_are_not_allowed_in_ambient_contexts : + Diagnostics.await_using_declarations_are_not_allowed_in_ambient_contexts, + ); + } + + if (blockScopeFlags === NodeFlags.AwaitUsing) { + return checkAwaitGrammar(declarationList); + } } return false; @@ -52343,7 +53025,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { blockScopeKind === NodeFlags.Using ? "using" : blockScopeKind === NodeFlags.AwaitUsing ? "await using" : Debug.fail("Unknown BlockScope flag"); - return grammarErrorOnNode(node, Diagnostics._0_declarations_can_only_be_declared_inside_a_block, keyword); + error(node, Diagnostics._0_declarations_can_only_be_declared_inside_a_block, keyword); } } } @@ -52358,7 +53040,18 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { break; case SyntaxKind.ImportKeyword: if (escapedText !== "meta") { - return grammarErrorOnNode(node.name, Diagnostics._0_is_not_a_valid_meta_property_for_keyword_1_Did_you_mean_2, unescapeLeadingUnderscores(node.name.escapedText), tokenToString(node.keywordToken), "meta"); + const isCallee = isCallExpression(node.parent) && node.parent.expression === node; + if (escapedText === "defer") { + if (!isCallee) { + return grammarErrorAtPos(node, node.end, 0, Diagnostics._0_expected, "("); + } + } + else { + if (isCallee) { + return grammarErrorOnNode(node.name, Diagnostics._0_is_not_a_valid_meta_property_for_keyword_import_Did_you_mean_meta_or_defer, unescapeLeadingUnderscores(node.name.escapedText)); + } + return grammarErrorOnNode(node.name, Diagnostics._0_is_not_a_valid_meta_property_for_keyword_1_Did_you_mean_2, unescapeLeadingUnderscores(node.name.escapedText), tokenToString(node.keywordToken), "meta"); + } } break; } @@ -52399,7 +53092,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function grammarErrorOnNode(node: Node, message: DiagnosticMessage, ...args: DiagnosticArguments): boolean { const sourceFile = getSourceFileOfNode(node); if (!hasParseDiagnostics(sourceFile)) { - diagnostics.add(createDiagnosticForNode(node, message, ...args)); + error(node, message, ...args); return true; } return false; @@ -52435,7 +53128,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (languageVersion < ScriptTarget.ES2015 && isPrivateIdentifier(node.name)) { return grammarErrorOnNode(node.name, Diagnostics.Private_identifiers_are_only_available_when_targeting_ECMAScript_2015_and_higher); } - if (languageVersion < ScriptTarget.ES2015 && isAutoAccessorPropertyDeclaration(node)) { + if (languageVersion < ScriptTarget.ES2015 && isAutoAccessorPropertyDeclaration(node) && !(node.flags & NodeFlags.Ambient)) { return grammarErrorOnNode(node.name, Diagnostics.Properties_with_the_accessor_modifier_are_only_available_when_targeting_ECMAScript_2015_and_higher); } if (isAutoAccessorPropertyDeclaration(node) && checkGrammarForInvalidQuestionMark(node.questionToken, Diagnostics.An_accessor_property_cannot_be_declared_optional)) { @@ -52584,7 +53277,8 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { const literalType = isLiteralTypeNode(node.parent) || isPrefixUnaryExpression(node.parent) && isLiteralTypeNode(node.parent.parent); if (!literalType) { - if (languageVersion < ScriptTarget.ES2020) { + // Don't error on BigInt literals in ambient contexts + if (!(node.flags & NodeFlags.Ambient) && languageVersion < ScriptTarget.ES2020) { if (grammarErrorOnNode(node, Diagnostics.BigInt_literals_are_not_available_when_targeting_lower_than_ES2020)) { return true; } @@ -52617,11 +53311,24 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { } function checkGrammarImportClause(node: ImportClause): boolean { - if (node.isTypeOnly && node.name && node.namedBindings) { - return grammarErrorOnNode(node, Diagnostics.A_type_only_import_can_specify_a_default_import_or_named_bindings_but_not_both); + if (node.phaseModifier === SyntaxKind.TypeKeyword) { + if (node.name && node.namedBindings) { + return grammarErrorOnNode(node, Diagnostics.A_type_only_import_can_specify_a_default_import_or_named_bindings_but_not_both); + } + if (node.namedBindings?.kind === SyntaxKind.NamedImports) { + return checkGrammarNamedImportsOrExports(node.namedBindings); + } } - if (node.isTypeOnly && node.namedBindings?.kind === SyntaxKind.NamedImports) { - return checkGrammarNamedImportsOrExports(node.namedBindings); + else if (node.phaseModifier === SyntaxKind.DeferKeyword) { + if (node.name) { + return grammarErrorOnNode(node, Diagnostics.Default_imports_are_not_allowed_in_a_deferred_import); + } + if (node.namedBindings?.kind === SyntaxKind.NamedImports) { + return grammarErrorOnNode(node, Diagnostics.Named_imports_are_not_allowed_in_a_deferred_import); + } + if (moduleKind !== ModuleKind.ESNext && moduleKind !== ModuleKind.Preserve) { + return grammarErrorOnNode(node, Diagnostics.Deferred_imports_are_only_supported_when_the_module_flag_is_set_to_esnext_or_preserve); + } } return false; } @@ -52641,11 +53348,16 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { function checkGrammarImportCallExpression(node: ImportCall): boolean { if (compilerOptions.verbatimModuleSyntax && moduleKind === ModuleKind.CommonJS) { - return grammarErrorOnNode(node, Diagnostics.ESM_syntax_is_not_allowed_in_a_CommonJS_module_when_verbatimModuleSyntax_is_enabled); + return grammarErrorOnNode(node, getVerbatimModuleSyntaxErrorMessage(node)); } - if (moduleKind === ModuleKind.ES2015) { - return grammarErrorOnNode(node, Diagnostics.Dynamic_imports_are_only_supported_when_the_module_flag_is_set_to_es2020_es2022_esnext_commonjs_amd_system_umd_node16_node18_or_nodenext); + if (node.expression.kind === SyntaxKind.MetaProperty) { + if (moduleKind !== ModuleKind.ESNext && moduleKind !== ModuleKind.Preserve) { + return grammarErrorOnNode(node, Diagnostics.Deferred_imports_are_only_supported_when_the_module_flag_is_set_to_esnext_or_preserve); + } + } + else if (moduleKind === ModuleKind.ES2015) { + return grammarErrorOnNode(node, Diagnostics.Dynamic_imports_are_only_supported_when_the_module_flag_is_set_to_es2020_es2022_esnext_commonjs_amd_system_umd_node16_node18_node20_or_nodenext); } if (node.typeArguments) { @@ -52659,7 +53371,7 @@ export function createTypeChecker(host: TypeCheckerHost): TypeChecker { if (nodeArguments.length > 1) { const importAttributesArgument = nodeArguments[1]; - return grammarErrorOnNode(importAttributesArgument, Diagnostics.Dynamic_imports_only_support_a_second_argument_when_the_module_option_is_set_to_esnext_node16_node18_nodenext_or_preserve); + return grammarErrorOnNode(importAttributesArgument, Diagnostics.Dynamic_imports_only_support_a_second_argument_when_the_module_option_is_set_to_esnext_node16_node18_node20_nodenext_or_preserve); } } @@ -52885,7 +53597,7 @@ function createBasicNodeBuilderModuleSpecifierResolutionHost(host: TypeCheckerHo getPackageJsonInfoCache: () => host.getPackageJsonInfoCache?.(), useCaseSensitiveFileNames: () => host.useCaseSensitiveFileNames(), redirectTargetsMap: host.redirectTargetsMap, - getProjectReferenceRedirect: fileName => host.getProjectReferenceRedirect(fileName), + getRedirectFromSourceFile: fileName => host.getRedirectFromSourceFile(fileName), isSourceOfProjectReferenceRedirect: fileName => host.isSourceOfProjectReferenceRedirect(fileName), fileExists: fileName => host.fileExists(fileName), getFileIncludeReasons: () => host.getFileIncludeReasons(), @@ -52910,6 +53622,10 @@ interface NodeBuilderContext extends SyntacticTypeNodeBuilderContext { flags: NodeBuilderFlags; internalFlags: InternalNodeBuilderFlags; tracker: SymbolTrackerImpl; + /* Maximum depth we're allowed to expand names. */ + readonly maxExpansionDepth: number; + /* Maximum length before we truncate the output. */ + readonly maxTruncationLength: number; // State encounteredError: boolean; @@ -52933,7 +53649,13 @@ interface NodeBuilderContext extends SyntacticTypeNodeBuilderContext { reverseMappedStack: ReverseMappedSymbol[] | undefined; bundled: boolean; mapper: TypeMapper | undefined; + /* How many levels of nested names we have expanded so far. */ + depth: number; suppressReportInferenceFallback: boolean; + typeStack: number[]; + + // Output + out: WriterContextOut; } class SymbolTrackerImpl implements SymbolTracker { diff --git a/src/compiler/commandLineParser.ts b/src/compiler/commandLineParser.ts index 8248a04194666..345eff350521b 100644 --- a/src/compiler/commandLineParser.ts +++ b/src/compiler/commandLineParser.ts @@ -44,7 +44,6 @@ import { filterMutate, find, findIndex, - firstOrUndefinedIterator, flatten, forEach, forEachEntry, @@ -133,9 +132,9 @@ const compileOnSaveCommandLineOption: CommandLineOption = { const jsxOptionMap = new Map(Object.entries({ "preserve": JsxEmit.Preserve, "react-native": JsxEmit.ReactNative, - "react": JsxEmit.React, "react-jsx": JsxEmit.ReactJSX, "react-jsxdev": JsxEmit.ReactJSXDev, + "react": JsxEmit.React, })); /** @internal */ @@ -249,6 +248,8 @@ const libEntries: [string, string][] = [ ["esnext.iterator", "lib.esnext.iterator.d.ts"], ["esnext.promise", "lib.esnext.promise.d.ts"], ["esnext.float16", "lib.esnext.float16.d.ts"], + ["esnext.error", "lib.esnext.error.d.ts"], + ["esnext.sharedmemory", "lib.esnext.sharedmemory.d.ts"], ["decorators", "lib.decorators.d.ts"], ["decorators.legacy", "lib.decorators.legacy.d.ts"], ]; @@ -602,6 +603,7 @@ export const moduleOptionDeclaration: CommandLineOptionOfCustomType = { esnext: ModuleKind.ESNext, node16: ModuleKind.Node16, node18: ModuleKind.Node18, + node20: ModuleKind.Node20, nodenext: ModuleKind.NodeNext, preserve: ModuleKind.Preserve, })), @@ -695,7 +697,7 @@ const commandOptionsWithoutBuild: CommandLineOption[] = [ affectsBuildInfo: true, showInSimplifiedHelpView: true, category: Diagnostics.JavaScript_Support, - description: Diagnostics.Allow_JavaScript_files_to_be_a_part_of_your_program_Use_the_checkJS_option_to_get_errors_from_these_files, + description: Diagnostics.Allow_JavaScript_files_to_be_a_part_of_your_program_Use_the_checkJs_option_to_get_errors_from_these_files, defaultValueDescription: false, }, { @@ -2789,140 +2791,146 @@ function serializeOptionBaseObject( return result; } -/** - * Generate a list of the compiler options whose value is not the default. - * @param options compilerOptions to be evaluated. -/** @internal */ -export function getCompilerOptionsDiffValue(options: CompilerOptions, newLine: string): string { - const compilerOptionsMap = getSerializedCompilerOption(options); - return getOverwrittenDefaultOptions(); - - function makePadding(paddingLength: number): string { - return Array(paddingLength + 1).join(" "); - } - - function getOverwrittenDefaultOptions() { - const result: string[] = []; - const tab = makePadding(2); - commandOptionsWithoutBuild.forEach(cmd => { - if (!compilerOptionsMap.has(cmd.name)) { - return; - } - - const newValue = compilerOptionsMap.get(cmd.name); - const defaultValue = getDefaultValueForOption(cmd); - if (newValue !== defaultValue) { - result.push(`${tab}${cmd.name}: ${newValue}`); - } - else if (hasProperty(defaultInitCompilerOptions, cmd.name)) { - result.push(`${tab}${cmd.name}: ${defaultValue}`); - } - }); - return result.join(newLine) + newLine; - } -} - -/** - * Get the compiler options to be written into the tsconfig.json. - * @param options commandlineOptions to be included in the compileOptions. - */ -function getSerializedCompilerOption(options: CompilerOptions): Map { - const compilerOptions = extend(options, defaultInitCompilerOptions); - return serializeCompilerOptions(compilerOptions); -} /** * Generate tsconfig configuration when running command line "--init" * @param options commandlineOptions to be generated into tsconfig.json - * @param fileNames array of filenames to be generated into tsconfig.json - * * @internal */ -export function generateTSConfig(options: CompilerOptions, fileNames: readonly string[], newLine: string): string { - const compilerOptionsMap = getSerializedCompilerOption(options); - return writeConfigurations(); +export function generateTSConfig(options: CompilerOptions, newLine: string): string { + type PresetValue = string | number | boolean | (string | number | boolean)[]; + + const tab = " "; + const result: string[] = []; + const allSetOptions = Object.keys(options).filter(k => k !== "init" && k !== "help" && k !== "watch"); + + result.push(`{`); + result.push(`${tab}// ${getLocaleSpecificMessage(Diagnostics.Visit_https_Colon_Slash_Slashaka_ms_Slashtsconfig_to_read_more_about_this_file)}`); + result.push(`${tab}"compilerOptions": {`); + + emitHeader(Diagnostics.File_Layout); + emitOption("rootDir", "./src", "optional"); + emitOption("outDir", "./dist", "optional"); + + newline(); + + emitHeader(Diagnostics.Environment_Settings); + emitHeader(Diagnostics.See_also_https_Colon_Slash_Slashaka_ms_Slashtsconfig_Slashmodule); + emitOption("module", ModuleKind.NodeNext); + emitOption("target", ScriptTarget.ESNext); + emitOption("types", []); + if (options.lib) { + emitOption("lib", options.lib); + } + emitHeader(Diagnostics.For_nodejs_Colon); + result.push(`${tab}${tab}// "lib": ["esnext"],`); + result.push(`${tab}${tab}// "types": ["node"],`); + emitHeader(Diagnostics.and_npm_install_D_types_Slashnode); + + newline(); + + emitHeader(Diagnostics.Other_Outputs); + emitOption("sourceMap", /*defaultValue*/ true); + emitOption("declaration", /*defaultValue*/ true); + emitOption("declarationMap", /*defaultValue*/ true); + + newline(); + + emitHeader(Diagnostics.Stricter_Typechecking_Options); + emitOption("noUncheckedIndexedAccess", /*defaultValue*/ true); + emitOption("exactOptionalPropertyTypes", /*defaultValue*/ true); + + newline(); + + emitHeader(Diagnostics.Style_Options); + emitOption("noImplicitReturns", /*defaultValue*/ true, "optional"); + emitOption("noImplicitOverride", /*defaultValue*/ true, "optional"); + emitOption("noUnusedLocals", /*defaultValue*/ true, "optional"); + emitOption("noUnusedParameters", /*defaultValue*/ true, "optional"); + emitOption("noFallthroughCasesInSwitch", /*defaultValue*/ true, "optional"); + emitOption("noPropertyAccessFromIndexSignature", /*defaultValue*/ true, "optional"); + + newline(); + + emitHeader(Diagnostics.Recommended_Options); + emitOption("strict", /*defaultValue*/ true); + emitOption("jsx", JsxEmit.ReactJSX); + emitOption("verbatimModuleSyntax", /*defaultValue*/ true); + emitOption("isolatedModules", /*defaultValue*/ true); + emitOption("noUncheckedSideEffectImports", /*defaultValue*/ true); + emitOption("moduleDetection", ModuleDetectionKind.Force); + emitOption("skipLibCheck", /*defaultValue*/ true); + + // Write any user-provided options we haven't already + if (allSetOptions.length > 0) { + newline(); + while (allSetOptions.length > 0) { + emitOption(allSetOptions[0], options[allSetOptions[0]]); + } + } - function makePadding(paddingLength: number): string { - return Array(paddingLength + 1).join(" "); + function newline() { + result.push(""); } - function isAllowedOptionForOutput({ category, name, isCommandLineOnly }: CommandLineOption): boolean { - // Skip options which do not have a category or have categories which are more niche - const categoriesToSkip = [Diagnostics.Command_line_Options, Diagnostics.Editor_Support, Diagnostics.Compiler_Diagnostics, Diagnostics.Backwards_Compatibility, Diagnostics.Watch_and_Build_Modes, Diagnostics.Output_Formatting]; - return !isCommandLineOnly && category !== undefined && (!categoriesToSkip.includes(category) || compilerOptionsMap.has(name)); + function emitHeader(header: DiagnosticMessage) { + result.push(`${tab}${tab}// ${getLocaleSpecificMessage(header)}`); } - function writeConfigurations() { - // Filter applicable options to place in the file - const categorizedOptions = new Map(); - // Set allowed categories in order - categorizedOptions.set(Diagnostics.Projects, []); - categorizedOptions.set(Diagnostics.Language_and_Environment, []); - categorizedOptions.set(Diagnostics.Modules, []); - categorizedOptions.set(Diagnostics.JavaScript_Support, []); - categorizedOptions.set(Diagnostics.Emit, []); - categorizedOptions.set(Diagnostics.Interop_Constraints, []); - categorizedOptions.set(Diagnostics.Type_Checking, []); - categorizedOptions.set(Diagnostics.Completeness, []); - for (const option of optionDeclarations) { - if (isAllowedOptionForOutput(option)) { - let listForCategory = categorizedOptions.get(option.category!); - if (!listForCategory) categorizedOptions.set(option.category!, listForCategory = []); - listForCategory.push(option); - } + // commented = 'always': Always comment this out, even if it's on commandline + // commented = 'optional': Comment out unless it's on commandline + // commented = 'never': Never comment this out + function emitOption(setting: K, defaultValue: CompilerOptions[K], commented: "always" | "optional" | "never" = "never") { + const existingOptionIndex = allSetOptions.indexOf(setting); + if (existingOptionIndex >= 0) { + allSetOptions.splice(existingOptionIndex, 1); } - // Serialize all options and their descriptions - let marginLength = 0; - let seenKnownKeys = 0; - const entries: { value: string; description?: string; }[] = []; - categorizedOptions.forEach((options, category) => { - if (entries.length !== 0) { - entries.push({ value: "" }); - } - entries.push({ value: `/* ${getLocaleSpecificMessage(category)} */` }); - for (const option of options) { - let optionName; - if (compilerOptionsMap.has(option.name)) { - optionName = `"${option.name}": ${JSON.stringify(compilerOptionsMap.get(option.name))}${(seenKnownKeys += 1) === compilerOptionsMap.size ? "" : ","}`; - } - else { - optionName = `// "${option.name}": ${JSON.stringify(getDefaultValueForOption(option))},`; - } - entries.push({ - value: optionName, - description: `/* ${option.description && getLocaleSpecificMessage(option.description) || option.name} */`, - }); - marginLength = Math.max(optionName.length, marginLength); - } - }); - - // Write the output - const tab = makePadding(2); - const result: string[] = []; - result.push(`{`); - result.push(`${tab}"compilerOptions": {`); - result.push(`${tab}${tab}/* ${getLocaleSpecificMessage(Diagnostics.Visit_https_Colon_Slash_Slashaka_ms_Slashtsconfig_to_read_more_about_this_file)} */`); - result.push(""); - // Print out each row, aligning all the descriptions on the same column. - for (const entry of entries) { - const { value, description = "" } = entry; - result.push(value && `${tab}${tab}${value}${description && (makePadding(marginLength - value.length + 2) + description)}`); + let comment: boolean; + if (commented === "always") { + comment = true; } - if (fileNames.length) { - result.push(`${tab}},`); - result.push(`${tab}"files": [`); - for (let i = 0; i < fileNames.length; i++) { - result.push(`${tab}${tab}${JSON.stringify(fileNames[i])}${i === fileNames.length - 1 ? "" : ","}`); - } - result.push(`${tab}]`); + else if (commented === "never") { + comment = false; + } + else { + comment = !hasProperty(options, setting); + } + + const value = (options[setting] ?? defaultValue) as PresetValue; + if (comment) { + result.push(`${tab}${tab}// "${setting}": ${formatValueOrArray(setting, value)},`); + } + else { + result.push(`${tab}${tab}"${setting}": ${formatValueOrArray(setting, value)},`); + } + } + + function formatValueOrArray(settingName: string, value: PresetValue): string { + const option = optionDeclarations.filter(c => c.name === settingName)[0]; + if (!option) Debug.fail(`No option named ${settingName}?`); + const map = (option.type instanceof Map) ? option.type : undefined; + if (isArray(value)) { + // eslint-disable-next-line local/no-in-operator + const map = ("element" in option && (option.element.type instanceof Map)) ? option.element.type : undefined; + return `[${value.map(v => formatSingleValue(v, map)).join(", ")}]`; } else { - result.push(`${tab}}`); + return formatSingleValue(value, map); } - result.push(`}`); + } - return result.join(newLine) + newLine; + function formatSingleValue(value: PresetValue, map: Map | undefined) { + if (map) { + value = getNameOfCompilerOptionValue(value as string | number, map) ?? Debug.fail(`No matching value of ${value}`); + } + return JSON.stringify(value); } + + result.push(`${tab}}`); + result.push(`}`); + result.push(``); + + return result.join(newLine); } /** @internal */ @@ -4256,25 +4264,3 @@ function getOptionValueWithEmptyStrings(value: any, option: CommandLineOption): }); } } - -function getDefaultValueForOption(option: CommandLineOption): {} { - switch (option.type) { - case "number": - return 1; - case "boolean": - return true; - case "string": - const defaultValue = option.defaultValueDescription; - return option.isFilePath ? `./${defaultValue && typeof defaultValue === "string" ? defaultValue : ""}` : ""; - case "list": - return []; - case "listOrElement": - return getDefaultValueForOption(option.element); - case "object": - return {}; - default: - const value = firstOrUndefinedIterator(option.type.keys()); - if (value !== undefined) return value; - return Debug.fail("Expected 'option.type' to have entries."); - } -} diff --git a/src/compiler/diagnosticMessages.json b/src/compiler/diagnosticMessages.json index be2fe3957b20a..0e60926c93d50 100644 --- a/src/compiler/diagnosticMessages.json +++ b/src/compiler/diagnosticMessages.json @@ -939,7 +939,7 @@ "category": "Error", "code": 1285 }, - "ESM syntax is not allowed in a CommonJS module when 'verbatimModuleSyntax' is enabled.": { + "ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'.": { "category": "Error", "code": 1286 }, @@ -967,7 +967,7 @@ "category": "Error", "code": 1292 }, - "ESM syntax is not allowed in a CommonJS module when 'module' is set to 'preserve'.": { + "ECMAScript module syntax is not allowed in a CommonJS module when 'module' is set to 'preserve'.": { "category": "Error", "code": 1293 }, @@ -975,6 +975,10 @@ "category": "Error", "code": 1294 }, + "ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. Adjust the 'type' field in the nearest 'package.json' to make this file an ECMAScript module, or adjust your 'verbatimModuleSyntax', 'module', and 'moduleResolution' settings in TypeScript.": { + "category": "Error", + "code": 1295 + }, "'with' statements are not allowed in an async function block.": { "category": "Error", "code": 1300 @@ -1031,11 +1035,11 @@ "category": "Error", "code": 1322 }, - "Dynamic imports are only supported when the '--module' flag is set to 'es2020', 'es2022', 'esnext', 'commonjs', 'amd', 'system', 'umd', 'node16', 'node18', or 'nodenext'.": { + "Dynamic imports are only supported when the '--module' flag is set to 'es2020', 'es2022', 'esnext', 'commonjs', 'amd', 'system', 'umd', 'node16', 'node18', 'node20', or 'nodenext'.": { "category": "Error", "code": 1323 }, - "Dynamic imports only support a second argument when the '--module' option is set to 'esnext', 'node16', 'node18', 'nodenext', or 'preserve'.": { + "Dynamic imports only support a second argument when the '--module' option is set to 'esnext', 'node16', 'node18', 'node20', 'nodenext', or 'preserve'.": { "category": "Error", "code": 1324 }, @@ -1103,7 +1107,7 @@ "category": "Error", "code": 1341 }, - "The 'import.meta' meta-property is only allowed when the '--module' option is 'es2020', 'es2022', 'esnext', 'system', 'node16', 'node18', or 'nodenext'.": { + "The 'import.meta' meta-property is only allowed when the '--module' option is 'es2020', 'es2022', 'esnext', 'system', 'node16', 'node18', 'node20', or 'nodenext'.": { "category": "Error", "code": 1343 }, @@ -1223,7 +1227,7 @@ "category": "Message", "code": 1377 }, - "Top-level 'await' expressions are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', 'node18', 'nodenext', or 'preserve', and the 'target' option is set to 'es2017' or higher.": { + "Top-level 'await' expressions are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', 'node18', 'node20', 'nodenext', or 'preserve', and the 'target' option is set to 'es2017' or higher.": { "category": "Error", "code": 1378 }, @@ -1427,7 +1431,7 @@ "category": "Error", "code": 1431 }, - "Top-level 'for await' loops are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', 'node18', 'nodenext', or 'preserve', and the 'target' option is set to 'es2017' or higher.": { + "Top-level 'for await' loops are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', 'node18', 'node20', 'nodenext', or 'preserve', and the 'target' option is set to 'es2017' or higher.": { "category": "Error", "code": 1432 }, @@ -1837,6 +1841,14 @@ "category": "Error", "code": 1544 }, + "'using' declarations are not allowed in ambient contexts.": { + "category": "Error", + "code": 1545 + }, + "'await using' declarations are not allowed in ambient contexts.": { + "category": "Error", + "code": 1546 + }, "The types of '{0}' are incompatible between these types.": { "category": "Error", @@ -2072,6 +2084,10 @@ "category": "Error", "code": 2345 }, + "Call target does not contain any signatures.": { + "category": "Error", + "code": 2346 + }, "Untyped function calls may not accept type arguments.": { "category": "Error", "code": 2347 @@ -3411,7 +3427,7 @@ "category": "Error", "code": 2724 }, - "Class name cannot be 'Object' when targeting ES5 with module {0}.": { + "Class name cannot be 'Object' when targeting ES5 and above with module {0}.": { "category": "Error", "code": 2725 }, @@ -3767,7 +3783,7 @@ "category": "Error", "code": 2814 }, - "'arguments' cannot be referenced in property initializers.": { + "'arguments' cannot be referenced in property initializers or class static initialization blocks.": { "category": "Error", "code": 2815 }, @@ -3791,7 +3807,7 @@ "category": "Error", "code": 2820 }, - "Import assertions are only supported when the '--module' option is set to 'esnext', 'node18', 'nodenext', or 'preserve'.": { + "Import assertions are only supported when the '--module' option is set to 'esnext', 'node18', 'node20', 'nodenext', or 'preserve'.": { "category": "Error", "code": 2821 }, @@ -3799,7 +3815,7 @@ "category": "Error", "code": 2822 }, - "Import attributes are only supported when the '--module' option is set to 'esnext', 'node18', 'nodenext', or 'preserve'.": { + "Import attributes are only supported when the '--module' option is set to 'esnext', 'node18', 'node20', 'nodenext', or 'preserve'.": { "category": "Error", "code": 2823 }, @@ -3879,7 +3895,7 @@ "category": "Error", "code": 2853 }, - "Top-level 'await using' statements are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', 'node18', 'nodenext', or 'preserve', and the 'target' option is set to 'es2017' or higher.": { + "Top-level 'await using' statements are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', 'node18', 'node20', 'nodenext', or 'preserve', and the 'target' option is set to 'es2017' or higher.": { "category": "Error", "code": 2854 }, @@ -5702,6 +5718,42 @@ "category": "Message", "code": 6283 }, + "File Layout": { + "category": "Message", + "code": 6284 + }, + "Environment Settings": { + "category": "Message", + "code": 6285 + }, + "See also https://aka.ms/tsconfig/module": { + "category": "Message", + "code": 6286 + }, + "For nodejs:": { + "category": "Message", + "code": 6287 + }, + "and npm install -D @types/node": { + "category": "Message", + "code": 6290 + }, + "Other Outputs": { + "category": "Message", + "code": 6291 + }, + "Stricter Typechecking Options": { + "category": "Message", + "code": 6292 + }, + "Style Options": { + "category": "Message", + "code": 6293 + }, + "Recommended Options": { + "category": "Message", + "code": 6294 + }, "Enable project compilation": { "category": "Message", @@ -6014,7 +6066,7 @@ "category": "Message", "code": 6506 }, - "Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files.": { + "Allow JavaScript files to be a part of your program. Use the 'checkJs' option to get errors from these files.": { "category": "Message", "code": 6600 }, @@ -8451,5 +8503,21 @@ "String literal import and export names are not supported when the '--module' flag is set to 'es2015' or 'es2020'.": { "category": "Error", "code": 18057 + }, + "Default imports are not allowed in a deferred import.": { + "category": "Error", + "code": 18058 + }, + "Named imports are not allowed in a deferred import.": { + "category": "Error", + "code": 18059 + }, + "Deferred imports are only supported when the '--module' flag is set to 'esnext' or 'preserve'.": { + "category": "Error", + "code": 18060 + }, + "'{0}' is not a valid meta-property for keyword 'import'. Did you mean 'meta' or 'defer'?": { + "category": "Error", + "code": 18061 } } diff --git a/src/compiler/emitter.ts b/src/compiler/emitter.ts index 01a96579861f4..c60fd92787275 100644 --- a/src/compiler/emitter.ts +++ b/src/compiler/emitter.ts @@ -1168,6 +1168,7 @@ export const notImplementedResolver: EmitResolver = { isImportRequiredByAugmentation: notImplemented, isDefinitelyReferenceToGlobalSymbolObject: notImplemented, createLateBoundIndexSignatures: notImplemented, + symbolToDeclarations: notImplemented, }; const enum PipelinePhase { @@ -3685,8 +3686,8 @@ export function createPrinter(printerOptions: PrinterOptions = {}, handlers: Pri } function emitImportClause(node: ImportClause) { - if (node.isTypeOnly) { - emitTokenWithComment(SyntaxKind.TypeKeyword, node.pos, writeKeyword, node); + if (node.phaseModifier !== undefined) { + emitTokenWithComment(node.phaseModifier, node.pos, writeKeyword, node); writeSpace(); } emit(node.name); diff --git a/src/compiler/executeCommandLine.ts b/src/compiler/executeCommandLine.ts index ca166635ac5c1..edeb0eb277c57 100644 --- a/src/compiler/executeCommandLine.ts +++ b/src/compiler/executeCommandLine.ts @@ -48,7 +48,6 @@ import { formatMessage, generateTSConfig, getBuildOrderFromAnyBuildOrder, - getCompilerOptionsDiffValue, getConfigFileParsingDiagnostics, getDiagnosticText, getErrorSummaryText, @@ -574,7 +573,7 @@ function executeCommandLineWorker( } if (commandLine.options.init) { - writeConfigFile(sys, reportDiagnostic, commandLine.options, commandLine.fileNames); + writeConfigFile(sys, reportDiagnostic, commandLine.options); return sys.exit(ExitStatus.Success); } @@ -1277,7 +1276,6 @@ function writeConfigFile( sys: System, reportDiagnostic: DiagnosticReporter, options: CompilerOptions, - fileNames: string[], ) { const currentDirectory = sys.getCurrentDirectory(); const file = normalizePath(combinePaths(currentDirectory, "tsconfig.json")); @@ -1285,9 +1283,8 @@ function writeConfigFile( reportDiagnostic(createCompilerDiagnostic(Diagnostics.A_tsconfig_json_file_is_already_defined_at_Colon_0, file)); } else { - sys.writeFile(file, generateTSConfig(options, fileNames, sys.newLine)); - const output: string[] = [sys.newLine, ...getHeader(sys, "Created a new tsconfig.json with:")]; - output.push(getCompilerOptionsDiffValue(options, sys.newLine) + sys.newLine + sys.newLine); + sys.writeFile(file, generateTSConfig(options, sys.newLine)); + const output: string[] = [sys.newLine, ...getHeader(sys, "Created a new tsconfig.json")]; output.push(`You can learn more at https://aka.ms/tsconfig` + sys.newLine); for (const line of output) { sys.write(line); diff --git a/src/compiler/expressionToTypeNode.ts b/src/compiler/expressionToTypeNode.ts index bb3db3bd0ccc5..0df3a399b8f14 100644 --- a/src/compiler/expressionToTypeNode.ts +++ b/src/compiler/expressionToTypeNode.ts @@ -1113,7 +1113,7 @@ export function createSyntacticTypeNodeBuilder( function ensureParameter(p: ParameterDeclaration, context: SyntacticTypeNodeBuilderContext) { return factory.updateParameterDeclaration( p, - [], + /*modifiers*/ undefined, reuseNode(context, p.dotDotDotToken), resolver.serializeNameOfParameter(context, p), resolver.isOptionalParameter(p) ? factory.createToken(SyntaxKind.QuestionToken) : undefined, diff --git a/src/compiler/factory/nodeFactory.ts b/src/compiler/factory/nodeFactory.ts index 694262eeeb54a..c7286dc33c677 100644 --- a/src/compiler/factory/nodeFactory.ts +++ b/src/compiler/factory/nodeFactory.ts @@ -135,6 +135,7 @@ import { ImportClause, ImportDeclaration, ImportEqualsDeclaration, + ImportPhaseModifierSyntaxKind, ImportSpecifier, ImportTypeAssertionContainer, ImportTypeNode, @@ -4723,14 +4724,18 @@ export function createNodeFactory(flags: NodeFactoryFlags, baseFactory: BaseNode } // @api - function createImportClause(isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause { + function createImportClause(phaseModifier: ImportPhaseModifierSyntaxKind | boolean | undefined, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause { const node = createBaseDeclaration(SyntaxKind.ImportClause); - node.isTypeOnly = isTypeOnly; + if (typeof phaseModifier === "boolean") { + phaseModifier = phaseModifier ? SyntaxKind.TypeKeyword : undefined; + } + node.isTypeOnly = phaseModifier === SyntaxKind.TypeKeyword; + node.phaseModifier = phaseModifier; node.name = name; node.namedBindings = namedBindings; node.transformFlags |= propagateChildFlags(node.name) | propagateChildFlags(node.namedBindings); - if (isTypeOnly) { + if (phaseModifier === SyntaxKind.TypeKeyword) { node.transformFlags |= TransformFlags.ContainsTypeScript; } node.transformFlags &= ~TransformFlags.ContainsPossibleTopLevelAwait; // always parsed in an Await context @@ -4738,11 +4743,14 @@ export function createNodeFactory(flags: NodeFactoryFlags, baseFactory: BaseNode } // @api - function updateImportClause(node: ImportClause, isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined) { - return node.isTypeOnly !== isTypeOnly + function updateImportClause(node: ImportClause, phaseModifier: ImportPhaseModifierSyntaxKind | boolean | undefined, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined) { + if (typeof phaseModifier === "boolean") { + phaseModifier = phaseModifier ? SyntaxKind.TypeKeyword : undefined; + } + return node.phaseModifier !== phaseModifier || node.name !== name || node.namedBindings !== namedBindings - ? update(createImportClause(isTypeOnly, name, namedBindings), node) + ? update(createImportClause(phaseModifier, name, namedBindings), node) : node; } diff --git a/src/compiler/factory/utilities.ts b/src/compiler/factory/utilities.ts index 80df86fd3ceae..d58b118a8e32d 100644 --- a/src/compiler/factory/utilities.ts +++ b/src/compiler/factory/utilities.ts @@ -700,9 +700,10 @@ export function createExternalHelpersImportDeclarationIfNeeded(nodeFactory: Node const impliedModuleKind = getImpliedNodeFormatForEmitWorker(sourceFile, compilerOptions); const helpers = getImportedHelpers(sourceFile); if ( - (moduleKind >= ModuleKind.ES2015 && moduleKind <= ModuleKind.ESNext) || - impliedModuleKind === ModuleKind.ESNext || - impliedModuleKind === undefined && moduleKind === ModuleKind.Preserve + impliedModuleKind !== ModuleKind.CommonJS && + ((moduleKind >= ModuleKind.ES2015 && moduleKind <= ModuleKind.ESNext) || + impliedModuleKind === ModuleKind.ESNext || + impliedModuleKind === undefined && moduleKind === ModuleKind.Preserve) ) { // When we emit as an ES module, generate an `import` declaration that uses named imports for helpers. // If we cannot determine the implied module kind under `module: preserve` we assume ESM. @@ -730,7 +731,7 @@ export function createExternalHelpersImportDeclarationIfNeeded(nodeFactory: Node const externalHelpersImportDeclaration = nodeFactory.createImportDeclaration( /*modifiers*/ undefined, - nodeFactory.createImportClause(/*isTypeOnly*/ false, /*name*/ undefined, namedBindings), + nodeFactory.createImportClause(/*phaseModifier*/ undefined, /*name*/ undefined, namedBindings), nodeFactory.createStringLiteral(externalHelpersModuleNameText), /*attributes*/ undefined, ); diff --git a/src/compiler/moduleSpecifiers.ts b/src/compiler/moduleSpecifiers.ts index eacba122e496c..8860677e6cab1 100644 --- a/src/compiler/moduleSpecifiers.ts +++ b/src/compiler/moduleSpecifiers.ts @@ -719,7 +719,7 @@ export function forEachFileNameOfModule( ): T | undefined { const getCanonicalFileName = hostGetCanonicalFileName(host); const cwd = host.getCurrentDirectory(); - const referenceRedirect = host.isSourceOfProjectReferenceRedirect(importedFileName) ? host.getProjectReferenceRedirect(importedFileName) : undefined; + const referenceRedirect = host.isSourceOfProjectReferenceRedirect(importedFileName) ? host.getRedirectFromSourceFile(importedFileName)?.outputDts : undefined; const importedPath = toPath(importedFileName, cwd, getCanonicalFileName); const redirects = host.redirectTargetsMap.get(importedPath) || emptyArray; const importedFileNames = [...(referenceRedirect ? [referenceRedirect] : emptyArray), importedFileName, ...redirects]; diff --git a/src/compiler/parser.ts b/src/compiler/parser.ts index 8c69cccba1282..191ef80d3211c 100644 --- a/src/compiler/parser.ts +++ b/src/compiler/parser.ts @@ -123,6 +123,7 @@ import { ImportDeclaration, ImportEqualsDeclaration, ImportOrExportSpecifier, + ImportPhaseModifierSyntaxKind, ImportSpecifier, ImportTypeAssertionContainer, ImportTypeNode, @@ -4563,6 +4564,7 @@ namespace Parser { } parseExpected(SyntaxKind.ColonToken); attributes = parseImportAttributes(currentToken as SyntaxKind.WithKeyword | SyntaxKind.AssertKeyword, /*skipKeyword*/ true); + parseOptional(SyntaxKind.CommaToken); if (!parseExpected(SyntaxKind.CloseBraceToken)) { const lastError = lastOrUndefined(parseDiagnostics); if (lastError && lastError.code === Diagnostics._0_expected.code) { @@ -5557,12 +5559,15 @@ namespace Parser { return parseFunctionBlock(SignatureFlags.IgnoreMissingOpenBrace | (isAsync ? SignatureFlags.Await : SignatureFlags.None)); } + const savedYieldContext = inYieldContext(); + setYieldContext(false); const savedTopLevel = topLevel; topLevel = false; const node = isAsync ? doInAwaitContext(() => parseAssignmentExpressionOrHigher(allowReturnTypeInArrowFunction)) : doOutsideOfAwaitContext(() => parseAssignmentExpressionOrHigher(allowReturnTypeInArrowFunction)); topLevel = savedTopLevel; + setYieldContext(savedYieldContext); return node; } @@ -5938,7 +5943,15 @@ namespace Parser { nextToken(); // advance past the 'import' nextToken(); // advance past the dot expression = finishNode(factory.createMetaProperty(SyntaxKind.ImportKeyword, parseIdentifierName()), pos); - sourceFlags |= NodeFlags.PossiblyContainsImportMeta; + + if ((expression as MetaProperty).name.escapedText === "defer") { + if (token() === SyntaxKind.OpenParenToken || token() === SyntaxKind.LessThanToken) { + sourceFlags |= NodeFlags.PossiblyContainsDynamicImport; + } + } + else { + sourceFlags |= NodeFlags.PossiblyContainsImportMeta; + } } else { expression = parseMemberExpressionOrHigher(); @@ -7190,6 +7203,7 @@ namespace Parser { // could be legal, it would add complexity for very little gain. case SyntaxKind.InterfaceKeyword: case SyntaxKind.TypeKeyword: + case SyntaxKind.DeferKeyword: return nextTokenIsIdentifierOnSameLine(); case SyntaxKind.ModuleKeyword: case SyntaxKind.NamespaceKeyword: @@ -7221,7 +7235,7 @@ namespace Parser { case SyntaxKind.ImportKeyword: nextToken(); - return token() === SyntaxKind.StringLiteral || token() === SyntaxKind.AsteriskToken || + return token() === SyntaxKind.DeferKeyword || token() === SyntaxKind.StringLiteral || token() === SyntaxKind.AsteriskToken || token() === SyntaxKind.OpenBraceToken || tokenIsIdentifierOrKeyword(token()); case SyntaxKind.ExportKeyword: let currentToken = nextToken(); @@ -7295,6 +7309,7 @@ namespace Parser { case SyntaxKind.NamespaceKeyword: case SyntaxKind.TypeKeyword: case SyntaxKind.GlobalKeyword: + case SyntaxKind.DeferKeyword: // When these don't start a declaration, they're an identifier in an expression statement return true; @@ -7328,9 +7343,16 @@ namespace Parser { return nextTokenIsBindingIdentifierOrStartOfDestructuringOnSameLine(/*disallowOf*/ true); } + function nextTokenIsEqualsOrSemicolonOrColonToken() { + nextToken(); + return token() === SyntaxKind.EqualsToken || token() === SyntaxKind.SemicolonToken || token() === SyntaxKind.ColonToken; + } + function nextTokenIsBindingIdentifierOrStartOfDestructuringOnSameLine(disallowOf?: boolean) { nextToken(); - if (disallowOf && token() === SyntaxKind.OfKeyword) return false; + if (disallowOf && token() === SyntaxKind.OfKeyword) { + return lookAhead(nextTokenIsEqualsOrSemicolonOrColonToken); + } return (isBindingIdentifier() || token() === SyntaxKind.OpenBraceToken) && !scanner.hasPrecedingLineBreak(); } @@ -8365,21 +8387,28 @@ namespace Parser { identifier = parseIdentifier(); } - let isTypeOnly = false; + let phaseModifier: ImportPhaseModifierSyntaxKind | undefined; if ( identifier?.escapedText === "type" && (token() !== SyntaxKind.FromKeyword || isIdentifier() && lookAhead(nextTokenIsFromKeywordOrEqualsToken)) && (isIdentifier() || tokenAfterImportDefinitelyProducesImportDeclaration()) ) { - isTypeOnly = true; + phaseModifier = SyntaxKind.TypeKeyword; + identifier = isIdentifier() ? parseIdentifier() : undefined; + } + else if ( + identifier?.escapedText === "defer" && + (token() === SyntaxKind.FromKeyword ? !lookAhead(nextTokenIsStringLiteral) : token() !== SyntaxKind.CommaToken && token() !== SyntaxKind.EqualsToken) + ) { + phaseModifier = SyntaxKind.DeferKeyword; identifier = isIdentifier() ? parseIdentifier() : undefined; } - if (identifier && !tokenAfterImportedIdentifierDefinitelyProducesImportDeclaration()) { - return parseImportEqualsDeclaration(pos, hasJSDoc, modifiers, identifier, isTypeOnly); + if (identifier && !tokenAfterImportedIdentifierDefinitelyProducesImportDeclaration() && phaseModifier !== SyntaxKind.DeferKeyword) { + return parseImportEqualsDeclaration(pos, hasJSDoc, modifiers, identifier, phaseModifier === SyntaxKind.TypeKeyword); } - const importClause = tryParseImportClause(identifier, afterImportPos, isTypeOnly); + const importClause = tryParseImportClause(identifier, afterImportPos, phaseModifier, /*skipJsDocLeadingAsterisks*/ undefined); const moduleSpecifier = parseModuleSpecifier(); const attributes = tryParseImportAttributes(); @@ -8388,7 +8417,7 @@ namespace Parser { return withJSDoc(finishNode(node, pos), hasJSDoc); } - function tryParseImportClause(identifier: Identifier | undefined, pos: number, isTypeOnly: boolean, skipJsDocLeadingAsterisks = false) { + function tryParseImportClause(identifier: Identifier | undefined, pos: number, phaseModifier: undefined | ImportPhaseModifierSyntaxKind, skipJsDocLeadingAsterisks = false) { // ImportDeclaration: // import ImportClause from ModuleSpecifier ; // import ModuleSpecifier; @@ -8398,7 +8427,7 @@ namespace Parser { token() === SyntaxKind.AsteriskToken || // import * token() === SyntaxKind.OpenBraceToken // import { ) { - importClause = parseImportClause(identifier, pos, isTypeOnly, skipJsDocLeadingAsterisks); + importClause = parseImportClause(identifier, pos, phaseModifier, skipJsDocLeadingAsterisks); parseExpected(SyntaxKind.FromKeyword); } return importClause; @@ -8464,7 +8493,7 @@ namespace Parser { return finished; } - function parseImportClause(identifier: Identifier | undefined, pos: number, isTypeOnly: boolean, skipJsDocLeadingAsterisks: boolean) { + function parseImportClause(identifier: Identifier | undefined, pos: number, phaseModifier: undefined | ImportPhaseModifierSyntaxKind, skipJsDocLeadingAsterisks: boolean) { // ImportClause: // ImportedDefaultBinding // NameSpaceImport @@ -8480,11 +8509,16 @@ namespace Parser { parseOptional(SyntaxKind.CommaToken) ) { if (skipJsDocLeadingAsterisks) scanner.setSkipJsDocLeadingAsterisks(true); - namedBindings = token() === SyntaxKind.AsteriskToken ? parseNamespaceImport() : parseNamedImportsOrExports(SyntaxKind.NamedImports); + if (token() === SyntaxKind.AsteriskToken) { + namedBindings = parseNamespaceImport(); + } + else { + namedBindings = parseNamedImportsOrExports(SyntaxKind.NamedImports); + } if (skipJsDocLeadingAsterisks) scanner.setSkipJsDocLeadingAsterisks(false); } - return finishNode(factory.createImportClause(isTypeOnly, identifier, namedBindings), pos); + return finishNode(factory.createImportClause(phaseModifier, identifier, namedBindings), pos); } function parseModuleReference() { @@ -9518,7 +9552,7 @@ namespace Parser { identifier = parseIdentifier(); } - const importClause = tryParseImportClause(identifier, afterImportTagPos, /*isTypeOnly*/ true, /*skipJsDocLeadingAsterisks*/ true); + const importClause = tryParseImportClause(identifier, afterImportTagPos, SyntaxKind.TypeKeyword, /*skipJsDocLeadingAsterisks*/ true); const moduleSpecifier = parseModuleSpecifier(); const attributes = tryParseImportAttributes(); diff --git a/src/compiler/program.ts b/src/compiler/program.ts index 48d8d07f1641e..445946dab0c67 100644 --- a/src/compiler/program.ts +++ b/src/compiler/program.ts @@ -272,6 +272,8 @@ import { ResolvedModuleFull, ResolvedModuleWithFailedLookupLocations, ResolvedProjectReference, + ResolvedRefAndOutputDts, + ResolvedRefAndSource, ResolvedTypeReferenceDirectiveWithFailedLookupLocations, resolveLibrary, resolveModuleName, @@ -291,7 +293,6 @@ import { SourceFile, sourceFileAffectingCompilerOptions, sourceFileMayBeEmitted, - SourceOfProjectReferenceRedirect, startsWith, Statement, StringLiteral, @@ -1715,8 +1716,9 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro // A parallel array to projectReferences storing the results of reading in the referenced tsconfig files let resolvedProjectReferences: readonly (ResolvedProjectReference | undefined)[] | undefined; let projectReferenceRedirects: Map | undefined; - let mapFromFileToProjectReferenceRedirects: Map | undefined; - let mapFromToProjectReferenceRedirectSource: Map | undefined; + + let mapSourceFileToResolvedRef: Map | undefined; + let mapOutputFileToResolvedRef: Map | undefined; const useSourceOfProjectReferenceRedirect = !!host.useSourceOfProjectReferenceRedirect?.() && !options.disableSourceOfProjectReferenceRedirect; @@ -1726,7 +1728,7 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro useSourceOfProjectReferenceRedirect, toPath, getResolvedProjectReferences, - getSourceOfProjectReferenceRedirect, + getRedirectFromOutput, forEachResolvedProjectReference, }); const readFile = host.readFile.bind(host) as typeof host.readFile; @@ -1933,12 +1935,11 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro getConfigFileParsingDiagnostics, getProjectReferences, getResolvedProjectReferences, - getProjectReferenceRedirect, - getResolvedProjectReferenceToRedirect, + getRedirectFromSourceFile, getResolvedProjectReferenceByPath, forEachResolvedProjectReference, isSourceOfProjectReferenceRedirect, - getRedirectReferenceForResolutionFromSourceOfProject, + getRedirectFromOutput, getCompilerOptionsForFile, getDefaultResolutionModeForFile, getEmitModuleFormatOfFile, @@ -2106,12 +2107,12 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro } function getRedirectReferenceForResolution(file: SourceFile) { - const redirect = getResolvedProjectReferenceToRedirect(file.originalFileName); - if (redirect || !isDeclarationFileName(file.originalFileName)) return redirect; + const redirect = getRedirectFromSourceFile(file.originalFileName); + if (redirect || !isDeclarationFileName(file.originalFileName)) return redirect?.resolvedRef; // The originalFileName could not be actual source file name if file found was d.ts from referecned project // So in this case try to look up if this is output from referenced project, if it is use the redirected project in that case - const resultFromDts = getRedirectReferenceForResolutionFromSourceOfProject(file.path); + const resultFromDts = getRedirectFromOutput(file.path)?.resolvedRef; if (resultFromDts) return resultFromDts; // If preserveSymlinks is true, module resolution wont jump the symlink @@ -2120,19 +2121,7 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro // file is from node_modules to avoid having to run real path on all file paths if (!host.realpath || !options.preserveSymlinks || !file.originalFileName.includes(nodeModulesPathPart)) return undefined; const realDeclarationPath = toPath(host.realpath(file.originalFileName)); - return realDeclarationPath === file.path ? undefined : getRedirectReferenceForResolutionFromSourceOfProject(realDeclarationPath); - } - - function getRedirectReferenceForResolutionFromSourceOfProject(filePath: Path) { - const source = getSourceOfProjectReferenceRedirect(filePath); - if (isString(source)) return getResolvedProjectReferenceToRedirect(source); - if (!source) return undefined; - // Output of .d.ts file so return resolved ref that matches the out file name - return forEachResolvedProjectReference(resolvedRef => { - const out = resolvedRef.commandLine.options.outFile; - if (!out) return undefined; - return toPath(out) === filePath ? resolvedRef : undefined; - }); + return realDeclarationPath === file.path ? undefined : getRedirectFromOutput(realDeclarationPath)?.resolvedRef; } function compareDefaultLibFiles(a: SourceFile, b: SourceFile) { @@ -2621,8 +2610,7 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro getSourceFileByPath: program.getSourceFileByPath, getSourceFiles: program.getSourceFiles, isSourceFileFromExternalLibrary, - getResolvedProjectReferenceToRedirect, - getProjectReferenceRedirect, + getRedirectFromSourceFile, isSourceOfProjectReferenceRedirect, getSymlinkCache, writeFile: writeFileCallback || writeFile, @@ -3493,9 +3481,9 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro const sourceFile = getSourceFile(fileName); if (fail) { if (!sourceFile) { - const redirect = getProjectReferenceRedirect(fileName); - if (redirect) { - fail(Diagnostics.Output_file_0_has_not_been_built_from_source_file_1, redirect, fileName); + const redirect = getRedirectFromSourceFile(fileName); + if (redirect?.outputDts) { + fail(Diagnostics.Output_file_0_has_not_been_built_from_source_file_1, redirect.outputDts, fileName); } else { fail(Diagnostics.File_0_not_found, fileName); @@ -3586,7 +3574,7 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro function findSourceFileWorker(fileName: string, isDefaultLib: boolean, ignoreNoDefaultLib: boolean, reason: FileIncludeReason, packageId: PackageId | undefined): SourceFile | undefined { const path = toPath(fileName); if (useSourceOfProjectReferenceRedirect) { - let source = getSourceOfProjectReferenceRedirect(path); + let source = getRedirectFromOutput(path); // If preserveSymlinks is true, module resolution wont jump the symlink // but the resolved real path may be the .d.ts from project reference // Note:: Currently we try the real path only if the @@ -3599,12 +3587,10 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro fileName.includes(nodeModulesPathPart) ) { const realPath = toPath(host.realpath(fileName)); - if (realPath !== path) source = getSourceOfProjectReferenceRedirect(realPath); + if (realPath !== path) source = getRedirectFromOutput(realPath); } - if (source) { - const file = isString(source) ? - findSourceFile(source, isDefaultLib, ignoreNoDefaultLib, reason, packageId) : - undefined; + if (source?.source) { + const file = findSourceFile(source.source, isDefaultLib, ignoreNoDefaultLib, reason, packageId); if (file) addFileToFilesByName(file, path, fileName, /*redirectedPath*/ undefined); return file; } @@ -3619,7 +3605,7 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro const checkedName = file.fileName; const isRedirect = toPath(checkedName) !== toPath(fileName); if (isRedirect) { - fileName = getProjectReferenceRedirect(fileName) || fileName; + fileName = getRedirectFromSourceFile(fileName)?.outputDts || fileName; } // Check if it differs only in drive letters its ok to ignore that error: const checkedAbsolutePath = getNormalizedAbsolutePathWithoutRoot(checkedName, currentDirectory); @@ -3657,20 +3643,19 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro let redirectedPath: Path | undefined; if (!useSourceOfProjectReferenceRedirect) { - const redirectProject = getProjectReferenceRedirectProject(fileName); - if (redirectProject) { - if (redirectProject.commandLine.options.outFile) { + const redirectProject = getRedirectFromSourceFile(fileName); + if (redirectProject?.outputDts) { + if (redirectProject.resolvedRef.commandLine.options.outFile) { // Shouldnt create many to 1 mapping file in --out scenario return undefined; } - const redirect = getProjectReferenceOutputName(redirectProject, fileName); - fileName = redirect; + fileName = redirectProject.outputDts; // Once we start redirecting to a file, we can potentially come back to it // via a back-reference from another file in the .d.ts folder. If that happens we'll // end up trying to add it to the program *again* because we were tracking it via its // original (un-redirected) name. So we have to map both the original path and the redirected path // to the source file we're about to find/create - redirectedPath = toPath(redirect); + redirectedPath = toPath(redirectProject.outputDts); } } @@ -3774,45 +3759,11 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro else missingFileNames.set(path, fileName); } - function getProjectReferenceRedirect(fileName: string): string | undefined { - const referencedProject = getProjectReferenceRedirectProject(fileName); - return referencedProject && getProjectReferenceOutputName(referencedProject, fileName); - } - - function getProjectReferenceRedirectProject(fileName: string) { - // Ignore dts or any json files - if (!resolvedProjectReferences || !resolvedProjectReferences.length || isDeclarationFileName(fileName) || fileExtensionIs(fileName, Extension.Json)) { - return undefined; - } - - // If this file is produced by a referenced project, we need to rewrite it to - // look in the output folder of the referenced project rather than the input - return getResolvedProjectReferenceToRedirect(fileName); - } - - function getProjectReferenceOutputName(referencedProject: ResolvedProjectReference, fileName: string) { - const out = referencedProject.commandLine.options.outFile; - return out ? - changeExtension(out, Extension.Dts) : - getOutputDeclarationFileName(fileName, referencedProject.commandLine, !host.useCaseSensitiveFileNames()); - } - /** * Get the referenced project if the file is input file from that reference project */ - function getResolvedProjectReferenceToRedirect(fileName: string) { - if (mapFromFileToProjectReferenceRedirects === undefined) { - mapFromFileToProjectReferenceRedirects = new Map(); - forEachResolvedProjectReference(referencedProject => { - // not input file from the referenced project, ignore - if (toPath(options.configFilePath!) !== referencedProject.sourceFile.path) { - referencedProject.commandLine.fileNames.forEach(f => mapFromFileToProjectReferenceRedirects!.set(toPath(f), referencedProject.sourceFile.path)); - } - }); - } - - const referencedProjectPath = mapFromFileToProjectReferenceRedirects.get(toPath(fileName)); - return referencedProjectPath && getResolvedProjectReferenceByPath(referencedProjectPath); + function getRedirectFromSourceFile(fileName: string) { + return mapSourceFileToResolvedRef?.get(toPath(fileName)); } function forEachResolvedProjectReference( @@ -3821,33 +3772,12 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro return ts_forEachResolvedProjectReference(resolvedProjectReferences, cb); } - function getSourceOfProjectReferenceRedirect(path: Path) { - if (!isDeclarationFileName(path)) return undefined; - if (mapFromToProjectReferenceRedirectSource === undefined) { - mapFromToProjectReferenceRedirectSource = new Map(); - forEachResolvedProjectReference(resolvedRef => { - const out = resolvedRef.commandLine.options.outFile; - if (out) { - // Dont know which source file it means so return true? - const outputDts = changeExtension(out, Extension.Dts); - mapFromToProjectReferenceRedirectSource!.set(toPath(outputDts), true); - } - else { - const getCommonSourceDirectory = memoize(() => getCommonSourceDirectoryOfConfig(resolvedRef.commandLine, !host.useCaseSensitiveFileNames())); - forEach(resolvedRef.commandLine.fileNames, fileName => { - if (!isDeclarationFileName(fileName) && !fileExtensionIs(fileName, Extension.Json)) { - const outputDts = getOutputDeclarationFileName(fileName, resolvedRef.commandLine, !host.useCaseSensitiveFileNames(), getCommonSourceDirectory); - mapFromToProjectReferenceRedirectSource!.set(toPath(outputDts), fileName); - } - }); - } - }); - } - return mapFromToProjectReferenceRedirectSource.get(path); + function getRedirectFromOutput(path: Path) { + return mapOutputFileToResolvedRef?.get(path); } function isSourceOfProjectReferenceRedirect(fileName: string) { - return useSourceOfProjectReferenceRedirect && !!getResolvedProjectReferenceToRedirect(fileName); + return useSourceOfProjectReferenceRedirect && !!getRedirectFromSourceFile(fileName); } function getResolvedProjectReferenceByPath(projectReferencePath: Path): ResolvedProjectReference | undefined { @@ -4034,7 +3964,7 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro const isFromNodeModulesSearch = resolution.isExternalLibraryImport; // If this is js file source of project reference, dont treat it as js file but as d.ts - const isJsFile = !resolutionExtensionIsTSOrJson(resolution.extension) && !getProjectReferenceRedirectProject(resolution.resolvedFileName); + const isJsFile = !resolutionExtensionIsTSOrJson(resolution.extension) && !getRedirectFromSourceFile(resolution.resolvedFileName); const isJsFileFromNodeModules = isFromNodeModulesSearch && isJsFile && (!resolution.originalPath || pathContainsNodeModules(resolution.resolvedFileName)); const resolvedFileName = resolution.resolvedFileName; @@ -4143,9 +4073,36 @@ export function createProgram(_rootNamesOrOptions: readonly string[] | CreatePro const resolvedRef: ResolvedProjectReference = { commandLine, sourceFile }; projectReferenceRedirects.set(sourceFilePath, resolvedRef); + if (options.configFile !== sourceFile) { + mapSourceFileToResolvedRef ??= new Map(); + mapOutputFileToResolvedRef ??= new Map(); + let outDts: string; + if (commandLine.options.outFile) { + outDts = changeExtension(commandLine.options.outFile, Extension.Dts); + mapOutputFileToResolvedRef?.set(toPath(outDts), { resolvedRef }); + } + const getCommonSourceDirectory = memoize(() => getCommonSourceDirectoryOfConfig(resolvedRef.commandLine, !host.useCaseSensitiveFileNames())); + commandLine.fileNames.forEach(fileName => { + if (isDeclarationFileName(fileName)) return; + const path = toPath(fileName); + let outputDts; + if (!fileExtensionIs(fileName, Extension.Json)) { + if (!commandLine.options.outFile) { + outputDts = getOutputDeclarationFileName(fileName, resolvedRef.commandLine, !host.useCaseSensitiveFileNames(), getCommonSourceDirectory); + mapOutputFileToResolvedRef!.set(toPath(outputDts), { resolvedRef, source: fileName }); + } + else { + outputDts = outDts; + } + } + mapSourceFileToResolvedRef!.set(path, { resolvedRef, outputDts }); + }); + } + if (commandLine.projectReferences) { resolvedRef.references = commandLine.projectReferences.map(parseProjectReferenceConfigFile); } + return resolvedRef; } @@ -4894,7 +4851,7 @@ interface HostForUseSourceOfProjectReferenceRedirect { useSourceOfProjectReferenceRedirect: boolean; toPath(fileName: string): Path; getResolvedProjectReferences(): readonly (ResolvedProjectReference | undefined)[] | undefined; - getSourceOfProjectReferenceRedirect(path: Path): SourceOfProjectReferenceRedirect | undefined; + getRedirectFromOutput(path: Path): ResolvedRefAndSource | undefined; forEachResolvedProjectReference(cb: (resolvedProjectReference: ResolvedProjectReference) => T | undefined): T | undefined; } @@ -4981,9 +4938,9 @@ function updateHostForUseSourceOfProjectReferenceRedirect(host: HostForUseSource } function fileExistsIfProjectReferenceDts(file: string) { - const source = host.getSourceOfProjectReferenceRedirect(host.toPath(file)); + const source = host.getRedirectFromOutput(host.toPath(file)); return source !== undefined ? - isString(source) ? originalFileExists.call(host.compilerHost, source) as boolean : true : + isString(source.source) ? originalFileExists.call(host.compilerHost, source.source) as boolean : true : undefined; } @@ -5029,8 +4986,8 @@ function updateHostForUseSourceOfProjectReferenceRedirect(host: HostForUseSource function fileOrDirectoryExistsUsingSource(fileOrDirectory: string, isFile: boolean): boolean { const fileOrDirectoryExistsUsingSource = isFile ? - (file: string) => fileExistsIfProjectReferenceDts(file) : - (dir: string) => directoryExistsIfProjectReferenceDeclDir(dir); + fileExistsIfProjectReferenceDts : + directoryExistsIfProjectReferenceDeclDir; // Check current directory or file const result = fileOrDirectoryExistsUsingSource(fileOrDirectory); if (result !== undefined) return result; diff --git a/src/compiler/resolutionCache.ts b/src/compiler/resolutionCache.ts index 7c69055ec1f66..7bced48353b82 100644 --- a/src/compiler/resolutionCache.ts +++ b/src/compiler/resolutionCache.ts @@ -324,7 +324,7 @@ export function canWatchAtTypes(atTypes: Path): boolean { } function isInDirectoryPath(dirComponents: Readonly, fileOrDirComponents: Readonly) { - if (fileOrDirComponents.length < fileOrDirComponents.length) return false; + if (fileOrDirComponents.length < dirComponents.length) return false; for (let i = 0; i < dirComponents.length; i++) { if (fileOrDirComponents[i] !== dirComponents[i]) return false; } @@ -872,7 +872,7 @@ export function createResolutionCache(resolutionHost: ResolutionCacheHost, rootD // All the resolutions in this file are invalidated if this file wasn't resolved using same redirect const program = resolutionHost.getCurrentProgram(); - const oldRedirect = program && program.getResolvedProjectReferenceToRedirect(containingFile); + const oldRedirect = program && program.getRedirectFromSourceFile(containingFile)?.resolvedRef; const unmatchedRedirects = oldRedirect ? !redirectedReference || redirectedReference.sourceFile.path !== oldRedirect.sourceFile.path : !!redirectedReference; diff --git a/src/compiler/scanner.ts b/src/compiler/scanner.ts index 50e827c17bd24..343df39ad9cbc 100644 --- a/src/compiler/scanner.ts +++ b/src/compiler/scanner.ts @@ -151,6 +151,7 @@ export const textToKeywordObj: MapLike = { debugger: SyntaxKind.DebuggerKeyword, declare: SyntaxKind.DeclareKeyword, default: SyntaxKind.DefaultKeyword, + defer: SyntaxKind.DeferKeyword, delete: SyntaxKind.DeleteKeyword, do: SyntaxKind.DoKeyword, else: SyntaxKind.ElseKeyword, diff --git a/src/compiler/transformer.ts b/src/compiler/transformer.ts index 8c19f33600649..6d9884632482e 100644 --- a/src/compiler/transformer.ts +++ b/src/compiler/transformer.ts @@ -87,6 +87,7 @@ function getModuleTransformer(moduleKind: ModuleKind): TransformerFactory | undefined { - Debug.assert(!node.isTypeOnly); + Debug.assert(node.phaseModifier !== SyntaxKind.TypeKeyword); // Elide the import clause if we elide both its name and its named bindings. const name = shouldEmitAliasDeclaration(node) ? node.name : undefined; const namedBindings = visitNode(node.namedBindings, visitNamedImportBindings, isNamedImportBindings); - return (name || namedBindings) ? factory.updateImportClause(node, /*isTypeOnly*/ false, name, namedBindings) : undefined; + return (name || namedBindings) ? factory.updateImportClause(node, node.phaseModifier, name, namedBindings) : undefined; } /** diff --git a/src/compiler/types.ts b/src/compiler/types.ts index 342c0f2af7146..1cfe3e04ba68d 100644 --- a/src/compiler/types.ts +++ b/src/compiler/types.ts @@ -222,7 +222,8 @@ export const enum SyntaxKind { GlobalKeyword, BigIntKeyword, OverrideKeyword, - OfKeyword, // LastKeyword and LastToken and LastContextualKeyword + OfKeyword, + DeferKeyword, // LastKeyword and LastToken and LastContextualKeyword // Parse tree nodes @@ -462,7 +463,7 @@ export const enum SyntaxKind { FirstReservedWord = BreakKeyword, LastReservedWord = WithKeyword, FirstKeyword = BreakKeyword, - LastKeyword = OfKeyword, + LastKeyword = DeferKeyword, FirstFutureReservedWord = ImplementsKeyword, LastFutureReservedWord = YieldKeyword, FirstTypeNode = TypePredicate, @@ -487,7 +488,7 @@ export const enum SyntaxKind { FirstJSDocTagNode = JSDocTag, LastJSDocTagNode = JSDocImportTag, /** @internal */ FirstContextualKeyword = AbstractKeyword, - /** @internal */ LastContextualKeyword = OfKeyword, + /** @internal */ LastContextualKeyword = LastKeyword, } export type TriviaSyntaxKind = @@ -599,6 +600,7 @@ export type KeywordSyntaxKind = | SyntaxKind.DebuggerKeyword | SyntaxKind.DeclareKeyword | SyntaxKind.DefaultKeyword + | SyntaxKind.DeferKeyword | SyntaxKind.DeleteKeyword | SyntaxKind.DoKeyword | SyntaxKind.ElseKeyword @@ -3099,7 +3101,7 @@ export interface SuperCall extends CallExpression { } export interface ImportCall extends CallExpression { - readonly expression: ImportExpression; + readonly expression: ImportExpression | ImportDeferProperty; } export interface ExpressionWithTypeArguments extends MemberExpression, NodeWithTypeArguments { @@ -3179,6 +3181,11 @@ export interface ImportMetaProperty extends MetaProperty { readonly name: Identifier & { readonly escapedText: __String & "meta"; }; } +export interface ImportDeferProperty extends MetaProperty { + readonly keywordToken: SyntaxKind.ImportKeyword; + readonly name: Identifier & { readonly escapedText: __String & "defer"; }; +} + /// A JSX expression of the form ... export interface JsxElement extends PrimaryExpression { readonly kind: SyntaxKind.JsxElement; @@ -3711,11 +3718,15 @@ export type NamedExportBindings = export interface ImportClause extends NamedDeclaration { readonly kind: SyntaxKind.ImportClause; readonly parent: ImportDeclaration | JSDocImportTag; + /** @deprecated Use `phaseModifier` instead */ readonly isTypeOnly: boolean; + readonly phaseModifier: undefined | ImportPhaseModifierSyntaxKind; readonly name?: Identifier; // Default binding readonly namedBindings?: NamedImportBindings; } +export type ImportPhaseModifierSyntaxKind = SyntaxKind.TypeKeyword | SyntaxKind.DeferKeyword; + /** @deprecated */ export type AssertionKey = ImportAttributeName; @@ -4277,6 +4288,7 @@ export interface SourceFileLike { lineMap?: readonly number[]; /** @internal */ getPositionOfLineAndCharacter?(line: number, character: number, allowEdits?: true): number; + languageVariant?: LanguageVariant; } /** @internal */ @@ -4553,6 +4565,17 @@ export interface ParseConfigHost extends ModuleResolutionHost { */ export type ResolvedConfigFileName = string & { _isResolvedConfigFileName: never; }; +/** @internal */ +export interface ResolvedRefAndOutputDts { + resolvedRef: ResolvedProjectReference; + outputDts?: string; // Not set if its a json source file +} +/** @internal */ +export interface ResolvedRefAndSource { + resolvedRef: ResolvedProjectReference; + source?: string; // Not set if options have --outFile +} + export interface WriteFileCallbackData { /** @internal */ sourceMapUrlPos?: number; /** @internal */ buildInfo?: BuildInfo; @@ -4907,15 +4930,14 @@ export interface Program extends ScriptReferenceHost { getProjectReferences(): readonly ProjectReference[] | undefined; getResolvedProjectReferences(): readonly (ResolvedProjectReference | undefined)[] | undefined; - /** @internal */ getProjectReferenceRedirect(fileName: string): string | undefined; /** * @internal * Get the referenced project if the file is input file from that reference project */ - getResolvedProjectReferenceToRedirect(fileName: string): ResolvedProjectReference | undefined; + getRedirectFromSourceFile(fileName: string): ResolvedRefAndOutputDts | undefined; /** @internal */ forEachResolvedProjectReference(cb: (resolvedProjectReference: ResolvedProjectReference) => T | undefined): T | undefined; /** @internal */ getResolvedProjectReferenceByPath(projectReferencePath: Path): ResolvedProjectReference | undefined; - /** @internal */ getRedirectReferenceForResolutionFromSourceOfProject(filePath: Path): ResolvedProjectReference | undefined; + /** @internal */ getRedirectFromOutput(filePath: Path): ResolvedRefAndSource | undefined; /** @internal */ isSourceOfProjectReferenceRedirect(fileName: string): boolean; /** @internal */ getCompilerOptionsForFile(file: SourceFile): CompilerOptions; /** @internal */ getBuildInfo?(): BuildInfo; @@ -5031,10 +5053,10 @@ export interface TypeCheckerHost extends ModuleSpecifierResolutionHost, SourceFi getSourceFiles(): readonly SourceFile[]; getSourceFile(fileName: string): SourceFile | undefined; - getProjectReferenceRedirect(fileName: string): string | undefined; + getRedirectFromSourceFile(fileName: string): ResolvedRefAndOutputDts | undefined; isSourceOfProjectReferenceRedirect(fileName: string): boolean; getEmitSyntaxForUsageLocation(file: SourceFile, usage: StringLiteralLike): ResolutionMode; - getRedirectReferenceForResolutionFromSourceOfProject(filePath: Path): ResolvedProjectReference | undefined; + getRedirectFromOutput(filePath: Path): ResolvedRefAndSource | undefined; getModeForUsageLocation(file: SourceFile, usage: StringLiteralLike): ResolutionMode; getDefaultResolutionModeForFile(sourceFile: SourceFile): ResolutionMode; getImpliedNodeFormatForEmit(sourceFile: SourceFile): ResolutionMode; @@ -5046,6 +5068,15 @@ export interface TypeCheckerHost extends ModuleSpecifierResolutionHost, SourceFi typesPackageExists(packageName: string): boolean; packageBundlesTypes(packageName: string): boolean; + + isSourceFileDefaultLibrary(file: SourceFile): boolean; +} + +/** @internal */ +export interface WriterContextOut { + /** Whether increasing the expansion depth will cause us to expand more types. */ + canIncreaseExpansionDepth: boolean; + truncated: boolean; } export interface TypeChecker { @@ -5134,6 +5165,16 @@ export interface TypeChecker { symbolToParameterDeclaration(symbol: Symbol, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): ParameterDeclaration | undefined; /** Note that the resulting nodes cannot be checked. */ typeParameterToDeclaration(parameter: TypeParameter, enclosingDeclaration: Node | undefined, flags: NodeBuilderFlags | undefined): TypeParameterDeclaration | undefined; + /** @internal */ typeParameterToDeclaration( + parameter: TypeParameter, + enclosingDeclaration: Node | undefined, + flags: NodeBuilderFlags | undefined, + internalFlags?: InternalNodeBuilderFlags, + tracker?: SymbolTracker, + maximumLength?: number, + verbosityLevel?: number, + out?: WriterContextOut, // eslint-disable-line @typescript-eslint/unified-signatures + ): TypeParameterDeclaration | undefined; getSymbolsInScope(location: Node, meaning: SymbolFlags): Symbol[]; getSymbolAtLocation(node: Node): Symbol | undefined; @@ -5165,8 +5206,25 @@ export interface TypeChecker { symbolToString(symbol: Symbol, enclosingDeclaration?: Node, meaning?: SymbolFlags, flags?: SymbolFormatFlags): string; typePredicateToString(predicate: TypePredicate, enclosingDeclaration?: Node, flags?: TypeFormatFlags): string; - /** @internal */ writeSignature(signature: Signature, enclosingDeclaration?: Node, flags?: TypeFormatFlags, kind?: SignatureKind, writer?: EmitTextWriter): string; - /** @internal */ writeType(type: Type, enclosingDeclaration?: Node, flags?: TypeFormatFlags, writer?: EmitTextWriter): string; + /** @internal */ writeSignature( + signature: Signature, + enclosingDeclaration?: Node, + flags?: TypeFormatFlags, + kind?: SignatureKind, + writer?: EmitTextWriter, + maximumLength?: number, + verbosityLevel?: number, + out?: WriterContextOut, + ): string; + /** @internal */ writeType( + type: Type, + enclosingDeclaration?: Node, + flags?: TypeFormatFlags, + writer?: EmitTextWriter, + maximumLength?: number, + verbosityLevel?: number, + out?: WriterContextOut, + ): string; /** @internal */ writeSymbol(symbol: Symbol, enclosingDeclaration?: Node, meaning?: SymbolFlags, flags?: SymbolFormatFlags, writer?: EmitTextWriter): string; /** @internal */ writeTypePredicate(predicate: TypePredicate, enclosingDeclaration?: Node, flags?: TypeFormatFlags, writer?: EmitTextWriter): string; @@ -5286,6 +5344,10 @@ export interface TypeChecker { * is `never`. Instead, use `type.flags & TypeFlags.Never`. */ getNeverType(): Type; + /** + * Gets the intrinsic `object` type. + */ + getNonPrimitiveType(): Type; /** @internal */ getOptionalType(): Type; /** @internal */ getUnionType(types: Type[], subtypeReduction?: UnionReduction): Type; /** @internal */ createArrayType(elementType: Type): Type; @@ -5435,6 +5497,7 @@ export interface TypeChecker { /** @internal */ fillMissingTypeArguments(typeArguments: readonly Type[], typeParameters: readonly TypeParameter[] | undefined, minTypeArgumentCount: number, isJavaScriptImplicitAny: boolean): Type[]; getTypeArgumentsForResolvedSignature(signature: Signature): readonly Type[] | undefined; + /** @internal */ isLibType(type: Type): boolean; } /** @internal */ @@ -5881,6 +5944,7 @@ export interface EmitResolver { isImportRequiredByAugmentation(decl: ImportDeclaration): boolean; isDefinitelyReferenceToGlobalSymbolObject(node: Node): boolean; createLateBoundIndexSignatures(cls: ClassLikeDeclaration, enclosingDeclaration: Node, flags: NodeBuilderFlags, internalFlags: InternalNodeBuilderFlags, tracker: SymbolTracker): (IndexSignatureDeclaration | PropertyDeclaration)[] | undefined; + symbolToDeclarations(symbol: Symbol, meaning: SymbolFlags, flags: NodeBuilderFlags, maximumLength?: number, verbosityLevel?: number, out?: WriterContextOut): Declaration[]; } // dprint-ignore @@ -6476,7 +6540,7 @@ export const enum ObjectFlags { CouldContainTypeVariablesComputed = 1 << 19, // CouldContainTypeVariables flag has been computed /** @internal */ CouldContainTypeVariables = 1 << 20, // Type could contain a type variable - + SingleSignatureType = 1 << 27, // A single signature type extracted from a potentially broader type ClassOrInterface = Class | Interface, /** @internal */ RequiresWidening = ContainsWideningType | ContainsObjectOrArrayLiteral, @@ -6492,7 +6556,6 @@ export const enum ObjectFlags { ContainsSpread = 1 << 21, // Object literal contains spread operation ObjectRestType = 1 << 22, // Originates in object rest declaration InstantiationExpressionType = 1 << 23, // Originates in instantiation expression - SingleSignatureType = 1 << 27, // A single signature type extracted from a potentially broader type /** @internal */ IsClassInstanceClone = 1 << 24, // Type is a clone of a class instance type // Flags that require TypeFlags.Object and ObjectFlags.Reference @@ -6707,12 +6770,6 @@ export interface AnonymousType extends ObjectType { instantiations?: Map; // Instantiations of generic type alias (undefined if non-generic) } -/** @internal */ -// A SingleSignatureType may have bespoke outer type parameters to handle free type variable inferences -export interface SingleSignatureType extends AnonymousType { - outerTypeParameters?: TypeParameter[]; -} - /** @internal */ export interface InstantiationExpressionType extends AnonymousType { node: NodeWithTypeArguments; @@ -6998,8 +7055,6 @@ export interface Signature { isolatedSignatureType?: ObjectType; // A manufactured type that just contains the signature for purposes of signature comparison /** @internal */ instantiations?: Map; // Generic signature instantiation cache - /** @internal */ - implementationSignatureCache?: Signature; // Copy of the signature with fresh type parameters to use in checking the body of a potentially self-referential generic function (deferred) } export const enum IndexKind { @@ -7107,6 +7162,7 @@ export interface InferenceContext { mapper: TypeMapper; // Mapper that fixes inferences nonFixingMapper: TypeMapper; // Mapper that doesn't fix inferences returnMapper?: TypeMapper; // Type mapper for inferences from return types (if any) + outerReturnMapper?: TypeMapper; // Type mapper for inferences from return types of outer function (if any) inferredTypeParameters?: readonly TypeParameter[]; // Inferred type parameters for function result intraExpressionInferenceSites?: IntraExpressionInferenceSite[]; } @@ -7543,6 +7599,7 @@ export enum ModuleKind { // Node16+ is an amalgam of commonjs (albeit updated) and es2022+, and represents a distinct module system from es2020/esnext Node16 = 100, Node18 = 101, + Node20 = 102, NodeNext = 199, // Emit as written @@ -8134,11 +8191,6 @@ export interface CompilerHost extends ModuleResolutionHost { jsDocParsingMode?: JSDocParsingMode; } -/** true if --out otherwise source file name * - * @internal - */ -export type SourceOfProjectReferenceRedirect = string | true; - /** @internal */ export const enum TransformFlags { None = 0, @@ -8524,7 +8576,7 @@ export const enum EmitHint { export interface SourceFileMayBeEmittedHost { getCompilerOptions(): CompilerOptions; isSourceFileFromExternalLibrary(file: SourceFile): boolean; - getResolvedProjectReferenceToRedirect(fileName: string): ResolvedProjectReference | undefined; + getRedirectFromSourceFile(fileName: string): ResolvedRefAndOutputDts | undefined; isSourceOfProjectReferenceRedirect(fileName: string): boolean; getCurrentDirectory(): string; getCanonicalFileName: GetCanonicalFileName; @@ -9021,8 +9073,12 @@ export interface NodeFactory { updateImportEqualsDeclaration(node: ImportEqualsDeclaration, modifiers: readonly ModifierLike[] | undefined, isTypeOnly: boolean, name: Identifier, moduleReference: ModuleReference): ImportEqualsDeclaration; createImportDeclaration(modifiers: readonly ModifierLike[] | undefined, importClause: ImportClause | undefined, moduleSpecifier: Expression, attributes?: ImportAttributes): ImportDeclaration; updateImportDeclaration(node: ImportDeclaration, modifiers: readonly ModifierLike[] | undefined, importClause: ImportClause | undefined, moduleSpecifier: Expression, attributes: ImportAttributes | undefined): ImportDeclaration; - createImportClause(isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause; - updateImportClause(node: ImportClause, isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause; + createImportClause(phaseModifier: ImportPhaseModifierSyntaxKind | undefined, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause; + // eslint-disable-next-line @typescript-eslint/unified-signatures -- Cannot unify due to the @deprecated tag + /** @deprecated */ createImportClause(isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause; + updateImportClause(node: ImportClause, phaseModifier: ImportPhaseModifierSyntaxKind | undefined, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause; + // eslint-disable-next-line @typescript-eslint/unified-signatures -- Cannot unify due to the @deprecated tag + /** @deprecated */ updateImportClause(node: ImportClause, isTypeOnly: boolean, name: Identifier | undefined, namedBindings: NamedImportBindings | undefined): ImportClause; /** @deprecated */ createAssertClause(elements: NodeArray, multiLine?: boolean): AssertClause; /** @deprecated */ updateAssertClause(node: AssertClause, elements: NodeArray, multiLine?: boolean): AssertClause; /** @deprecated */ createAssertEntry(name: AssertionKey, value: Expression): AssertEntry; @@ -9924,7 +9980,7 @@ export interface ModuleSpecifierResolutionHost { getNearestAncestorDirectoryWithPackageJson?(fileName: string, rootDir?: string): string | undefined; readonly redirectTargetsMap: RedirectTargetsMap; - getProjectReferenceRedirect(fileName: string): string | undefined; + getRedirectFromSourceFile(fileName: string): ResolvedRefAndOutputDts | undefined; isSourceOfProjectReferenceRedirect(fileName: string): boolean; getFileIncludeReasons(): MultiMap; getCommonSourceDirectory(): string; @@ -10501,6 +10557,12 @@ export interface UserPreferences { readonly displayPartsForJSDoc?: boolean; readonly generateReturnInDocTemplate?: boolean; readonly disableLineTextInReferences?: boolean; + /** + * A positive integer indicating the maximum length of a hover text before it is truncated. + * + * Default: `500` + */ + readonly maximumHoverLength?: number; } export type OrganizeImportsTypeOrder = "last" | "inline" | "first"; diff --git a/src/compiler/utilities.ts b/src/compiler/utilities.ts index 5755369134d8a..4687bb8796fad 100644 --- a/src/compiler/utilities.ts +++ b/src/compiler/utilities.ts @@ -2,6 +2,7 @@ import { __String, AccessExpression, AccessorDeclaration, + addEmitFlags, addRange, affectsDeclarationPathOptionDeclarations, affectsEmitOptionDeclarations, @@ -511,6 +512,8 @@ import { ScriptTarget, semanticDiagnosticsOptionDeclarations, SetAccessorDeclaration, + setOriginalNode, + setTextRange, ShorthandPropertyAssignment, shouldAllowImportingTsExtension, Signature, @@ -592,6 +595,7 @@ import { VariableDeclarationList, VariableLikeDeclaration, VariableStatement, + visitEachChild, WhileStatement, WithStatement, WrappedExpression, @@ -610,6 +614,8 @@ export const externalHelpersModuleNameText = "tslib"; export const defaultMaximumTruncationLength = 160; /** @internal */ export const noTruncationMaximumTruncationLength = 1_000_000; +/** @internal */ +export const defaultHoverMaximumTruncationLength = 500; /** @internal */ export function getDeclarationOfKind(symbol: Symbol, kind: T["kind"]): T | undefined { @@ -1446,6 +1452,9 @@ export const getScriptTargetFeatures: () => ScriptTargetFeatures = /* @__PURE__ es2024: [ "waitAsync", ], + esnext: [ + "pause", + ], })), SharedArrayBuffer: new Map(Object.entries({ es2017: [ @@ -2642,7 +2651,13 @@ export function isSuperCall(n: Node): n is SuperCall { /** @internal */ export function isImportCall(n: Node): n is ImportCall { - return n.kind === SyntaxKind.CallExpression && (n as CallExpression).expression.kind === SyntaxKind.ImportKeyword; + if (n.kind !== SyntaxKind.CallExpression) return false; + const e = (n as CallExpression).expression; + return e.kind === SyntaxKind.ImportKeyword || ( + isMetaProperty(e) + && e.keywordToken === SyntaxKind.ImportKeyword + && e.name.escapedText === "defer" + ); } /** @internal */ @@ -3593,8 +3608,10 @@ export function isExpressionNode(node: Node): boolean { case SyntaxKind.JsxFragment: case SyntaxKind.YieldExpression: case SyntaxKind.AwaitExpression: - case SyntaxKind.MetaProperty: return true; + case SyntaxKind.MetaProperty: + // `import.defer` in `import.defer(...)` is not an expression + return !isImportCall(node.parent) || node.parent.expression !== node; case SyntaxKind.ExpressionWithTypeArguments: return !isHeritageClause(node.parent) && !isJSDocAugmentsTag(node.parent); case SyntaxKind.QualifiedName: @@ -5658,17 +5675,17 @@ export const enum OperatorPrecedence { // CoalesceExpression Conditional, + // LogicalORExpression: + // LogicalANDExpression + // LogicalORExpression `||` LogicalANDExpression + LogicalOR, + // CoalesceExpression: // CoalesceExpressionHead `??` BitwiseORExpression // CoalesceExpressionHead: // CoalesceExpression // BitwiseORExpression - Coalesce = Conditional, // NOTE: This is wrong - - // LogicalORExpression: - // LogicalANDExpression - // LogicalORExpression `||` LogicalANDExpression - LogicalOR, + Coalesce = LogicalOR, // LogicalANDExpression: // BitwiseORExpression @@ -6585,7 +6602,7 @@ export function sourceFileMayBeEmitted(sourceFile: SourceFile, host: SourceFileM if (host.isSourceOfProjectReferenceRedirect(sourceFile.fileName)) return false; // Any non json file should be emitted if (!isJsonSourceFile(sourceFile)) return true; - if (host.getResolvedProjectReferenceToRedirect(sourceFile.fileName)) return false; + if (host.getRedirectFromSourceFile(sourceFile.fileName)) return false; // Emit json file if outFile is specified if (options.outFile) return true; // Json file is not emitted if outDir is not specified @@ -7698,9 +7715,18 @@ export function base64decode(host: { base64decode?(input: string): string; } | u export function readJsonOrUndefined(path: string, hostOrText: { readFile(fileName: string): string | undefined; } | string): object | undefined { const jsonText = isString(hostOrText) ? hostOrText : hostOrText.readFile(path); if (!jsonText) return undefined; - // gracefully handle if readFile fails or returns not JSON - const result = parseConfigFileTextToJson(path, jsonText); - return !result.error ? result.config : undefined; + // Try strictly parsing first, then fall back to our (slower) + // parser that is resilient to comments/trailing commas. + // package.json files should never have these, but we + // have no way to communicate these issues in the first place. + let result = tryParseJson(jsonText); + if (result === undefined) { + const looseResult = parseConfigFileTextToJson(path, jsonText); + if (!looseResult.error) { + result = looseResult.config; + } + } + return result; } /** @internal */ @@ -8947,6 +8973,7 @@ const _computedOptions = createComputedCompilerOptions({ return target ?? ((compilerOptions.module === ModuleKind.Node16 && ScriptTarget.ES2022) || (compilerOptions.module === ModuleKind.Node18 && ScriptTarget.ES2022) || + (compilerOptions.module === ModuleKind.Node20 && ScriptTarget.ES2023) || (compilerOptions.module === ModuleKind.NodeNext && ScriptTarget.ESNext) || ScriptTarget.ES5); }, @@ -8970,6 +8997,7 @@ const _computedOptions = createComputedCompilerOptions({ break; case ModuleKind.Node16: case ModuleKind.Node18: + case ModuleKind.Node20: moduleResolution = ModuleResolutionKind.Node16; break; case ModuleKind.NodeNext: @@ -9013,6 +9041,7 @@ const _computedOptions = createComputedCompilerOptions({ switch (_computedOptions.module.computeValue(compilerOptions)) { case ModuleKind.Node16: case ModuleKind.Node18: + case ModuleKind.Node20: case ModuleKind.NodeNext: case ModuleKind.Preserve: return true; @@ -9057,8 +9086,8 @@ const _computedOptions = createComputedCompilerOptions({ if (!moduleResolutionSupportsPackageJsonExportsAndImports(moduleResolution)) { return false; } - if (compilerOptions.resolvePackageJsonExports !== undefined) { - return compilerOptions.resolvePackageJsonExports; + if (compilerOptions.resolvePackageJsonImports !== undefined) { + return compilerOptions.resolvePackageJsonImports; } switch (moduleResolution) { case ModuleResolutionKind.Node16: @@ -9075,6 +9104,14 @@ const _computedOptions = createComputedCompilerOptions({ if (compilerOptions.resolveJsonModule !== undefined) { return compilerOptions.resolveJsonModule; } + switch (_computedOptions.module.computeValue(compilerOptions)) { + // TODO in 6.0: uncomment + // case ModuleKind.Node16: + // case ModuleKind.Node18: + case ModuleKind.Node20: + case ModuleKind.NodeNext: + return true; + } return _computedOptions.moduleResolution.computeValue(compilerOptions) === ModuleResolutionKind.Bundler; }, }, @@ -9505,7 +9542,7 @@ const wildcardCharCodes = [CharacterCodes.asterisk, CharacterCodes.question]; const commonPackageFolders: readonly string[] = ["node_modules", "bower_components", "jspm_packages"]; -const implicitExcludePathRegexPattern = `(?!(${commonPackageFolders.join("|")})(/|$))`; +const implicitExcludePathRegexPattern = `(?!(?:${commonPackageFolders.join("|")})(?:/|$))`; /** @internal */ export interface WildcardMatcher { @@ -9521,12 +9558,12 @@ const filesMatcher: WildcardMatcher = { * [^./] # matches everything up to the first . character (excluding directory separators) * (\\.(?!min\\.js$))? # matches . characters but not if they are part of the .min.js file extension */ - singleAsteriskRegexFragment: "([^./]|(\\.(?!min\\.js$))?)*", + singleAsteriskRegexFragment: "(?:[^./]|(?:\\.(?!min\\.js$))?)*", /** * Regex for the ** wildcard. Matches any number of subdirectories. When used for including * files or directories, does not match subdirectories that start with a . character */ - doubleAsteriskRegexFragment: `(/${implicitExcludePathRegexPattern}[^/.][^/]*)*?`, + doubleAsteriskRegexFragment: `(?:/${implicitExcludePathRegexPattern}[^/.][^/]*)*?`, replaceWildcardCharacter: match => replaceWildcardCharacter(match, filesMatcher.singleAsteriskRegexFragment), }; @@ -9536,13 +9573,13 @@ const directoriesMatcher: WildcardMatcher = { * Regex for the ** wildcard. Matches any number of subdirectories. When used for including * files or directories, does not match subdirectories that start with a . character */ - doubleAsteriskRegexFragment: `(/${implicitExcludePathRegexPattern}[^/.][^/]*)*?`, + doubleAsteriskRegexFragment: `(?:/${implicitExcludePathRegexPattern}[^/.][^/]*)*?`, replaceWildcardCharacter: match => replaceWildcardCharacter(match, directoriesMatcher.singleAsteriskRegexFragment), }; const excludeMatcher: WildcardMatcher = { singleAsteriskRegexFragment: "[^/]*", - doubleAsteriskRegexFragment: "(/.+?)?", + doubleAsteriskRegexFragment: "(?:/.+?)?", replaceWildcardCharacter: match => replaceWildcardCharacter(match, excludeMatcher.singleAsteriskRegexFragment), }; @@ -9559,10 +9596,10 @@ export function getRegularExpressionForWildcard(specs: readonly string[] | undef return undefined; } - const pattern = patterns.map(pattern => `(${pattern})`).join("|"); + const pattern = patterns.map(pattern => `(?:${pattern})`).join("|"); // If excluding, match "foo/bar/baz...", but if including, only allow "foo". - const terminator = usage === "exclude" ? "($|/)" : "$"; - return `^(${pattern})${terminator}`; + const terminator = usage === "exclude" ? "(?:$|/)" : "$"; + return `^(?:${pattern})${terminator}`; } /** @internal */ @@ -9587,7 +9624,7 @@ export function isImplicitGlob(lastPathComponent: string): boolean { /** @internal */ export function getPatternFromSpec(spec: string, basePath: string, usage: "files" | "directories" | "exclude"): string | undefined { const pattern = spec && getSubPatternFromSpec(spec, basePath, usage, wildcardMatchers[usage]); - return pattern && `^(${pattern})${usage === "exclude" ? "($|/)" : "$"}`; + return pattern && `^(?:${pattern})${usage === "exclude" ? "(?:$|/)" : "$"}`; } /** @internal */ @@ -9620,7 +9657,7 @@ export function getSubPatternFromSpec( } else { if (usage === "directories") { - subpattern += "("; + subpattern += "(?:"; optionalCount++; } @@ -9634,7 +9671,7 @@ export function getSubPatternFromSpec( // appear first in a component. Dotted directories and files can be included explicitly // like so: **/.*/.* if (component.charCodeAt(0) === CharacterCodes.asterisk) { - componentPattern += "([^./]" + singleAsteriskRegexFragment + ")?"; + componentPattern += "(?:[^./]" + singleAsteriskRegexFragment + ")?"; component = component.substr(1); } else if (component.charCodeAt(0) === CharacterCodes.question) { @@ -10933,10 +10970,11 @@ export function isTypeDeclaration(node: Node): node is TypeParameterDeclaration case SyntaxKind.JSDocEnumTag: return true; case SyntaxKind.ImportClause: - return (node as ImportClause).isTypeOnly; + return (node as ImportClause).phaseModifier === SyntaxKind.TypeKeyword; case SyntaxKind.ImportSpecifier: + return (node as ImportSpecifier).parent.parent.phaseModifier === SyntaxKind.TypeKeyword; case SyntaxKind.ExportSpecifier: - return (node as ImportSpecifier | ExportSpecifier).parent.parent.isTypeOnly; + return (node as ExportSpecifier).parent.parent.isTypeOnly; default: return false; } @@ -12108,7 +12146,7 @@ function getNodeAtPosition(sourceFile: SourceFile, position: number, includeJSDo }; while (true) { const child = isJavaScriptFile && includeJSDoc && hasJSDocNodes(current) && forEach(current.jsDoc, getContainingChild) || forEachChild(current, getContainingChild); - if (!child) { + if (!child || isMetaProperty(child)) { return current; } current = child; @@ -12135,12 +12173,12 @@ export function getLibFileNameFromLibReference(libReference: FileReference): str /** @internal */ export function forEachResolvedProjectReference( resolvedProjectReferences: readonly (ResolvedProjectReference | undefined)[] | undefined, - cb: (resolvedProjectReference: ResolvedProjectReference, parent: ResolvedProjectReference | undefined) => T | undefined, + cb: (resolvedProjectReference: ResolvedProjectReference) => T | undefined, ): T | undefined { return forEachProjectReference( /*projectReferences*/ undefined, resolvedProjectReferences, - (resolvedRef, parent) => resolvedRef && cb(resolvedRef, parent), + resolvedRef => resolvedRef && cb(resolvedRef), ); } @@ -12208,3 +12246,121 @@ export function getOptionsSyntaxByValue(optionsObject: ObjectLiteralExpression | export function forEachOptionsSyntaxByName(optionsObject: ObjectLiteralExpression | undefined, name: string, callback: (prop: PropertyAssignment) => T | undefined): T | undefined { return forEachPropertyAssignment(optionsObject, name, callback); } + +/** + * Creates a deep, memberwise clone of a node with no source map location. + * + * WARNING: This is an expensive operation and is only intended to be used in refactorings + * and code fixes (because those are triggered by explicit user actions). + * + * @internal + */ +// Moved here to compiler utilities for usage in node builder for quickinfo. +export function getSynthesizedDeepClone(node: T, includeTrivia = true): T { + const clone = node && getSynthesizedDeepCloneWorker(node); + if (clone && !includeTrivia) suppressLeadingAndTrailingTrivia(clone); + return setParentRecursive(clone, /*incremental*/ false); +} + +/** @internal */ +export function getSynthesizedDeepCloneWithReplacements( + node: T, + includeTrivia: boolean, + replaceNode: (node: Node) => Node | undefined, +): T { + let clone = replaceNode(node); + if (clone) { + setOriginalNode(clone, node); + } + else { + clone = getSynthesizedDeepCloneWorker(node as NonNullable, replaceNode); + } + + if (clone && !includeTrivia) suppressLeadingAndTrailingTrivia(clone); + return clone as T; +} + +function getSynthesizedDeepCloneWorker(node: T, replaceNode?: (node: Node) => Node | undefined): T { + const nodeClone: (n: T) => T = replaceNode + ? n => getSynthesizedDeepCloneWithReplacements(n, /*includeTrivia*/ true, replaceNode) + : getSynthesizedDeepClone; + const nodesClone: (ns: NodeArray | undefined) => NodeArray | undefined = replaceNode + ? ns => ns && getSynthesizedDeepClonesWithReplacements(ns, /*includeTrivia*/ true, replaceNode) + : ns => ns && getSynthesizedDeepClones(ns); + const visited = visitEachChild(node, nodeClone, /*context*/ undefined, nodesClone, nodeClone); + + if (visited === node) { + // This only happens for leaf nodes - internal nodes always see their children change. + const clone = isStringLiteral(node) ? setOriginalNode(factory.createStringLiteralFromNode(node), node) as Node as T : + isNumericLiteral(node) ? setOriginalNode(factory.createNumericLiteral(node.text, node.numericLiteralFlags), node) as Node as T : + factory.cloneNode(node); + return setTextRange(clone, node); + } + + // PERF: As an optimization, rather than calling factory.cloneNode, we'll update + // the new node created by visitEachChild with the extra changes factory.cloneNode + // would have made. + (visited as Mutable).parent = undefined!; + return visited; +} + +/** @internal */ +export function getSynthesizedDeepClones(nodes: NodeArray, includeTrivia?: boolean): NodeArray; +/** @internal */ +export function getSynthesizedDeepClones(nodes: NodeArray | undefined, includeTrivia?: boolean): NodeArray | undefined; +/** @internal */ +export function getSynthesizedDeepClones(nodes: NodeArray | undefined, includeTrivia = true): NodeArray | undefined { + if (nodes) { + const cloned = factory.createNodeArray(nodes.map(n => getSynthesizedDeepClone(n, includeTrivia)), nodes.hasTrailingComma); + setTextRange(cloned, nodes); + return cloned; + } + return nodes; +} + +/** @internal */ +export function getSynthesizedDeepClonesWithReplacements( + nodes: NodeArray, + includeTrivia: boolean, + replaceNode: (node: Node) => Node | undefined, +): NodeArray { + return factory.createNodeArray(nodes.map(n => getSynthesizedDeepCloneWithReplacements(n, includeTrivia, replaceNode)), nodes.hasTrailingComma); +} + +/** + * Sets EmitFlags to suppress leading and trailing trivia on the node. + * + * @internal + */ +export function suppressLeadingAndTrailingTrivia(node: Node): void { + suppressLeadingTrivia(node); + suppressTrailingTrivia(node); +} + +/** + * Sets EmitFlags to suppress leading trivia on the node. + * + * @internal + */ +export function suppressLeadingTrivia(node: Node): void { + addEmitFlagsRecursively(node, EmitFlags.NoLeadingComments, getFirstChild); +} + +/** + * Sets EmitFlags to suppress trailing trivia on the node. + * + * @internal @knipignore + */ +export function suppressTrailingTrivia(node: Node): void { + addEmitFlagsRecursively(node, EmitFlags.NoTrailingComments, getLastChild); +} + +function addEmitFlagsRecursively(node: Node, flag: EmitFlags, getChild: (n: Node) => Node | undefined) { + addEmitFlags(node, flag); + const child = getChild(node); + if (child) addEmitFlagsRecursively(child, flag, getChild); +} + +function getFirstChild(node: Node): Node | undefined { + return forEachChild(node, child => child); +} diff --git a/src/compiler/utilitiesPublic.ts b/src/compiler/utilitiesPublic.ts index 02623678a0cf0..36eba18db07ba 100644 --- a/src/compiler/utilitiesPublic.ts +++ b/src/compiler/utilitiesPublic.ts @@ -1534,12 +1534,13 @@ export function isImportOrExportSpecifier(node: Node): node is ImportSpecifier | export function isTypeOnlyImportDeclaration(node: Node): node is TypeOnlyImportDeclaration { switch (node.kind) { case SyntaxKind.ImportSpecifier: - return (node as ImportSpecifier).isTypeOnly || (node as ImportSpecifier).parent.parent.isTypeOnly; + return (node as ImportSpecifier).isTypeOnly || (node as ImportSpecifier).parent.parent.phaseModifier === SyntaxKind.TypeKeyword; case SyntaxKind.NamespaceImport: - return (node as NamespaceImport).parent.isTypeOnly; + return (node as NamespaceImport).parent.phaseModifier === SyntaxKind.TypeKeyword; case SyntaxKind.ImportClause: + return (node as ImportClause).phaseModifier === SyntaxKind.TypeKeyword; case SyntaxKind.ImportEqualsDeclaration: - return (node as ImportClause | ImportEqualsDeclaration).isTypeOnly; + return (node as ImportEqualsDeclaration).isTypeOnly; } return false; } diff --git a/src/compiler/visitorPublic.ts b/src/compiler/visitorPublic.ts index dbd49379e5750..d1aee94bc6e1b 100644 --- a/src/compiler/visitorPublic.ts +++ b/src/compiler/visitorPublic.ts @@ -1549,7 +1549,7 @@ const visitEachChildTable: VisitEachChildTable = { [SyntaxKind.ImportClause]: function visitEachChildOfImportClause(node, visitor, context, _nodesVisitor, nodeVisitor, _tokenVisitor) { return context.factory.updateImportClause( node, - node.isTypeOnly, + node.phaseModifier, nodeVisitor(node.name, visitor, isIdentifier), nodeVisitor(node.namedBindings, visitor, isNamedImportBindings), ); diff --git a/src/compiler/watch.ts b/src/compiler/watch.ts index a859bcc60009d..4a49afdc36492 100644 --- a/src/compiler/watch.ts +++ b/src/compiler/watch.ts @@ -436,7 +436,7 @@ export function getMatchedIncludeSpec(program: Program, fileName: string): strin const index = findIndex(configFile?.configFileSpecs?.validatedIncludeSpecs, includeSpec => { if (isJsonFile && !endsWith(includeSpec, Extension.Json)) return false; const pattern = getPatternFromSpec(includeSpec, basePath, "files"); - return !!pattern && getRegexFromPattern(`(${pattern})$`, useCaseSensitiveFileNames).test(fileName); + return !!pattern && getRegexFromPattern(`(?:${pattern})$`, useCaseSensitiveFileNames).test(fileName); }); return index !== -1 ? configFile.configFileSpecs.validatedIncludeSpecsBeforeSubstitution![index] : undefined; } diff --git a/src/harness/client.ts b/src/harness/client.ts index ec659d738c02a..786690be0f467 100644 --- a/src/harness/client.ts +++ b/src/harness/client.ts @@ -254,8 +254,8 @@ export class SessionClient implements LanguageService { return { line, character: offset }; } - getQuickInfoAtPosition(fileName: string, position: number): QuickInfo { - const args = this.createFileLocationRequestArgs(fileName, position); + getQuickInfoAtPosition(fileName: string, position: number, maximumLength?: number, verbosityLevel?: number | undefined): QuickInfo { + const args = { ...this.createFileLocationRequestArgs(fileName, position), verbosityLevel }; const request = this.processRequest(protocol.CommandTypes.Quickinfo, args); const response = this.processResponse(request); @@ -268,6 +268,7 @@ export class SessionClient implements LanguageService { displayParts: [{ kind: "text", text: body.displayString }], documentation: typeof body.documentation === "string" ? [{ kind: "text", text: body.documentation }] : body.documentation, tags: this.decodeLinkDisplayParts(body.tags), + canIncreaseVerbosityLevel: body.canIncreaseVerbosityLevel, }; } diff --git a/src/harness/fourslashImpl.ts b/src/harness/fourslashImpl.ts index e1a410dfb5d3b..e53dbb123c553 100644 --- a/src/harness/fourslashImpl.ts +++ b/src/harness/fourslashImpl.ts @@ -86,6 +86,10 @@ export interface TextSpan { end: number; } +export interface VerbosityLevels { + [markerName: string]: number | number[] | undefined; +} + // Name of testcase metadata including ts.CompilerOptions properties that will be used by globalOptions // To add additional option, add property into the testOptMetadataNames, refer the property in either globalMetadataNames or fileMetadataNames // Add cases into convertGlobalOptionsToCompilationsSettings function for the compiler to acknowledge such option from meta data @@ -2451,19 +2455,33 @@ export class TestState { return result; } - public baselineQuickInfo(): void { - const result = ts.arrayFrom(this.testData.markerPositions.entries(), ([name, marker]) => ({ - marker: { ...marker, name }, - item: this.languageService.getQuickInfoAtPosition(marker.fileName, marker.position), - })); + public baselineQuickInfo(verbosityLevels?: VerbosityLevels, maximumLength?: number): void { + const result = ts.arrayFrom(this.testData.markerPositions.entries(), ([name, marker]) => { + const verbosityLevel = toArray(verbosityLevels?.[name]); + const items = verbosityLevel.map(verbosityLevel => { + const item: ts.QuickInfo & { verbosityLevel?: number; } | undefined = this.languageService.getQuickInfoAtPosition( + marker.fileName, + marker.position, + maximumLength, + verbosityLevel, + ); + if (item) item.verbosityLevel = verbosityLevel; + return { + marker: { ...marker, name }, + item, + }; + }); + return items; + }).flat(); const annotations = this.annotateContentWithTooltips( result, "quickinfo", item => item.textSpan, - ({ displayParts, documentation, tags }) => [ + ({ displayParts, documentation, tags, verbosityLevel }) => [ ...(displayParts ? displayParts.map(p => p.text).join("").split("\n") : []), ...(documentation?.length ? documentation.map(p => p.text).join("").split("\n") : []), ...(tags?.length ? tags.map(p => `@${p.name} ${p.text?.map(dp => dp.text).join("") ?? ""}`).join("\n").split("\n") : []), + ...(verbosityLevel !== undefined ? [`(verbosity level: ${verbosityLevel})`] : []), ], ); this.baseline("QuickInfo", annotations + "\n\n" + stringify(result)); @@ -2585,9 +2603,9 @@ export class TestState { const sorted = items.slice(); // sort by file, then *backwards* by position in the file so I can insert multiple times on a line without counting sorted.sort((q1, q2) => - q1.marker.fileName === q1.marker.fileName + q1.marker.fileName === q2.marker.fileName ? (q1.marker.position > q2.marker.position ? -1 : 1) - : (q1.marker.fileName > q1.marker.fileName ? 1 : -1) + : (q1.marker.fileName > q2.marker.fileName ? 1 : -1) ); const files = new Map(); let previous: T | undefined; diff --git a/src/harness/fourslashInterfaceImpl.ts b/src/harness/fourslashInterfaceImpl.ts index ec23609de6db0..db6127dc106e0 100644 --- a/src/harness/fourslashInterfaceImpl.ts +++ b/src/harness/fourslashInterfaceImpl.ts @@ -449,8 +449,8 @@ export class Verify extends VerifyNegatable { this.state.baselineGetEmitOutput(); } - public baselineQuickInfo(): void { - this.state.baselineQuickInfo(); + public baselineQuickInfo(verbosityLevels?: FourSlash.VerbosityLevels, maximumLength?: number): void { + this.state.baselineQuickInfo(verbosityLevels, maximumLength); } public baselineSignatureHelp(): void { diff --git a/src/lib/dom.generated.d.ts b/src/lib/dom.generated.d.ts index 7b6d0275cf54e..26f0aa1022e33 100644 --- a/src/lib/dom.generated.d.ts +++ b/src/lib/dom.generated.d.ts @@ -121,7 +121,7 @@ interface AudioDataInit { interface AudioDecoderConfig { codec: string; - description?: BufferSource; + description?: AllowSharedBufferSource; numberOfChannels: number; sampleRate: number; } @@ -183,26 +183,57 @@ interface AudioWorkletNodeOptions extends AudioNodeOptions { interface AuthenticationExtensionsClientInputs { appid?: string; credProps?: boolean; + credentialProtectionPolicy?: string; + enforceCredentialProtectionPolicy?: boolean; hmacCreateSecret?: boolean; + largeBlob?: AuthenticationExtensionsLargeBlobInputs; minPinLength?: boolean; prf?: AuthenticationExtensionsPRFInputs; } interface AuthenticationExtensionsClientInputsJSON { + appid?: string; + credProps?: boolean; + largeBlob?: AuthenticationExtensionsLargeBlobInputsJSON; + prf?: AuthenticationExtensionsPRFInputsJSON; } interface AuthenticationExtensionsClientOutputs { appid?: boolean; credProps?: CredentialPropertiesOutput; hmacCreateSecret?: boolean; + largeBlob?: AuthenticationExtensionsLargeBlobOutputs; prf?: AuthenticationExtensionsPRFOutputs; } +interface AuthenticationExtensionsLargeBlobInputs { + read?: boolean; + support?: string; + write?: BufferSource; +} + +interface AuthenticationExtensionsLargeBlobInputsJSON { + read?: boolean; + support?: string; + write?: Base64URLString; +} + +interface AuthenticationExtensionsLargeBlobOutputs { + blob?: ArrayBuffer; + supported?: boolean; + written?: boolean; +} + interface AuthenticationExtensionsPRFInputs { eval?: AuthenticationExtensionsPRFValues; evalByCredential?: Record; } +interface AuthenticationExtensionsPRFInputsJSON { + eval?: AuthenticationExtensionsPRFValuesJSON; + evalByCredential?: Record; +} + interface AuthenticationExtensionsPRFOutputs { enabled?: boolean; results?: AuthenticationExtensionsPRFValues; @@ -213,6 +244,11 @@ interface AuthenticationExtensionsPRFValues { second?: BufferSource; } +interface AuthenticationExtensionsPRFValuesJSON { + first: Base64URLString; + second?: Base64URLString; +} + interface AuthenticatorSelectionCriteria { authenticatorAttachment?: AuthenticatorAttachment; requireResidentKey?: boolean; @@ -232,7 +268,7 @@ interface BiquadFilterOptions extends AudioNodeOptions { type?: BiquadFilterType; } -interface BlobEventInit { +interface BlobEventInit extends EventInit { data: Blob; timecode?: DOMHighResTimeStamp; } @@ -369,6 +405,38 @@ interface ConvolverOptions extends AudioNodeOptions { disableNormalization?: boolean; } +interface CookieChangeEventInit extends EventInit { + changed?: CookieList; + deleted?: CookieList; +} + +interface CookieInit { + domain?: string | null; + expires?: DOMHighResTimeStamp | null; + name: string; + partitioned?: boolean; + path?: string; + sameSite?: CookieSameSite; + value: string; +} + +interface CookieListItem { + name?: string; + value?: string; +} + +interface CookieStoreDeleteOptions { + domain?: string | null; + name: string; + partitioned?: boolean; + path?: string; +} + +interface CookieStoreGetOptions { + name?: string; + url?: string; +} + interface CredentialCreationOptions { publicKey?: PublicKeyCredentialCreationOptions; signal?: AbortSignal; @@ -533,6 +601,7 @@ interface EffectTiming { } interface ElementCreationOptions { + customElementRegistry?: CustomElementRegistry; is?: string; } @@ -680,6 +749,10 @@ interface GetAnimationsOptions { subtree?: boolean; } +interface GetComposedRangesOptions { + shadowRoots?: ShadowRoot[]; +} + interface GetHTMLOptions { serializableShadowRoots?: boolean; shadowRoots?: ShadowRoot[]; @@ -794,6 +867,11 @@ interface ImageEncodeOptions { type?: string; } +interface ImportNodeOptions { + customElementRegistry?: CustomElementRegistry; + selfOnly?: boolean; +} + interface InputEventInit extends UIEventInit { data?: string | null; dataTransfer?: DataTransfer | null; @@ -833,6 +911,10 @@ interface KeyAlgorithm { name: string; } +interface KeySystemTrackConfiguration { + robustness?: string; +} + interface KeyboardEventInit extends EventModifierInit { /** @deprecated */ charCode?: number; @@ -886,7 +968,7 @@ interface MIDIConnectionEventInit extends EventInit { } interface MIDIMessageEventInit extends EventInit { - data?: Uint8Array; + data?: Uint8Array; } interface MIDIOptions { @@ -895,11 +977,10 @@ interface MIDIOptions { } interface MediaCapabilitiesDecodingInfo extends MediaCapabilitiesInfo { - configuration?: MediaDecodingConfiguration; + keySystemAccess: MediaKeySystemAccess | null; } interface MediaCapabilitiesEncodingInfo extends MediaCapabilitiesInfo { - configuration?: MediaEncodingConfiguration; } interface MediaCapabilitiesInfo { @@ -908,12 +989,23 @@ interface MediaCapabilitiesInfo { supported: boolean; } +interface MediaCapabilitiesKeySystemConfiguration { + audio?: KeySystemTrackConfiguration; + distinctiveIdentifier?: MediaKeysRequirement; + initDataType?: string; + keySystem: string; + persistentState?: MediaKeysRequirement; + sessionTypes?: string[]; + video?: KeySystemTrackConfiguration; +} + interface MediaConfiguration { audio?: AudioConfiguration; video?: VideoConfiguration; } interface MediaDecodingConfiguration extends MediaConfiguration { + keySystemConfiguration?: MediaCapabilitiesKeySystemConfiguration; type: MediaDecodingType; } @@ -993,6 +1085,12 @@ interface MediaSessionActionDetails { seekTime?: number; } +interface MediaSettingsRange { + max?: number; + min?: number; + step?: number; +} + interface MediaStreamAudioSourceOptions { mediaStream: MediaStream; } @@ -1063,7 +1161,10 @@ interface MediaTrackSettings { noiseSuppression?: boolean; sampleRate?: number; sampleSize?: number; + torch?: boolean; + whiteBalanceMode?: string; width?: number; + zoom?: number; } interface MediaTrackSupportedConstraints { @@ -1323,6 +1424,20 @@ interface PermissionDescriptor { name: PermissionName; } +interface PhotoCapabilities { + fillLightMode?: FillLightMode[]; + imageHeight?: MediaSettingsRange; + imageWidth?: MediaSettingsRange; + redEyeReduction?: RedEyeReduction; +} + +interface PhotoSettings { + fillLightMode?: FillLightMode; + imageHeight?: number; + imageWidth?: number; + redEyeReduction?: boolean; +} + interface PictureInPictureEventInit extends EventInit { pictureInPictureWindow: PictureInPictureWindow; } @@ -1531,21 +1646,23 @@ interface RTCDtlsFingerprint { value?: string; } -interface RTCEncodedAudioFrameMetadata { +interface RTCEncodedAudioFrameMetadata extends RTCEncodedFrameMetadata { + sequenceNumber?: number; +} + +interface RTCEncodedFrameMetadata { contributingSources?: number[]; + mimeType?: string; payloadType?: number; - sequenceNumber?: number; + rtpTimestamp?: number; synchronizationSource?: number; } -interface RTCEncodedVideoFrameMetadata { - contributingSources?: number[]; +interface RTCEncodedVideoFrameMetadata extends RTCEncodedFrameMetadata { dependencies?: number[]; frameId?: number; height?: number; - payloadType?: number; spatialIndex?: number; - synchronizationSource?: number; temporalIndex?: number; timestamp?: number; width?: number; @@ -1657,6 +1774,9 @@ interface RTCInboundRtpStreamStats extends RTCReceivedRtpStreamStats { trackIdentifier: string; } +interface RTCLocalIceCandidateInit extends RTCIceCandidateInit { +} + interface RTCLocalSessionDescriptionInit { sdp?: string; type?: RTCSdpType; @@ -1712,7 +1832,6 @@ interface RTCPeerConnectionIceErrorEventInit extends EventInit { interface RTCPeerConnectionIceEventInit extends EventInit { candidate?: RTCIceCandidate | null; - url?: string | null; } interface RTCReceivedRtpStreamStats extends RTCRtpStreamStats { @@ -1870,7 +1989,7 @@ interface ReadableStreamIteratorOptions { interface ReadableStreamReadDoneResult { done: true; - value?: T; + value: T | undefined; } interface ReadableStreamReadValueResult { @@ -2012,6 +2131,8 @@ interface SecurityPolicyViolationEventInit extends EventInit { } interface ShadowRootInit { + clonable?: boolean; + customElementRegistry?: CustomElementRegistry; delegatesFocus?: boolean; mode: ShadowRootMode; serializable?: boolean; @@ -2037,6 +2158,11 @@ interface SpeechSynthesisEventInit extends EventInit { utterance: SpeechSynthesisUtterance; } +interface StartViewTransitionOptions { + types?: string[] | null; + update?: ViewTransitionUpdateCallback | null; +} + interface StaticRangeInit { endContainer: Node; endOffset: number; @@ -2373,10 +2499,13 @@ interface WebTransportOptions { serverCertificateHashes?: WebTransportHash[]; } -interface WebTransportSendStreamOptions { +interface WebTransportSendOptions { sendOrder?: number; } +interface WebTransportSendStreamOptions extends WebTransportSendOptions { +} + interface WheelEventInit extends MouseEventInit { deltaMode?: number; deltaX?: number; @@ -2429,21 +2558,35 @@ declare var NodeFilter: { type XPathNSResolver = ((prefix: string | null) => string | null) | { lookupNamespaceURI(prefix: string | null): string | null; }; /** - * The ANGLE_instanced_arrays extension is part of the WebGL API and allows to draw the same object, or groups of similar objects multiple times, if they share the same vertex data, primitive count and type. + * The **`ANGLE_instanced_arrays`** extension is part of the WebGL API and allows to draw the same object, or groups of similar objects multiple times, if they share the same vertex data, primitive count and type. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays) */ interface ANGLE_instanced_arrays { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays/drawArraysInstancedANGLE) */ + /** + * The **`ANGLE_instanced_arrays.drawArraysInstancedANGLE()`** method of the WebGL API renders primitives from array data like the WebGLRenderingContext.drawArrays() method. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays/drawArraysInstancedANGLE) + */ drawArraysInstancedANGLE(mode: GLenum, first: GLint, count: GLsizei, primcount: GLsizei): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays/drawElementsInstancedANGLE) */ + /** + * The **`ANGLE_instanced_arrays.drawElementsInstancedANGLE()`** method of the WebGL API renders primitives from array data like the WebGLRenderingContext.drawElements() method. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays/drawElementsInstancedANGLE) + */ drawElementsInstancedANGLE(mode: GLenum, count: GLsizei, type: GLenum, offset: GLintptr, primcount: GLsizei): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays/vertexAttribDivisorANGLE) */ + /** + * The **ANGLE_instanced_arrays.vertexAttribDivisorANGLE()** method of the WebGL API modifies the rate at which generic vertex attributes advance when rendering multiple instances of primitives with ANGLE_instanced_arrays.drawArraysInstancedANGLE() and ANGLE_instanced_arrays.drawElementsInstancedANGLE(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ANGLE_instanced_arrays/vertexAttribDivisorANGLE) + */ vertexAttribDivisorANGLE(index: GLuint, divisor: GLuint): void; readonly VERTEX_ATTRIB_ARRAY_DIVISOR_ANGLE: 0x88FE; } interface ARIAMixin { + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaActiveDescendantElement) */ + ariaActiveDescendantElement: Element | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaAtomic) */ ariaAtomic: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaAutoComplete) */ @@ -2464,23 +2607,36 @@ interface ARIAMixin { ariaColIndexText: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaColSpan) */ ariaColSpan: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaControlsElements) */ + ariaControlsElements: ReadonlyArray | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaCurrent) */ ariaCurrent: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaDescribedByElements) */ + ariaDescribedByElements: ReadonlyArray | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaDescription) */ ariaDescription: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaDetailsElements) */ + ariaDetailsElements: ReadonlyArray | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaDisabled) */ ariaDisabled: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaErrorMessageElements) */ + ariaErrorMessageElements: ReadonlyArray | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaExpanded) */ ariaExpanded: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaFlowToElements) */ + ariaFlowToElements: ReadonlyArray | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaHasPopup) */ ariaHasPopup: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaHidden) */ ariaHidden: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaInvalid) */ ariaInvalid: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaKeyShortcuts) */ ariaKeyShortcuts: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaLabel) */ ariaLabel: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaLabelledByElements) */ + ariaLabelledByElements: ReadonlyArray | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaLevel) */ ariaLevel: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaLive) */ @@ -2493,6 +2649,8 @@ interface ARIAMixin { ariaMultiSelectable: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaOrientation) */ ariaOrientation: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaOwnsElements) */ + ariaOwnsElements: ReadonlyArray | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaPlaceholder) */ ariaPlaceholder: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaPosInSet) */ @@ -2529,23 +2687,24 @@ interface ARIAMixin { ariaValueNow: string | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/ariaValueText) */ ariaValueText: string | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/role) */ role: string | null; } /** - * A controller object that allows you to abort one or more DOM requests as and when desired. + * The **`AbortController`** interface represents a controller object that allows you to abort one or more Web requests as and when desired. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController) */ interface AbortController { /** - * Returns the AbortSignal object associated with this object. + * The **`signal`** read-only property of the AbortController interface returns an AbortSignal object instance, which can be used to communicate with/abort an asynchronous operation as desired. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/signal) */ readonly signal: AbortSignal; /** - * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted. + * The **`abort()`** method of the AbortController interface aborts an asynchronous operation before it has completed. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort) */ @@ -2562,22 +2721,30 @@ interface AbortSignalEventMap { } /** - * A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object. + * The **`AbortSignal`** interface represents a signal object that allows you to communicate with an asynchronous operation (such as a fetch request) and abort it if required via an AbortController object. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal) */ interface AbortSignal extends EventTarget { /** - * Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise. + * The **`aborted`** read-only property returns a value that indicates whether the asynchronous operations the signal is communicating with are aborted (`true`) or not (`false`). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/aborted) */ readonly aborted: boolean; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_event) */ onabort: ((this: AbortSignal, ev: Event) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/reason) */ + /** + * The **`reason`** read-only property returns a JavaScript value that indicates the abort reason. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/reason) + */ readonly reason: any; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/throwIfAborted) */ + /** + * The **`throwIfAborted()`** method throws the signal's abort AbortSignal.reason if the signal has been aborted; otherwise it does nothing. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/throwIfAborted) + */ throwIfAborted(): void; addEventListener(type: K, listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -2588,42 +2755,58 @@ interface AbortSignal extends EventTarget { declare var AbortSignal: { prototype: AbortSignal; new(): AbortSignal; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_static) */ + /** + * The **`AbortSignal.abort()`** static method returns an AbortSignal that is already set as aborted (and which does not trigger an AbortSignal/abort_event event). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_static) + */ abort(reason?: any): AbortSignal; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/any_static) */ + /** + * The **`AbortSignal.any()`** static method takes an iterable of abort signals and returns an AbortSignal. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/any_static) + */ any(signals: AbortSignal[]): AbortSignal; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/timeout_static) */ + /** + * The **`AbortSignal.timeout()`** static method returns an AbortSignal that will automatically abort after a specified time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/timeout_static) + */ timeout(milliseconds: number): AbortSignal; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbstractRange) */ +/** + * The **`AbstractRange`** abstract interface is the base class upon which all DOM range types are defined. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbstractRange) + */ interface AbstractRange { /** - * Returns true if range is collapsed, and false otherwise. + * The read-only **`collapsed`** property of the AbstractRange interface returns `true` if the range's start position and end position are the same. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbstractRange/collapsed) */ readonly collapsed: boolean; /** - * Returns range's end node. + * The read-only **`endContainer`** property of the AbstractRange interface returns the Node in which the end of the range is located. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbstractRange/endContainer) */ readonly endContainer: Node; /** - * Returns range's end offset. + * The **`endOffset`** property of the AbstractRange interface returns the offset into the end node of the range's end position. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbstractRange/endOffset) */ readonly endOffset: number; /** - * Returns range's start node. + * The read-only **`startContainer`** property of the AbstractRange interface returns the start Node for the range. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbstractRange/startContainer) */ readonly startContainer: Node; /** - * Returns range's start offset. + * The read-only **`startOffset`** property of the AbstractRange interface returns the offset into the start node of the range's start position. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbstractRange/startOffset) */ @@ -2649,29 +2832,65 @@ interface AbstractWorker { } /** - * A node able to provide real-time frequency and time-domain analysis information. It is an AudioNode that passes the audio stream unchanged from the input to the output, but allows you to take the generated data, process it, and create audio visualizations. + * The **`AnalyserNode`** interface represents a node able to provide real-time frequency and time-domain analysis information. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode) */ interface AnalyserNode extends AudioNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/fftSize) */ + /** + * The **`fftSize`** property of the AnalyserNode interface is an unsigned long value and represents the window size in samples that is used when performing a Fast Fourier Transform (FFT) to get frequency domain data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/fftSize) + */ fftSize: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/frequencyBinCount) */ + /** + * The **`frequencyBinCount`** read-only property of the AnalyserNode interface contains the total number of data points available to AudioContext BaseAudioContext.sampleRate. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/frequencyBinCount) + */ readonly frequencyBinCount: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/maxDecibels) */ + /** + * The **`maxDecibels`** property of the AnalyserNode interface is a double value representing the maximum power value in the scaling range for the FFT analysis data, for conversion to unsigned byte values — basically, this specifies the maximum value for the range of results when using `getByteFrequencyData()`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/maxDecibels) + */ maxDecibels: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/minDecibels) */ + /** + * The **`minDecibels`** property of the AnalyserNode interface is a double value representing the minimum power value in the scaling range for the FFT analysis data, for conversion to unsigned byte values — basically, this specifies the minimum value for the range of results when using `getByteFrequencyData()`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/minDecibels) + */ minDecibels: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/smoothingTimeConstant) */ + /** + * The **`smoothingTimeConstant`** property of the AnalyserNode interface is a double value representing the averaging constant with the last analysis frame. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/smoothingTimeConstant) + */ smoothingTimeConstant: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getByteFrequencyData) */ - getByteFrequencyData(array: Uint8Array): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getByteTimeDomainData) */ - getByteTimeDomainData(array: Uint8Array): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getFloatFrequencyData) */ - getFloatFrequencyData(array: Float32Array): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getFloatTimeDomainData) */ - getFloatTimeDomainData(array: Float32Array): void; + /** + * The **`getByteFrequencyData()`** method of the AnalyserNode interface copies the current frequency data into a Uint8Array (unsigned byte array) passed into it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getByteFrequencyData) + */ + getByteFrequencyData(array: Uint8Array): void; + /** + * The **`getByteTimeDomainData()`** method of the AnalyserNode Interface copies the current waveform, or time-domain, data into a Uint8Array (unsigned byte array) passed into it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getByteTimeDomainData) + */ + getByteTimeDomainData(array: Uint8Array): void; + /** + * The **`getFloatFrequencyData()`** method of the AnalyserNode Interface copies the current frequency data into a Float32Array array passed into it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getFloatFrequencyData) + */ + getFloatFrequencyData(array: Float32Array): void; + /** + * The **`getFloatTimeDomainData()`** method of the AnalyserNode Interface copies the current waveform, or time-domain, data into a Float32Array array passed into it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnalyserNode/getFloatTimeDomainData) + */ + getFloatTimeDomainData(array: Float32Array): void; } declare var AnalyserNode: { @@ -2692,15 +2911,35 @@ interface AnimationEventMap { "remove": AnimationPlaybackEvent; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation) */ +/** + * The **`Animation`** interface of the Web Animations API represents a single animation player and provides playback controls and a timeline for an animation node or source. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation) + */ interface Animation extends EventTarget { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/currentTime) */ + /** + * The **`Animation.currentTime`** property of the Web Animations API returns and sets the current time value of the animation in milliseconds, whether running or paused. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/currentTime) + */ currentTime: CSSNumberish | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/effect) */ + /** + * The **`Animation.effect`** property of the Web Animations API gets and sets the target effect of an animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/effect) + */ effect: AnimationEffect | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/finished) */ + /** + * The **`Animation.finished`** read-only property of the Web Animations API returns a Promise which resolves once the animation has finished playing. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/finished) + */ readonly finished: Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/id) */ + /** + * The **`Animation.id`** property of the Web Animations API returns or sets a string used to identify the animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/id) + */ id: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/cancel_event) */ oncancel: ((this: Animation, ev: AnimationPlaybackEvent) => any) | null; @@ -2708,35 +2947,95 @@ interface Animation extends EventTarget { onfinish: ((this: Animation, ev: AnimationPlaybackEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/remove_event) */ onremove: ((this: Animation, ev: AnimationPlaybackEvent) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/pending) */ + /** + * The read-only **`Animation.pending`** property of the Web Animations API indicates whether the animation is currently waiting for an asynchronous operation such as initiating playback or pausing a running animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/pending) + */ readonly pending: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/playState) */ + /** + * The read-only **`Animation.playState`** property of the Web Animations API returns an enumerated value describing the playback state of an animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/playState) + */ readonly playState: AnimationPlayState; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/playbackRate) */ + /** + * The **`Animation.playbackRate`** property of the Web Animations API returns or sets the playback rate of the animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/playbackRate) + */ playbackRate: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/ready) */ + /** + * The read-only **`Animation.ready`** property of the Web Animations API returns a Promise which resolves when the animation is ready to play. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/ready) + */ readonly ready: Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/replaceState) */ + /** + * The read-only **`Animation.replaceState`** property of the Web Animations API indicates whether the animation has been removed by the browser automatically after being replaced by another animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/replaceState) + */ readonly replaceState: AnimationReplaceState; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/startTime) */ + /** + * The **`Animation.startTime`** property of the Animation interface is a double-precision floating-point value which indicates the scheduled time when an animation's playback should begin. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/startTime) + */ startTime: CSSNumberish | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/timeline) */ + /** + * The **`Animation.timeline`** property of the Animation interface returns or sets the AnimationTimeline associated with this animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/timeline) + */ timeline: AnimationTimeline | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/cancel) */ + /** + * The Web Animations API's **`cancel()`** method of the Animation interface clears all KeyframeEffects caused by this animation and aborts its playback. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/cancel) + */ cancel(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/commitStyles) */ + /** + * The `commitStyles()` method of the Web Animations API's Animation interface writes the computed values of the animation's current styles into its target element's `style` attribute. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/commitStyles) + */ commitStyles(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/finish) */ + /** + * The **`finish()`** method of the Web Animations API's Animation Interface sets the current playback time to the end of the animation corresponding to the current playback direction. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/finish) + */ finish(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/pause) */ + /** + * The **`pause()`** method of the Web Animations API's Animation interface suspends playback of the animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/pause) + */ pause(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/persist) */ + /** + * The `persist()` method of the Web Animations API's Animation interface explicitly persists an animation, preventing it from being automatically removed when it is replaced by another animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/persist) + */ persist(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/play) */ + /** + * The **`play()`** method of the Web Animations API's Animation Interface starts or resumes playing of an animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/play) + */ play(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/reverse) */ + /** + * The **`Animation.reverse()`** method of the Animation Interface reverses the playback direction, meaning the animation ends at its beginning. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/reverse) + */ reverse(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/updatePlaybackRate) */ + /** + * The **`updatePlaybackRate()`** method of the Web Animations API's synchronizing its playback position. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Animation/updatePlaybackRate) + */ updatePlaybackRate(playbackRate: number): void; addEventListener(type: K, listener: (this: Animation, ev: AnimationEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -2749,13 +3048,29 @@ declare var Animation: { new(effect?: AnimationEffect | null, timeline?: AnimationTimeline | null): Animation; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect) */ +/** + * The `AnimationEffect` interface of the Web Animations API is an interface representing animation effects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect) + */ interface AnimationEffect { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect/getComputedTiming) */ + /** + * The `getComputedTiming()` method of the AnimationEffect interface returns the calculated timing properties for this animation effect. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect/getComputedTiming) + */ getComputedTiming(): ComputedEffectTiming; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect/getTiming) */ + /** + * The `AnimationEffect.getTiming()` method of the AnimationEffect interface returns an object containing the timing properties for the Animation Effect. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect/getTiming) + */ getTiming(): EffectTiming; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect/updateTiming) */ + /** + * The `updateTiming()` method of the AnimationEffect interface updates the specified timing properties for an animation effect. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEffect/updateTiming) + */ updateTiming(timing?: OptionalEffectTiming): void; } @@ -2765,16 +3080,28 @@ declare var AnimationEffect: { }; /** - * Events providing information related to animations. + * The **`AnimationEvent`** interface represents events providing information related to animations. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEvent) */ interface AnimationEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEvent/animationName) */ + /** + * The **`AnimationEvent.animationName`** read-only property is a string containing the value of the animation-name CSS property associated with the transition. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEvent/animationName) + */ readonly animationName: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEvent/elapsedTime) */ + /** + * The **`AnimationEvent.elapsedTime`** read-only property is a `float` giving the amount of time the animation has been running, in seconds, when this event fired, excluding any time the animation was paused. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEvent/elapsedTime) + */ readonly elapsedTime: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEvent/pseudoElement) */ + /** + * The **`AnimationEvent.pseudoElement`** read-only property is a string, starting with `'::'`, containing the name of the pseudo-element the animation runs on. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationEvent/pseudoElement) + */ readonly pseudoElement: string; } @@ -2790,11 +3117,23 @@ interface AnimationFrameProvider { requestAnimationFrame(callback: FrameRequestCallback): number; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationPlaybackEvent) */ +/** + * The AnimationPlaybackEvent interface of the Web Animations API represents animation events. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationPlaybackEvent) + */ interface AnimationPlaybackEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationPlaybackEvent/currentTime) */ + /** + * The **`currentTime`** read-only property of the AnimationPlaybackEvent interface represents the current time of the animation that generated the event at the moment the event is queued. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationPlaybackEvent/currentTime) + */ readonly currentTime: CSSNumberish | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationPlaybackEvent/timelineTime) */ + /** + * The **`timelineTime`** read-only property of the AnimationPlaybackEvent interface represents the time value of the animation's AnimationTimeline at the moment the event is queued. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationPlaybackEvent/timelineTime) + */ readonly timelineTime: CSSNumberish | null; } @@ -2803,9 +3142,17 @@ declare var AnimationPlaybackEvent: { new(type: string, eventInitDict?: AnimationPlaybackEventInit): AnimationPlaybackEvent; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationTimeline) */ +/** + * The `AnimationTimeline` interface of the Web Animations API represents the timeline of an animation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationTimeline) + */ interface AnimationTimeline { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationTimeline/currentTime) */ + /** + * The **`currentTime`** read-only property of the Web Animations API's AnimationTimeline interface returns the timeline's current time in milliseconds, or `null` if the timeline is inactive. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AnimationTimeline/currentTime) + */ readonly currentTime: CSSNumberish | null; } @@ -2815,30 +3162,58 @@ declare var AnimationTimeline: { }; /** - * A DOM element's attribute as an object. In most DOM methods, you will probably directly retrieve the attribute as a string (e.g., Element.getAttribute(), but certain functions (e.g., Element.getAttributeNode()) or means of iterating give Attr types. + * The **`Attr`** interface represents one of an element's attributes as an object. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr) */ interface Attr extends Node { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/localName) */ + /** + * The read-only **`localName`** property of the Attr interface returns the _local part_ of the _qualified name_ of an attribute, that is the name of the attribute, stripped from any namespace in front of it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/localName) + */ readonly localName: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/name) */ + /** + * The read-only **`name`** property of the Attr interface returns the _qualified name_ of an attribute, that is the name of the attribute, with the namespace prefix, if any, in front of it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/name) + */ readonly name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/namespaceURI) */ + /** + * The read-only **`namespaceURI`** property of the Attr interface returns the namespace URI of the attribute, or `null` if the element is not in a namespace. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/namespaceURI) + */ readonly namespaceURI: string | null; readonly ownerDocument: Document; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/ownerElement) */ + /** + * The read-only **`ownerElement`** property of the Attr interface returns the Element the attribute belongs to. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/ownerElement) + */ readonly ownerElement: Element | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/prefix) */ + /** + * The read-only **`prefix`** property of the Attr returns the namespace prefix of the attribute, or `null` if no prefix is specified. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/prefix) + */ readonly prefix: string | null; /** + * The read-only **`specified`** property of the Attr interface always returns `true`. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/specified) */ readonly specified: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/value) */ + /** + * The **`value`** property of the Attr interface contains the value of the attribute. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Attr/value) + */ value: string; + /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) */ + get textContent(): string; + set textContent(value: string | null); } declare var Attr: { @@ -2847,51 +3222,107 @@ declare var Attr: { }; /** - * A short audio asset residing in memory, created from an audio file using the AudioContext.decodeAudioData() method, or from raw data using AudioContext.createBuffer(). Once put into an AudioBuffer, the audio can then be played by being passed into an AudioBufferSourceNode. + * The **`AudioBuffer`** interface represents a short audio asset residing in memory, created from an audio file using the BaseAudioContext/decodeAudioData method, or from raw data using BaseAudioContext/createBuffer. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer) */ interface AudioBuffer { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/duration) */ + /** + * The **`duration`** property of the AudioBuffer interface returns a double representing the duration, in seconds, of the PCM data stored in the buffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/duration) + */ readonly duration: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/length) */ + /** + * The **`length`** property of the AudioBuffer interface returns an integer representing the length, in sample-frames, of the PCM data stored in the buffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/length) + */ readonly length: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/numberOfChannels) */ + /** + * The `numberOfChannels` property of the AudioBuffer interface returns an integer representing the number of discrete audio channels described by the PCM data stored in the buffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/numberOfChannels) + */ readonly numberOfChannels: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/sampleRate) */ + /** + * The **`sampleRate`** property of the AudioBuffer interface returns a float representing the sample rate, in samples per second, of the PCM data stored in the buffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/sampleRate) + */ readonly sampleRate: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/copyFromChannel) */ - copyFromChannel(destination: Float32Array, channelNumber: number, bufferOffset?: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/copyToChannel) */ - copyToChannel(source: Float32Array, channelNumber: number, bufferOffset?: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/getChannelData) */ - getChannelData(channel: number): Float32Array; -} - -declare var AudioBuffer: { - prototype: AudioBuffer; - new(options: AudioBufferOptions): AudioBuffer; -}; - -/** - * An AudioScheduledSourceNode which represents an audio source consisting of in-memory audio data, stored in an AudioBuffer. It's especially useful for playing back audio which has particularly stringent timing accuracy requirements, such as for sounds that must match a specific rhythm and can be kept in memory rather than being played from disk or the network. + /** + * The **`copyFromChannel()`** method of the channel of the `AudioBuffer` to a specified ```js-nolint copyFromChannel(destination, channelNumber, startInChannel) ``` - `destination` - : A Float32Array to copy the channel's samples to. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/copyFromChannel) + */ + copyFromChannel(destination: Float32Array, channelNumber: number, bufferOffset?: number): void; + /** + * The `copyToChannel()` method of the AudioBuffer interface copies the samples to the specified channel of the `AudioBuffer`, from the source array. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/copyToChannel) + */ + copyToChannel(source: Float32Array, channelNumber: number, bufferOffset?: number): void; + /** + * The **`getChannelData()`** method of the AudioBuffer Interface returns a Float32Array containing the PCM data associated with the channel, defined by the channel parameter (with 0 representing the first channel). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBuffer/getChannelData) + */ + getChannelData(channel: number): Float32Array; +} + +declare var AudioBuffer: { + prototype: AudioBuffer; + new(options: AudioBufferOptions): AudioBuffer; +}; + +/** + * The **`AudioBufferSourceNode`** interface is an AudioScheduledSourceNode which represents an audio source consisting of in-memory audio data, stored in an AudioBuffer. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode) */ interface AudioBufferSourceNode extends AudioScheduledSourceNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/buffer) */ + /** + * The **`buffer`** property of the AudioBufferSourceNode interface provides the ability to play back audio using an AudioBuffer as the source of the sound data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/buffer) + */ buffer: AudioBuffer | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/detune) */ + /** + * The **`detune`** property of the representing detuning of oscillation in cents. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/detune) + */ readonly detune: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/loop) */ + /** + * The `loop` property of the AudioBufferSourceNode interface is a Boolean indicating if the audio asset must be replayed when the end of the AudioBuffer is reached. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/loop) + */ loop: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/loopEnd) */ + /** + * The `loopEnd` property of the AudioBufferSourceNode interface specifies is a floating point number specifying, in seconds, at what offset into playing the AudioBuffer playback should loop back to the time indicated by the AudioBufferSourceNode.loopStart property. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/loopEnd) + */ loopEnd: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/loopStart) */ + /** + * The **`loopStart`** property of the AudioBufferSourceNode interface is a floating-point value indicating, in seconds, where in the AudioBuffer the restart of the play must happen. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/loopStart) + */ loopStart: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/playbackRate) */ + /** + * The **`playbackRate`** property of the AudioBufferSourceNode interface Is a k-rate AudioParam that defines the speed at which the audio asset will be played. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/playbackRate) + */ readonly playbackRate: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/start) */ + /** + * The `start()` method of the AudioBufferSourceNode Interface is used to schedule playback of the audio data contained in the buffer, or to begin playback immediately. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioBufferSourceNode/start) + */ start(when?: number, offset?: number, duration?: number): void; addEventListener(type: K, listener: (this: AudioBufferSourceNode, ev: AudioScheduledSourceNodeEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -2905,28 +3336,64 @@ declare var AudioBufferSourceNode: { }; /** - * An audio-processing graph built from audio modules linked together, each represented by an AudioNode. + * The `AudioContext` interface represents an audio-processing graph built from audio modules linked together, each represented by an AudioNode. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext) */ interface AudioContext extends BaseAudioContext { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/baseLatency) */ + /** + * The **`baseLatency`** read-only property of the seconds of processing latency incurred by the `AudioContext` passing an audio buffer from the AudioDestinationNode — i.e., the end of the audio graph — into the host system's audio subsystem ready for playing. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/baseLatency) + */ readonly baseLatency: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/outputLatency) */ + /** + * The **`outputLatency`** read-only property of the AudioContext Interface provides an estimation of the output latency of the current audio context. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/outputLatency) + */ readonly outputLatency: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/close) */ + /** + * The `close()` method of the AudioContext Interface closes the audio context, releasing any system audio resources that it uses. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/close) + */ close(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/createMediaElementSource) */ + /** + * The `createMediaElementSource()` method of the AudioContext Interface is used to create a new MediaElementAudioSourceNode object, given an existing HTML audio or video element, the audio from which can then be played and manipulated. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/createMediaElementSource) + */ createMediaElementSource(mediaElement: HTMLMediaElement): MediaElementAudioSourceNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/createMediaStreamDestination) */ + /** + * The `createMediaStreamDestination()` method of the AudioContext Interface is used to create a new MediaStreamAudioDestinationNode object associated with a WebRTC MediaStream representing an audio stream, which may be stored in a local file or sent to another computer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/createMediaStreamDestination) + */ createMediaStreamDestination(): MediaStreamAudioDestinationNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/createMediaStreamSource) */ + /** + * The `createMediaStreamSource()` method of the AudioContext Interface is used to create a new MediaStreamAudioSourceNode object, given a media stream (say, from a MediaDevices.getUserMedia instance), the audio from which can then be played and manipulated. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/createMediaStreamSource) + */ createMediaStreamSource(mediaStream: MediaStream): MediaStreamAudioSourceNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/getOutputTimestamp) */ + /** + * The **`getOutputTimestamp()`** method of the containing two audio timestamp values relating to the current audio context. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/getOutputTimestamp) + */ getOutputTimestamp(): AudioTimestamp; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/resume) */ + /** + * The **`resume()`** method of the AudioContext interface resumes the progression of time in an audio context that has previously been suspended. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/resume) + */ resume(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/suspend) */ + /** + * The `suspend()` method of the AudioContext Interface suspends the progression of time in the audio context, temporarily halting audio hardware access and reducing CPU/battery usage in the process — this is useful if you want an application to power down the audio hardware when it will not be using an audio context for a while. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioContext/suspend) + */ suspend(): Promise; addEventListener(type: K, listener: (this: AudioContext, ev: BaseAudioContextEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -2939,27 +3406,71 @@ declare var AudioContext: { new(contextOptions?: AudioContextOptions): AudioContext; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData) */ +/** + * The **`AudioData`** interface of the WebCodecs API represents an audio sample. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData) + */ interface AudioData { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/duration) */ + /** + * The **`duration`** read-only property of the AudioData interface returns the duration in microseconds of this `AudioData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/duration) + */ readonly duration: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/format) */ + /** + * The **`format`** read-only property of the AudioData interface returns the sample format of the `AudioData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/format) + */ readonly format: AudioSampleFormat | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/numberOfChannels) */ + /** + * The **`numberOfChannels`** read-only property of the AudioData interface returns the number of channels in the `AudioData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/numberOfChannels) + */ readonly numberOfChannels: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/numberOfFrames) */ + /** + * The **`numberOfFrames`** read-only property of the AudioData interface returns the number of frames in the `AudioData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/numberOfFrames) + */ readonly numberOfFrames: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/sampleRate) */ + /** + * The **`sampleRate`** read-only property of the AudioData interface returns the sample rate in Hz. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/sampleRate) + */ readonly sampleRate: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/timestamp) */ + /** + * The **`timestamp`** read-only property of the AudioData interface returns the timestamp of this `AudioData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/timestamp) + */ readonly timestamp: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/allocationSize) */ + /** + * The **`allocationSize()`** method of the AudioData interface returns the size in bytes required to hold the current sample as filtered by options passed into the method. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/allocationSize) + */ allocationSize(options: AudioDataCopyToOptions): number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/clone) */ + /** + * The **`clone()`** method of the AudioData interface creates a new `AudioData` object with reference to the same media resource as the original. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/clone) + */ clone(): AudioData; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/close) */ + /** + * The **`close()`** method of the AudioData interface clears all states and releases the reference to the media resource. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/close) + */ close(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/copyTo) */ + /** + * The **`copyTo()`** method of the AudioData interface copies a plane of an `AudioData` object to a destination buffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioData/copyTo) + */ copyTo(destination: AllowSharedBufferSource, options: AudioDataCopyToOptions): void; } @@ -2973,26 +3484,55 @@ interface AudioDecoderEventMap { } /** + * The **`AudioDecoder`** interface of the WebCodecs API decodes chunks of audio. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder) */ interface AudioDecoder extends EventTarget { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/decodeQueueSize) */ + /** + * The **`decodeQueueSize`** read-only property of the AudioDecoder interface returns the number of pending decode requests in the queue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/decodeQueueSize) + */ readonly decodeQueueSize: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/dequeue_event) */ ondequeue: ((this: AudioDecoder, ev: Event) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/state) */ + /** + * The **`state`** read-only property of the AudioDecoder interface returns the current state of the underlying codec. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/state) + */ readonly state: CodecState; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/close) */ + /** + * The **`close()`** method of the AudioDecoder interface ends all pending work and releases system resources. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/close) + */ close(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/configure) */ + /** + * The **`configure()`** method of the AudioDecoder interface enqueues a control message to configure the audio decoder for decoding chunks. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/configure) + */ configure(config: AudioDecoderConfig): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/decode) */ + /** + * The **`decode()`** method of the AudioDecoder interface enqueues a control message to decode a given chunk of audio. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/decode) + */ decode(chunk: EncodedAudioChunk): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/flush) */ + /** + * The **`flush()`** method of the AudioDecoder interface returns a Promise that resolves once all pending messages in the queue have been completed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/flush) + */ flush(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/reset) */ + /** + * The **`reset()`** method of the AudioDecoder interface resets all states including configuration, control messages in the control message queue, and all pending callbacks. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/reset) + */ reset(): void; addEventListener(type: K, listener: (this: AudioDecoder, ev: AudioDecoderEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -3003,17 +3543,25 @@ interface AudioDecoder extends EventTarget { declare var AudioDecoder: { prototype: AudioDecoder; new(init: AudioDecoderInit): AudioDecoder; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/isConfigSupported_static) */ + /** + * The **`isConfigSupported()`** static method of the AudioDecoder interface checks if the given config is supported (that is, if AudioDecoder objects can be successfully configured with the given config). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDecoder/isConfigSupported_static) + */ isConfigSupported(config: AudioDecoderConfig): Promise; }; /** - * AudioDestinationNode has no output (as it is the output, no more AudioNode can be linked after it in the audio graph) and one input. The number of channels in the input must be between 0 and the maxChannelCount value or an exception is raised. + * The `AudioDestinationNode` interface represents the end destination of an audio graph in a given context — usually the speakers of your device. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDestinationNode) */ interface AudioDestinationNode extends AudioNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDestinationNode/maxChannelCount) */ + /** + * The `maxChannelCount` property of the AudioDestinationNode interface is an `unsigned long` defining the maximum amount of channels that the physical device can handle. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioDestinationNode/maxChannelCount) + */ readonly maxChannelCount: number; } @@ -3027,26 +3575,55 @@ interface AudioEncoderEventMap { } /** + * The **`AudioEncoder`** interface of the WebCodecs API encodes AudioData objects. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder) */ interface AudioEncoder extends EventTarget { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/encodeQueueSize) */ + /** + * The **`encodeQueueSize`** read-only property of the AudioEncoder interface returns the number of pending encode requests in the queue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/encodeQueueSize) + */ readonly encodeQueueSize: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/dequeue_event) */ ondequeue: ((this: AudioEncoder, ev: Event) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/state) */ + /** + * The **`state`** read-only property of the AudioEncoder interface returns the current state of the underlying codec. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/state) + */ readonly state: CodecState; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/close) */ + /** + * The **`close()`** method of the AudioEncoder interface ends all pending work and releases system resources. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/close) + */ close(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/configure) */ + /** + * The **`configure()`** method of the AudioEncoder interface enqueues a control message to configure the audio encoder for encoding chunks. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/configure) + */ configure(config: AudioEncoderConfig): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/encode) */ + /** + * The **`encode()`** method of the AudioEncoder interface enqueues a control message to encode a given AudioData object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/encode) + */ encode(data: AudioData): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/flush) */ + /** + * The **`flush()`** method of the AudioEncoder interface returns a Promise that resolves once all pending messages in the queue have been completed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/flush) + */ flush(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/reset) */ + /** + * The **`reset()`** method of the AudioEncoder interface resets all states including configuration, control messages in the control message queue, and all pending callbacks. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/reset) + */ reset(): void; addEventListener(type: K, listener: (this: AudioEncoder, ev: AudioEncoderEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -3057,41 +3634,83 @@ interface AudioEncoder extends EventTarget { declare var AudioEncoder: { prototype: AudioEncoder; new(init: AudioEncoderInit): AudioEncoder; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/isConfigSupported_static) */ + /** + * The **`isConfigSupported()`** static method of the AudioEncoder interface checks if the given config is supported (that is, if AudioEncoder objects can be successfully configured with the given config). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioEncoder/isConfigSupported_static) + */ isConfigSupported(config: AudioEncoderConfig): Promise; }; /** - * The position and orientation of the unique person listening to the audio scene, and is used in audio spatialization. All PannerNodes spatialize in relation to the AudioListener stored in the BaseAudioContext.listener attribute. + * The `AudioListener` interface represents the position and orientation of the unique person listening to the audio scene, and is used in audio spatialization. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener) */ interface AudioListener { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/forwardX) */ + /** + * The `forwardX` read-only property of the AudioListener interface is an AudioParam representing the x value of the direction vector defining the forward direction the listener is pointing in. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/forwardX) + */ readonly forwardX: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/forwardY) */ + /** + * The `forwardY` read-only property of the AudioListener interface is an AudioParam representing the y value of the direction vector defining the forward direction the listener is pointing in. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/forwardY) + */ readonly forwardY: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/forwardZ) */ + /** + * The `forwardZ` read-only property of the AudioListener interface is an AudioParam representing the z value of the direction vector defining the forward direction the listener is pointing in. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/forwardZ) + */ readonly forwardZ: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/positionX) */ + /** + * The `positionX` read-only property of the AudioListener interface is an AudioParam representing the x position of the listener in 3D cartesian space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/positionX) + */ readonly positionX: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/positionY) */ + /** + * The `positionY` read-only property of the AudioListener interface is an AudioParam representing the y position of the listener in 3D cartesian space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/positionY) + */ readonly positionY: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/positionZ) */ + /** + * The `positionZ` read-only property of the AudioListener interface is an AudioParam representing the z position of the listener in 3D cartesian space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/positionZ) + */ readonly positionZ: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/upX) */ + /** + * The `upX` read-only property of the AudioListener interface is an AudioParam representing the x value of the direction vector defining the up direction the listener is pointing in. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/upX) + */ readonly upX: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/upY) */ + /** + * The `upY` read-only property of the AudioListener interface is an AudioParam representing the y value of the direction vector defining the up direction the listener is pointing in. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/upY) + */ readonly upY: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/upZ) */ + /** + * The `upZ` read-only property of the AudioListener interface is an AudioParam representing the z value of the direction vector defining the up direction the listener is pointing in. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/upZ) + */ readonly upZ: AudioParam; /** + * The `setOrientation()` method of the AudioListener interface defines the orientation of the listener. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/setOrientation) */ setOrientation(x: number, y: number, z: number, xUp: number, yUp: number, zUp: number): void; /** + * The `setPosition()` method of the AudioListener Interface defines the position of the listener. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioListener/setPosition) @@ -3105,27 +3724,59 @@ declare var AudioListener: { }; /** - * A generic interface for representing an audio processing module. Examples include: + * The **`AudioNode`** interface is a generic interface for representing an audio processing module. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode) */ interface AudioNode extends EventTarget { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/channelCount) */ + /** + * The **`channelCount`** property of the AudioNode interface represents an integer used to determine how many channels are used when up-mixing and down-mixing connections to any inputs to the node. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/channelCount) + */ channelCount: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/channelCountMode) */ + /** + * The `channelCountMode` property of the AudioNode interface represents an enumerated value describing the way channels must be matched between the node's inputs and outputs. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/channelCountMode) + */ channelCountMode: ChannelCountMode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/channelInterpretation) */ + /** + * The **`channelInterpretation`** property of the AudioNode interface represents an enumerated value describing how input channels are mapped to output channels when the number of inputs/outputs is different. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/channelInterpretation) + */ channelInterpretation: ChannelInterpretation; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/context) */ + /** + * The read-only `context` property of the the node is participating in. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/context) + */ readonly context: BaseAudioContext; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/numberOfInputs) */ + /** + * The `numberOfInputs` property of the AudioNode interface returns the number of inputs feeding the node. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/numberOfInputs) + */ readonly numberOfInputs: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/numberOfOutputs) */ + /** + * The `numberOfOutputs` property of the AudioNode interface returns the number of outputs coming out of the node. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/numberOfOutputs) + */ readonly numberOfOutputs: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/connect) */ + /** + * The `connect()` method of the AudioNode interface lets you connect one of the node's outputs to a target, which may be either another `AudioNode` (thereby directing the sound data to the specified node) or an change the value of that parameter over time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/connect) + */ connect(destinationNode: AudioNode, output?: number, input?: number): AudioNode; connect(destinationParam: AudioParam, output?: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/disconnect) */ + /** + * The **`disconnect()`** method of the AudioNode interface lets you disconnect one or more nodes from the node on which the method is called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioNode/disconnect) + */ disconnect(): void; disconnect(output: number): void; disconnect(destinationNode: AudioNode): void; @@ -3141,33 +3792,77 @@ declare var AudioNode: { }; /** - * The Web Audio API's AudioParam interface represents an audio-related parameter, usually a parameter of an AudioNode (such as GainNode.gain). + * The Web Audio API's `AudioParam` interface represents an audio-related parameter, usually a parameter of an AudioNode (such as GainNode.gain). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam) */ interface AudioParam { automationRate: AutomationRate; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/defaultValue) */ + /** + * The **`defaultValue`** read-only property of the AudioParam interface represents the initial value of the attributes as defined by the specific AudioNode creating the `AudioParam`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/defaultValue) + */ readonly defaultValue: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/maxValue) */ + /** + * The **`maxValue`** read-only property of the AudioParam interface represents the maximum possible value for the parameter's nominal (effective) range. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/maxValue) + */ readonly maxValue: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/minValue) */ + /** + * The **`minValue`** read-only property of the AudioParam interface represents the minimum possible value for the parameter's nominal (effective) range. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/minValue) + */ readonly minValue: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/value) */ + /** + * The **`value`** property of the AudioParam interface gets or sets the value of this `AudioParam` at the current time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/value) + */ value: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/cancelAndHoldAtTime) */ + /** + * The **`cancelAndHoldAtTime()`** method of the `AudioParam` but holds its value at a given time until further changes are made using other methods. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/cancelAndHoldAtTime) + */ cancelAndHoldAtTime(cancelTime: number): AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/cancelScheduledValues) */ + /** + * The `cancelScheduledValues()` method of the AudioParam Interface cancels all scheduled future changes to the `AudioParam`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/cancelScheduledValues) + */ cancelScheduledValues(cancelTime: number): AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/exponentialRampToValueAtTime) */ + /** + * The **`exponentialRampToValueAtTime()`** method of the AudioParam Interface schedules a gradual exponential change in the value of the AudioParam. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/exponentialRampToValueAtTime) + */ exponentialRampToValueAtTime(value: number, endTime: number): AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/linearRampToValueAtTime) */ + /** + * The `linearRampToValueAtTime()` method of the AudioParam Interface schedules a gradual linear change in the value of the `AudioParam`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/linearRampToValueAtTime) + */ linearRampToValueAtTime(value: number, endTime: number): AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/setTargetAtTime) */ + /** + * The `setTargetAtTime()` method of the `AudioParam` value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/setTargetAtTime) + */ setTargetAtTime(target: number, startTime: number, timeConstant: number): AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/setValueAtTime) */ + /** + * The `setValueAtTime()` method of the `AudioParam` value at a precise time, as measured against ```js-nolint setValueAtTime(value, startTime) ``` - `value` - : A floating point number representing the value the AudioParam will change to at the given time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/setValueAtTime) + */ setValueAtTime(value: number, startTime: number): AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/setValueCurveAtTime) */ + /** + * The **`setValueCurveAtTime()`** method of the following a curve defined by a list of values. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParam/setValueCurveAtTime) + */ setValueCurveAtTime(values: number[] | Float32Array, startTime: number, duration: number): AudioParam; } @@ -3176,7 +3871,11 @@ declare var AudioParam: { new(): AudioParam; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParamMap) */ +/** + * The **`AudioParamMap`** interface of the Web Audio API represents an iterable and read-only set of multiple audio parameters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioParamMap) + */ interface AudioParamMap { forEach(callbackfn: (value: AudioParam, key: string, parent: AudioParamMap) => void, thisArg?: any): void; } @@ -3187,25 +3886,28 @@ declare var AudioParamMap: { }; /** - * The Web Audio API events that occur when a ScriptProcessorNode input buffer is ready to be processed. + * The `AudioProcessingEvent` interface of the Web Audio API represents events that occur when a ScriptProcessorNode input buffer is ready to be processed. * @deprecated As of the August 29 2014 Web Audio API spec publication, this feature has been marked as deprecated, and is soon to be replaced by AudioWorklet. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioProcessingEvent) */ interface AudioProcessingEvent extends Event { /** + * The **`inputBuffer`** read-only property of the AudioProcessingEvent interface represents the input buffer of an audio processing event. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioProcessingEvent/inputBuffer) */ readonly inputBuffer: AudioBuffer; /** + * The **`outputBuffer`** read-only property of the AudioProcessingEvent interface represents the output buffer of an audio processing event. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioProcessingEvent/outputBuffer) */ readonly outputBuffer: AudioBuffer; /** + * The **`playbackTime`** read-only property of the AudioProcessingEvent interface represents the time when the audio will be played. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioProcessingEvent/playbackTime) @@ -3223,13 +3925,25 @@ interface AudioScheduledSourceNodeEventMap { "ended": Event; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioScheduledSourceNode) */ +/** + * The `AudioScheduledSourceNode` interface—part of the Web Audio API—is a parent interface for several types of audio source node interfaces which share the ability to be started and stopped, optionally at specified times. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioScheduledSourceNode) + */ interface AudioScheduledSourceNode extends AudioNode { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioScheduledSourceNode/ended_event) */ onended: ((this: AudioScheduledSourceNode, ev: Event) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioScheduledSourceNode/start) */ + /** + * The `start()` method on AudioScheduledSourceNode schedules a sound to begin playback at the specified time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioScheduledSourceNode/start) + */ start(when?: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioScheduledSourceNode/stop) */ + /** + * The `stop()` method on AudioScheduledSourceNode schedules a sound to cease playback at the specified time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioScheduledSourceNode/stop) + */ stop(when?: number): void; addEventListener(type: K, listener: (this: AudioScheduledSourceNode, ev: AudioScheduledSourceNodeEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -3243,6 +3957,7 @@ declare var AudioScheduledSourceNode: { }; /** + * The **`AudioWorklet`** interface of the Web Audio API is used to supply custom audio processing scripts that execute in a separate thread to provide very low latency audio processing. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioWorklet) @@ -3260,6 +3975,7 @@ interface AudioWorkletNodeEventMap { } /** + * The **`AudioWorkletNode`** interface of the Web Audio API represents a base class for a user-defined AudioNode, which can be connected to an audio routing graph along with other nodes. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioWorkletNode) @@ -3267,9 +3983,17 @@ interface AudioWorkletNodeEventMap { interface AudioWorkletNode extends AudioNode { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioWorkletNode/processorerror_event) */ onprocessorerror: ((this: AudioWorkletNode, ev: ErrorEvent) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioWorkletNode/parameters) */ + /** + * The read-only **`parameters`** property of the underlying AudioWorkletProcessor according to its getter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioWorkletNode/parameters) + */ readonly parameters: AudioParamMap; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioWorkletNode/port) */ + /** + * The read-only **`port`** property of the associated AudioWorkletProcessor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AudioWorkletNode/port) + */ readonly port: MessagePort; addEventListener(type: K, listener: (this: AudioWorkletNode, ev: AudioWorkletNodeEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -3283,17 +4007,30 @@ declare var AudioWorkletNode: { }; /** + * The **`AuthenticatorAssertionResponse`** interface of the Web Authentication API contains a digital signature from the private key of a particular WebAuthn credential. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAssertionResponse) */ interface AuthenticatorAssertionResponse extends AuthenticatorResponse { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAssertionResponse/authenticatorData) */ + /** + * The **`authenticatorData`** property of the AuthenticatorAssertionResponse interface returns an ArrayBuffer containing information from the authenticator such as the Relying Party ID Hash (rpIdHash), a signature counter, test of user presence, user verification flags, and any extensions processed by the authenticator. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAssertionResponse/authenticatorData) + */ readonly authenticatorData: ArrayBuffer; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAssertionResponse/signature) */ - readonly signature: ArrayBuffer; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAssertionResponse/userHandle) */ - readonly userHandle: ArrayBuffer | null; + /** + * The **`signature`** read-only property of the object which is the signature of the authenticator for both the client data (AuthenticatorResponse.clientDataJSON). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAssertionResponse/signature) + */ + readonly signature: ArrayBuffer; + /** + * The **`userHandle`** read-only property of the AuthenticatorAssertionResponse interface is an ArrayBuffer object providing an opaque identifier for the given user. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAssertionResponse/userHandle) + */ + readonly userHandle: ArrayBuffer | null; } declare var AuthenticatorAssertionResponse: { @@ -3302,20 +4039,41 @@ declare var AuthenticatorAssertionResponse: { }; /** + * The **`AuthenticatorAttestationResponse`** interface of the Web Authentication API is the result of a WebAuthn credential registration. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse) */ interface AuthenticatorAttestationResponse extends AuthenticatorResponse { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/attestationObject) */ + /** + * The **`attestationObject`** property of the entire `attestationObject` with a private key that is stored in the authenticator when it is manufactured. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/attestationObject) + */ readonly attestationObject: ArrayBuffer; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getAuthenticatorData) */ + /** + * The **`getAuthenticatorData()`** method of the AuthenticatorAttestationResponse interface returns an ArrayBuffer containing the authenticator data contained within the AuthenticatorAttestationResponse.attestationObject property. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getAuthenticatorData) + */ getAuthenticatorData(): ArrayBuffer; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getPublicKey) */ + /** + * The **`getPublicKey()`** method of the AuthenticatorAttestationResponse interface returns an ArrayBuffer containing the DER `SubjectPublicKeyInfo` of the new credential (see Subject Public Key Info), or `null` if this is not available. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getPublicKey) + */ getPublicKey(): ArrayBuffer | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getPublicKeyAlgorithm) */ + /** + * The **`getPublicKeyAlgorithm()`** method of the AuthenticatorAttestationResponse interface returns a number that is equal to a COSE Algorithm Identifier, representing the cryptographic algorithm used for the new credential. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getPublicKeyAlgorithm) + */ getPublicKeyAlgorithm(): COSEAlgorithmIdentifier; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getTransports) */ + /** + * The **`getTransports()`** method of the AuthenticatorAttestationResponse interface returns an array of strings describing the different transports which may be used by the authenticator. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorAttestationResponse/getTransports) + */ getTransports(): string[]; } @@ -3325,12 +4083,17 @@ declare var AuthenticatorAttestationResponse: { }; /** + * The **`AuthenticatorResponse`** interface of the Web Authentication API is the base interface for interfaces that provide a cryptographic root of trust for a key pair. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorResponse) */ interface AuthenticatorResponse { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorResponse/clientDataJSON) */ + /** + * The **`clientDataJSON`** property of the AuthenticatorResponse interface stores a JSON string in an An ArrayBuffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AuthenticatorResponse/clientDataJSON) + */ readonly clientDataJSON: ArrayBuffer; } @@ -3339,9 +4102,17 @@ declare var AuthenticatorResponse: { new(): AuthenticatorResponse; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BarProp) */ +/** + * The **`BarProp`** interface of the Document Object Model represents the web browser user interface elements that are exposed to scripts in web pages. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BarProp) + */ interface BarProp { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BarProp/visible) */ + /** + * The **`visible`** read-only property of the BarProp interface returns `true` if the user interface element it represents is visible. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BarProp/visible) + */ readonly visible: boolean; } @@ -3354,67 +4125,165 @@ interface BaseAudioContextEventMap { "statechange": Event; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext) */ +/** + * The `BaseAudioContext` interface of the Web Audio API acts as a base definition for online and offline audio-processing graphs, as represented by AudioContext and OfflineAudioContext respectively. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext) + */ interface BaseAudioContext extends EventTarget { /** + * The `audioWorklet` read-only property of the processing. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/audioWorklet) */ readonly audioWorklet: AudioWorklet; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/currentTime) */ + /** + * The `currentTime` read-only property of the BaseAudioContext interface returns a double representing an ever-increasing hardware timestamp in seconds that can be used for scheduling audio playback, visualizing timelines, etc. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/currentTime) + */ readonly currentTime: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/destination) */ + /** + * The `destination` property of the BaseAudioContext interface returns an AudioDestinationNode representing the final destination of all audio in the context. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/destination) + */ readonly destination: AudioDestinationNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/listener) */ + /** + * The `listener` property of the BaseAudioContext interface returns an AudioListener object that can then be used for implementing 3D audio spatialization. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/listener) + */ readonly listener: AudioListener; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/statechange_event) */ onstatechange: ((this: BaseAudioContext, ev: Event) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/sampleRate) */ + /** + * The `sampleRate` property of the BaseAudioContext interface returns a floating point number representing the sample rate, in samples per second, used by all nodes in this audio context. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/sampleRate) + */ readonly sampleRate: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/state) */ + /** + * The `state` read-only property of the BaseAudioContext interface returns the current state of the `AudioContext`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/state) + */ readonly state: AudioContextState; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createAnalyser) */ + /** + * The `createAnalyser()` method of the can be used to expose audio time and frequency data and create data visualizations. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createAnalyser) + */ createAnalyser(): AnalyserNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createBiquadFilter) */ + /** + * The `createBiquadFilter()` method of the BaseAudioContext interface creates a BiquadFilterNode, which represents a second order filter configurable as several different common filter types. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createBiquadFilter) + */ createBiquadFilter(): BiquadFilterNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createBuffer) */ + /** + * The `createBuffer()` method of the BaseAudioContext Interface is used to create a new, empty AudioBuffer object, which can then be populated by data, and played via an AudioBufferSourceNode. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createBuffer) + */ createBuffer(numberOfChannels: number, length: number, sampleRate: number): AudioBuffer; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createBufferSource) */ + /** + * The `createBufferSource()` method of the BaseAudioContext Interface is used to create a new AudioBufferSourceNode, which can be used to play audio data contained within an AudioBuffer object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createBufferSource) + */ createBufferSource(): AudioBufferSourceNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createChannelMerger) */ + /** + * The `createChannelMerger()` method of the BaseAudioContext interface creates a ChannelMergerNode, which combines channels from multiple audio streams into a single audio stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createChannelMerger) + */ createChannelMerger(numberOfInputs?: number): ChannelMergerNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createChannelSplitter) */ + /** + * The `createChannelSplitter()` method of the BaseAudioContext Interface is used to create a ChannelSplitterNode, which is used to access the individual channels of an audio stream and process them separately. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createChannelSplitter) + */ createChannelSplitter(numberOfOutputs?: number): ChannelSplitterNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createConstantSource) */ + /** + * The **`createConstantSource()`** property of the BaseAudioContext interface creates a outputs a monaural (one-channel) sound signal whose samples all have the same value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createConstantSource) + */ createConstantSource(): ConstantSourceNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createConvolver) */ + /** + * The `createConvolver()` method of the BaseAudioContext interface creates a ConvolverNode, which is commonly used to apply reverb effects to your audio. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createConvolver) + */ createConvolver(): ConvolverNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createDelay) */ + /** + * The `createDelay()` method of the which is used to delay the incoming audio signal by a certain amount of time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createDelay) + */ createDelay(maxDelayTime?: number): DelayNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createDynamicsCompressor) */ + /** + * The `createDynamicsCompressor()` method of the BaseAudioContext Interface is used to create a DynamicsCompressorNode, which can be used to apply compression to an audio signal. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createDynamicsCompressor) + */ createDynamicsCompressor(): DynamicsCompressorNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createGain) */ + /** + * The `createGain()` method of the BaseAudioContext interface creates a GainNode, which can be used to control the overall gain (or volume) of the audio graph. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createGain) + */ createGain(): GainNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createIIRFilter) */ + /** + * The **`createIIRFilter()`** method of the BaseAudioContext interface creates an IIRFilterNode, which represents a general **infinite impulse response** (IIR) filter which can be configured to serve as various types of filter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createIIRFilter) + */ createIIRFilter(feedforward: number[], feedback: number[]): IIRFilterNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createOscillator) */ + /** + * The `createOscillator()` method of the BaseAudioContext interface creates an OscillatorNode, a source representing a periodic waveform. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createOscillator) + */ createOscillator(): OscillatorNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createPanner) */ + /** + * The `createPanner()` method of the BaseAudioContext Interface is used to create a new PannerNode, which is used to spatialize an incoming audio stream in 3D space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createPanner) + */ createPanner(): PannerNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createPeriodicWave) */ + /** + * The `createPeriodicWave()` method of the BaseAudioContext interface is used to create a PeriodicWave. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createPeriodicWave) + */ createPeriodicWave(real: number[] | Float32Array, imag: number[] | Float32Array, constraints?: PeriodicWaveConstraints): PeriodicWave; /** + * The `createScriptProcessor()` method of the BaseAudioContext interface creates a ScriptProcessorNode used for direct audio processing. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createScriptProcessor) */ createScriptProcessor(bufferSize?: number, numberOfInputChannels?: number, numberOfOutputChannels?: number): ScriptProcessorNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createStereoPanner) */ + /** + * The `createStereoPanner()` method of the BaseAudioContext interface creates a StereoPannerNode, which can be used to apply stereo panning to an audio source. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createStereoPanner) + */ createStereoPanner(): StereoPannerNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createWaveShaper) */ + /** + * The `createWaveShaper()` method of the BaseAudioContext interface creates a WaveShaperNode, which represents a non-linear distortion. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/createWaveShaper) + */ createWaveShaper(): WaveShaperNode; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/decodeAudioData) */ + /** + * The `decodeAudioData()` method of the BaseAudioContext Interface is used to asynchronously decode audio file data contained in an rate, then passed to a callback or promise. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BaseAudioContext/decodeAudioData) + */ decodeAudioData(audioData: ArrayBuffer, successCallback?: DecodeSuccessCallback | null, errorCallback?: DecodeErrorCallback | null): Promise; addEventListener(type: K, listener: (this: BaseAudioContext, ev: BaseAudioContextEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -3428,12 +4297,13 @@ declare var BaseAudioContext: { }; /** - * The beforeunload event is fired when the window, the document and its resources are about to be unloaded. + * The **`BeforeUnloadEvent`** interface represents the event object for the Window/beforeunload_event event, which is fired when the current window, contained document, and associated resources are about to be unloaded. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BeforeUnloadEvent) */ interface BeforeUnloadEvent extends Event { /** + * The **`returnValue`** property of the `returnValue` is initialized to an empty string (`''`) value. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BeforeUnloadEvent/returnValue) @@ -3447,23 +4317,47 @@ declare var BeforeUnloadEvent: { }; /** - * A simple low-order filter, and is created using the AudioContext.createBiquadFilter() method. It is an AudioNode that can represent different kinds of filters, tone control devices, and graphic equalizers. + * The `BiquadFilterNode` interface represents a simple low-order filter, and is created using the BaseAudioContext/createBiquadFilter method. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode) */ interface BiquadFilterNode extends AudioNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/Q) */ + /** + * The `Q` property of the BiquadFilterNode interface is an a-rate AudioParam, a double representing a Q factor, or _quality factor_. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/Q) + */ readonly Q: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/detune) */ + /** + * The `detune` property of the BiquadFilterNode interface is an a-rate AudioParam representing detuning of the frequency in cents. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/detune) + */ readonly detune: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/frequency) */ + /** + * The `frequency` property of the BiquadFilterNode interface is an a-rate AudioParam — a double representing a frequency in the current filtering algorithm measured in hertz (Hz). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/frequency) + */ readonly frequency: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/gain) */ + /** + * The `gain` property of the BiquadFilterNode interface is an a-rate AudioParam — a double representing the gain used in the current filtering algorithm. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/gain) + */ readonly gain: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/type) */ + /** + * The `type` property of the BiquadFilterNode interface is a string (enum) value defining the kind of filtering algorithm the node is implementing. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/type) + */ type: BiquadFilterType; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/getFrequencyResponse) */ - getFrequencyResponse(frequencyHz: Float32Array, magResponse: Float32Array, phaseResponse: Float32Array): void; + /** + * The `getFrequencyResponse()` method of the BiquadFilterNode interface takes the current filtering algorithm's settings and calculates the frequency response for frequencies specified in a specified array of frequencies. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BiquadFilterNode/getFrequencyResponse) + */ + getFrequencyResponse(frequencyHz: Float32Array, magResponse: Float32Array, phaseResponse: Float32Array): void; } declare var BiquadFilterNode: { @@ -3472,24 +4366,52 @@ declare var BiquadFilterNode: { }; /** - * A file-like object of immutable, raw data. Blobs represent data that isn't necessarily in a JavaScript-native format. The File interface is based on Blob, inheriting blob functionality and expanding it to support files on the user's system. + * The **`Blob`** interface represents a blob, which is a file-like object of immutable, raw data; they can be read as text or binary data, or converted into a ReadableStream so its methods can be used for processing the data. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob) */ interface Blob { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size) */ + /** + * The **`size`** read-only property of the Blob interface returns the size of the Blob or File in bytes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/size) + */ readonly size: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type) */ + /** + * The **`type`** read-only property of the Blob interface returns the MIME type of the file. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/type) + */ readonly type: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/arrayBuffer) */ + /** + * The **`arrayBuffer()`** method of the Blob interface returns a Promise that resolves with the contents of the blob as binary data contained in an ArrayBuffer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/arrayBuffer) + */ arrayBuffer(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/bytes) */ - bytes(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice) */ + /** + * The **`bytes()`** method of the Blob interface returns a Promise that resolves with a Uint8Array containing the contents of the blob as an array of bytes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/bytes) + */ + bytes(): Promise>; + /** + * The **`slice()`** method of the Blob interface creates and returns a new `Blob` object which contains data from a subset of the blob on which it's called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/slice) + */ slice(start?: number, end?: number, contentType?: string): Blob; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/stream) */ - stream(): ReadableStream; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text) */ + /** + * The **`stream()`** method of the Blob interface returns a ReadableStream which upon reading returns the data contained within the `Blob`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/stream) + */ + stream(): ReadableStream>; + /** + * The **`text()`** method of the string containing the contents of the blob, interpreted as UTF-8. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Blob/text) + */ text(): Promise; } @@ -3498,11 +4420,23 @@ declare var Blob: { new(blobParts?: BlobPart[], options?: BlobPropertyBag): Blob; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BlobEvent) */ +/** + * The **`BlobEvent`** interface of the MediaStream Recording API represents events associated with a Blob. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BlobEvent) + */ interface BlobEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BlobEvent/data) */ + /** + * The **`data`** read-only property of the BlobEvent interface represents a Blob associated with the event. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BlobEvent/data) + */ readonly data: Blob; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BlobEvent/timecode) */ + /** + * The **`timecode`** read-only property of the BlobEvent interface indicates the difference between the timestamp of the first chunk of data, and the timestamp of the first chunk in the first `BlobEvent` produced by this recorder. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BlobEvent/timecode) + */ readonly timecode: DOMHighResTimeStamp; } @@ -3513,7 +4447,7 @@ declare var BlobEvent: { interface Body { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/body) */ - readonly body: ReadableStream | null; + readonly body: ReadableStream> | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bodyUsed) */ readonly bodyUsed: boolean; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/arrayBuffer) */ @@ -3521,7 +4455,7 @@ interface Body { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/blob) */ blob(): Promise; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/bytes) */ - bytes(): Promise; + bytes(): Promise>; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/formData) */ formData(): Promise; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Request/json) */ @@ -3535,10 +4469,14 @@ interface BroadcastChannelEventMap { "messageerror": MessageEvent; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BroadcastChannel) */ +/** + * The **`BroadcastChannel`** interface represents a named channel that any browsing context of a given origin can subscribe to. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BroadcastChannel) + */ interface BroadcastChannel extends EventTarget { /** - * Returns the channel name (as passed to the constructor). + * The **`name`** read-only property of the BroadcastChannel interface returns a string, which uniquely identifies the given channel with its name. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BroadcastChannel/name) */ @@ -3548,13 +4486,13 @@ interface BroadcastChannel extends EventTarget { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/BroadcastChannel/messageerror_event) */ onmessageerror: ((this: BroadcastChannel, ev: MessageEvent) => any) | null; /** - * Closes the BroadcastChannel object, opening it up to garbage collection. + * The **`close()`** method of the BroadcastChannel interface terminates the connection to the underlying channel, allowing the object to be garbage collected. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BroadcastChannel/close) */ close(): void; /** - * Sends the given message to other BroadcastChannel objects set up for this channel. Messages can be structured objects, e.g. nested objects and arrays. + * The **`postMessage()`** method of the BroadcastChannel interface sends a message, which can be of any kind of Object, to each listener in any browsing context with the same origin. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/BroadcastChannel/postMessage) */ @@ -3571,12 +4509,16 @@ declare var BroadcastChannel: { }; /** - * This Streams API interface provides a built-in byte length queuing strategy that can be used when constructing streams. + * The **`ByteLengthQueuingStrategy`** interface of the Streams API provides a built-in byte length queuing strategy that can be used when constructing streams. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy) */ interface ByteLengthQueuingStrategy extends QueuingStrategy { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy/highWaterMark) */ + /** + * The read-only **`ByteLengthQueuingStrategy.highWaterMark`** property returns the total number of bytes that can be contained in the internal queue before backpressure is applied. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy/highWaterMark) + */ readonly highWaterMark: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ByteLengthQueuingStrategy/size) */ readonly size: QueuingStrategySize; @@ -3588,7 +4530,7 @@ declare var ByteLengthQueuingStrategy: { }; /** - * A CDATA section that can be used within XML to include extended portions of unescaped text. The symbols < and & don’t need escaping as they normally do when inside a CDATA section. + * The **`CDATASection`** interface represents a CDATA section that can be used within XML to include extended portions of unescaped text. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CDATASection) */ @@ -3600,9 +4542,102 @@ declare var CDATASection: { new(): CDATASection; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSAnimation) */ +/** + * The `CSPViolationReportBody` interface is an extension of the Reporting API that represents the body of a Content Security Policy (CSP) violation report. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody) + */ +interface CSPViolationReportBody extends ReportBody { + /** + * The **`blockedURL`** read-only property of the CSPViolationReportBody interface is a string value that represents the resource that was blocked because it violates a Content Security Policy (CSP). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/blockedURL) + */ + readonly blockedURL: string | null; + /** + * The **`columnNumber`** read-only property of the CSPViolationReportBody interface indicates the column number in the source file that triggered the Content Security Policy (CSP) violation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/columnNumber) + */ + readonly columnNumber: number | null; + /** + * The **`disposition`** read-only property of the CSPViolationReportBody interface indicates whether the user agent is configured to enforce Content Security Policy (CSP) violations or only report them. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/disposition) + */ + readonly disposition: SecurityPolicyViolationEventDisposition; + /** + * The **`documentURL`** read-only property of the CSPViolationReportBody interface is a string that represents the URL of the document or worker that violated the Content Security Policy (CSP). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/documentURL) + */ + readonly documentURL: string; + /** + * The **`effectiveDirective`** read-only property of the CSPViolationReportBody interface is a string that represents the effective Content Security Policy (CSP) directive that was violated. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/effectiveDirective) + */ + readonly effectiveDirective: string; + /** + * The **`lineNumber`** read-only property of the CSPViolationReportBody interface indicates the line number in the source file that triggered the Content Security Policy (CSP) violation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/lineNumber) + */ + readonly lineNumber: number | null; + /** + * The **`originalPolicy`** read-only property of the CSPViolationReportBody interface is a string that represents the Content Security Policy (CSP) whose enforcement uncovered the violation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/originalPolicy) + */ + readonly originalPolicy: string; + /** + * The **`referrer`** read-only property of the CSPViolationReportBody interface is a string that represents the URL of the referring page of the resource who's Content Security Policy (CSP) was violated. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/referrer) + */ + readonly referrer: string | null; + /** + * The **`sample`** read-only property of the CSPViolationReportBody interface is a string that contains a part of the resource that violated the Content Security Policy (CSP). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/sample) + */ + readonly sample: string | null; + /** + * The **`sourceFile`** read-only property of the CSPViolationReportBody interface indicates the URL of the source file that violated the Content Security Policy (CSP). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/sourceFile) + */ + readonly sourceFile: string | null; + /** + * The **`statusCode`** read-only property of the CSPViolationReportBody interface is a number representing the HTTP status code of the response to the request that triggered a Content Security Policy (CSP) violation (when loading a window or worker). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/statusCode) + */ + readonly statusCode: number; + /** + * The **`toJSON()`** method of the CSPViolationReportBody interface is a _serializer_, which returns a JSON representation of the `CSPViolationReportBody` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSPViolationReportBody/toJSON) + */ + toJSON(): any; +} + +declare var CSPViolationReportBody: { + prototype: CSPViolationReportBody; + new(): CSPViolationReportBody; +}; + +/** + * The **`CSSAnimation`** interface of the Web Animations API represents an Animation object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSAnimation) + */ interface CSSAnimation extends Animation { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSAnimation/animationName) */ + /** + * The **`animationName`** property of the specifies one or more keyframe at-rules which describe the animation applied to the element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSAnimation/animationName) + */ readonly animationName: string; addEventListener(type: K, listener: (this: CSSAnimation, ev: AnimationEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -3616,12 +4651,16 @@ declare var CSSAnimation: { }; /** - * A single condition CSS at-rule, which consists of a condition and a statement block. It is a child of CSSGroupingRule. + * An object implementing the **`CSSConditionRule`** interface represents a single condition CSS at-rule, which consists of a condition and a statement block. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSConditionRule) */ interface CSSConditionRule extends CSSGroupingRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSConditionRule/conditionText) */ + /** + * The read-only **`conditionText`** property of the CSSConditionRule interface returns or sets the text of the CSS rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSConditionRule/conditionText) + */ readonly conditionText: string; } @@ -3630,11 +4669,23 @@ declare var CSSConditionRule: { new(): CSSConditionRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSContainerRule) */ +/** + * The **`CSSContainerRule`** interface represents a single CSS @container rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSContainerRule) + */ interface CSSContainerRule extends CSSConditionRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSContainerRule/containerName) */ + /** + * The read-only **`containerName`** property of the CSSContainerRule interface represents the container name of the associated CSS @container at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSContainerRule/containerName) + */ readonly containerName: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSContainerRule/containerQuery) */ + /** + * The read-only **`containerQuery`** property of the CSSContainerRule interface returns a string representing the container conditions that are evaluated when the container changes size in order to determine if the styles in the associated @container are applied. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSContainerRule/containerQuery) + */ readonly containerQuery: string; } @@ -3643,30 +4694,78 @@ declare var CSSContainerRule: { new(): CSSContainerRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule) */ +/** + * The **`CSSCounterStyleRule`** interface represents an @counter-style at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule) + */ interface CSSCounterStyleRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/additiveSymbols) */ + /** + * The **`additiveSymbols`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/additive-symbols descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/additiveSymbols) + */ additiveSymbols: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/fallback) */ + /** + * The **`fallback`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/fallback descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/fallback) + */ fallback: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/name) */ + /** + * The **`name`** property of the CSSCounterStyleRule interface gets and sets the <custom-ident> defined as the `name` for the associated rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/name) + */ name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/negative) */ + /** + * The **`negative`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/negative descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/negative) + */ negative: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/pad) */ + /** + * The **`pad`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/pad descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/pad) + */ pad: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/prefix) */ + /** + * The **`prefix`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/prefix descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/prefix) + */ prefix: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/range) */ + /** + * The **`range`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/range descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/range) + */ range: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/speakAs) */ + /** + * The **`speakAs`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/speak-as descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/speakAs) + */ speakAs: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/suffix) */ + /** + * The **`suffix`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/suffix descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/suffix) + */ suffix: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/symbols) */ - symbols: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/system) */ - system: string; + /** + * The **`symbols`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/symbols descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/symbols) + */ + symbols: string; + /** + * The **`system`** property of the CSSCounterStyleRule interface gets and sets the value of the @counter-style/system descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSCounterStyleRule/system) + */ + system: string; } declare var CSSCounterStyleRule: { @@ -3674,9 +4773,17 @@ declare var CSSCounterStyleRule: { new(): CSSCounterStyleRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFaceRule) */ +/** + * The **`CSSFontFaceRule`** interface represents an @font-face at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFaceRule) + */ interface CSSFontFaceRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFaceRule/style) */ + /** + * The read-only **`style`** property of the CSSFontFaceRule interface returns the style information from the @font-face at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFaceRule/style) + */ get style(): CSSStyleDeclaration; set style(cssText: string); } @@ -3686,9 +4793,17 @@ declare var CSSFontFaceRule: { new(): CSSFontFaceRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFeatureValuesRule) */ +/** + * The **`CSSFontFeatureValuesRule`** interface represents an @font-feature-values at-rule, letting developers assign for each font face a common name to specify features indices to be used in font-variant-alternates. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFeatureValuesRule) + */ interface CSSFontFeatureValuesRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFeatureValuesRule/fontFamily) */ + /** + * The **`fontFamily`** property of the CSSConditionRule interface represents the name of the font family it applies to. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontFeatureValuesRule/fontFamily) + */ fontFamily: string; } @@ -3697,15 +4812,35 @@ declare var CSSFontFeatureValuesRule: { new(): CSSFontFeatureValuesRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule) */ +/** + * The **`CSSFontPaletteValuesRule`** interface represents an @font-palette-values at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule) + */ interface CSSFontPaletteValuesRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/basePalette) */ + /** + * The read-only **`basePalette`** property of the CSSFontPaletteValuesRule interface indicates the base palette associated with the rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/basePalette) + */ readonly basePalette: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/fontFamily) */ + /** + * The read-only **`fontFamily`** property of the CSSFontPaletteValuesRule interface lists the font families the rule can be applied to. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/fontFamily) + */ readonly fontFamily: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/name) */ + /** + * The read-only **`name`** property of the CSSFontPaletteValuesRule interface represents the name identifying the associated @font-palette-values at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/name) + */ readonly name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/overrideColors) */ + /** + * The read-only **`overrideColors`** property of the CSSFontPaletteValuesRule interface is a string containing a list of color index and color pair that are to be used instead. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSFontPaletteValuesRule/overrideColors) + */ readonly overrideColors: string; } @@ -3715,16 +4850,28 @@ declare var CSSFontPaletteValuesRule: { }; /** - * Any CSS at-rule that contains other rules nested within it. + * The **`CSSGroupingRule`** interface of the CSS Object Model represents any CSS at-rule that contains other rules nested within it. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSGroupingRule) */ interface CSSGroupingRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSGroupingRule/cssRules) */ + /** + * The **`cssRules`** property of the a collection of CSSRule objects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSGroupingRule/cssRules) + */ readonly cssRules: CSSRuleList; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSGroupingRule/deleteRule) */ + /** + * The **`deleteRule()`** method of the rules. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSGroupingRule/deleteRule) + */ deleteRule(index: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSGroupingRule/insertRule) */ + /** + * The **`insertRule()`** method of the ```js-nolint insertRule(rule) insertRule(rule, index) ``` - `rule` - : A string - `index` [MISSING: optional_inline] - : An optional index at which to insert the rule; defaults to 0. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSGroupingRule/insertRule) + */ insertRule(rule: string, index?: number): number; } @@ -3733,7 +4880,11 @@ declare var CSSGroupingRule: { new(): CSSGroupingRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImageValue) */ +/** + * The **`CSSImageValue`** interface of the CSS Typed Object Model API represents values for properties that take an image, for example background-image, list-style-image, or border-image-source. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImageValue) + */ interface CSSImageValue extends CSSStyleValue { } @@ -3742,18 +4893,42 @@ declare var CSSImageValue: { new(): CSSImageValue; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule) */ +/** + * The **`CSSImportRule`** interface represents an @import at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule) + */ interface CSSImportRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/href) */ + /** + * The read-only **`href`** property of the The resolved URL will be the `href` attribute of the associated stylesheet. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/href) + */ readonly href: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/layerName) */ + /** + * The read-only **`layerName`** property of the CSSImportRule interface returns the name of the cascade layer created by the @import at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/layerName) + */ readonly layerName: string | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/media) */ + /** + * The read-only **`media`** property of the containing the value of the `media` attribute of the associated stylesheet. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/media) + */ get media(): MediaList; set media(mediaText: string); - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/styleSheet) */ + /** + * The read-only **`styleSheet`** property of the in the form of a CSSStyleSheet object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/styleSheet) + */ readonly styleSheet: CSSStyleSheet | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/supportsText) */ + /** + * The read-only **`supportsText`** property of the CSSImportRule interface returns the supports condition specified by the @import at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSImportRule/supportsText) + */ readonly supportsText: string | null; } @@ -3763,14 +4938,22 @@ declare var CSSImportRule: { }; /** - * An object representing a set of style for a given keyframe. It corresponds to the contains of a single keyframe of a @keyframes at-rule. It implements the CSSRule interface with a type value of 8 (CSSRule.KEYFRAME_RULE). + * The **`CSSKeyframeRule`** interface describes an object representing a set of styles for a given keyframe. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframeRule) */ interface CSSKeyframeRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframeRule/keyText) */ + /** + * The **`keyText`** property of the CSSKeyframeRule interface represents the keyframe selector as a comma-separated list of percentage values. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframeRule/keyText) + */ keyText: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframeRule/style) */ + /** + * The read-only **`CSSKeyframeRule.style`** property is the CSSStyleDeclaration interface for the declaration block of the CSSKeyframeRule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframeRule/style) + */ get style(): CSSStyleDeclaration; set style(cssText: string); } @@ -3781,22 +4964,46 @@ declare var CSSKeyframeRule: { }; /** - * An object representing a complete set of keyframes for a CSS animation. It corresponds to the contains of a whole @keyframes at-rule. It implements the CSSRule interface with a type value of 7 (CSSRule.KEYFRAMES_RULE). + * The **`CSSKeyframesRule`** interface describes an object representing a complete set of keyframes for a CSS animation. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule) */ interface CSSKeyframesRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/cssRules) */ + /** + * The read-only **`cssRules`** property of the CSSKeyframeRule interface returns a CSSRuleList containing the rules in the keyframes at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/cssRules) + */ readonly cssRules: CSSRuleList; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/length) */ + /** + * The read-only **`length`** property of the CSSKeyframeRule interface returns the number of CSSKeyframeRule objects in its list. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/length) + */ readonly length: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/name) */ + /** + * The **`name`** property of the CSSKeyframeRule interface gets and sets the name of the animation as used by the animation-name property. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/name) + */ name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/appendRule) */ + /** + * The **`appendRule()`** method of the CSSKeyframeRule interface appends a CSSKeyFrameRule to the end of the rules. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/appendRule) + */ appendRule(rule: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/deleteRule) */ + /** + * The **`deleteRule()`** method of the CSSKeyframeRule interface deletes the CSSKeyFrameRule that matches the specified keyframe selector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/deleteRule) + */ deleteRule(select: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/findRule) */ + /** + * The **`findRule()`** method of the CSSKeyframeRule interface finds the CSSKeyFrameRule that matches the specified keyframe selector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeyframesRule/findRule) + */ findRule(select: string): CSSKeyframeRule | null; [index: number]: CSSKeyframeRule; } @@ -3806,9 +5013,17 @@ declare var CSSKeyframesRule: { new(): CSSKeyframesRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeywordValue) */ +/** + * The **`CSSKeywordValue`** interface of the CSS Typed Object Model API creates an object to represent CSS keywords and other identifiers. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeywordValue) + */ interface CSSKeywordValue extends CSSStyleValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeywordValue/value) */ + /** + * The **`value`** property of the `CSSKeywordValue`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSKeywordValue/value) + */ value: string; } @@ -3817,9 +5032,17 @@ declare var CSSKeywordValue: { new(value: string): CSSKeywordValue; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerBlockRule) */ +/** + * The **`CSSLayerBlockRule`** represents a @layer block rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerBlockRule) + */ interface CSSLayerBlockRule extends CSSGroupingRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerBlockRule/name) */ + /** + * The read-only **`name`** property of the CSSLayerBlockRule interface represents the name of the associated cascade layer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerBlockRule/name) + */ readonly name: string; } @@ -3828,9 +5051,17 @@ declare var CSSLayerBlockRule: { new(): CSSLayerBlockRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerStatementRule) */ +/** + * The **`CSSLayerStatementRule`** represents a @layer statement rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerStatementRule) + */ interface CSSLayerStatementRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerStatementRule/nameList) */ + /** + * The read-only **`nameList`** property of the CSSLayerStatementRule interface return the list of associated cascade layer names. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSLayerStatementRule/nameList) + */ readonly nameList: ReadonlyArray; } @@ -3850,9 +5081,17 @@ declare var CSSMathClamp: { new(lower: CSSNumberish, value: CSSNumberish, upper: CSSNumberish): CSSMathClamp; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathInvert) */ +/** + * The **`CSSMathInvert`** interface of the CSS Typed Object Model API represents a CSS calc used as `calc(1 / )`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathInvert) + */ interface CSSMathInvert extends CSSMathValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathInvert/value) */ + /** + * The CSSMathInvert.value read-only property of the A CSSNumericValue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathInvert/value) + */ readonly value: CSSNumericValue; } @@ -3861,9 +5100,17 @@ declare var CSSMathInvert: { new(arg: CSSNumberish): CSSMathInvert; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMax) */ +/** + * The **`CSSMathMax`** interface of the CSS Typed Object Model API represents the CSS max function. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMax) + */ interface CSSMathMax extends CSSMathValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMax/values) */ + /** + * The CSSMathMax.values read-only property of the which contains one or more CSSNumericValue objects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMax/values) + */ readonly values: CSSNumericArray; } @@ -3872,9 +5119,17 @@ declare var CSSMathMax: { new(...args: CSSNumberish[]): CSSMathMax; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMin) */ +/** + * The **`CSSMathMin`** interface of the CSS Typed Object Model API represents the CSS min function. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMin) + */ interface CSSMathMin extends CSSMathValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMin/values) */ + /** + * The CSSMathMin.values read-only property of the which contains one or more CSSNumericValue objects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathMin/values) + */ readonly values: CSSNumericArray; } @@ -3883,9 +5138,17 @@ declare var CSSMathMin: { new(...args: CSSNumberish[]): CSSMathMin; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathNegate) */ +/** + * The **`CSSMathNegate`** interface of the CSS Typed Object Model API negates the value passed into it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathNegate) + */ interface CSSMathNegate extends CSSMathValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathNegate/value) */ + /** + * The CSSMathNegate.value read-only property of the A CSSNumericValue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathNegate/value) + */ readonly value: CSSNumericValue; } @@ -3894,9 +5157,17 @@ declare var CSSMathNegate: { new(arg: CSSNumberish): CSSMathNegate; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathProduct) */ +/** + * The **`CSSMathProduct`** interface of the CSS Typed Object Model API represents the result obtained by calling CSSNumericValue.add, CSSNumericValue.sub, or CSSNumericValue.toSum on CSSNumericValue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathProduct) + */ interface CSSMathProduct extends CSSMathValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathProduct/values) */ + /** + * The **`CSSMathProduct.values`** read-only property of the CSSMathProduct interface returns a A CSSNumericArray. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathProduct/values) + */ readonly values: CSSNumericArray; } @@ -3905,9 +5176,17 @@ declare var CSSMathProduct: { new(...args: CSSNumberish[]): CSSMathProduct; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathSum) */ +/** + * The **`CSSMathSum`** interface of the CSS Typed Object Model API represents the result obtained by calling CSSNumericValue.add, CSSNumericValue.sub, or CSSNumericValue.toSum on CSSNumericValue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathSum) + */ interface CSSMathSum extends CSSMathValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathSum/values) */ + /** + * The **`CSSMathSum.values`** read-only property of the CSSMathSum interface returns a CSSNumericArray object which contains one or more CSSNumericValue objects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathSum/values) + */ readonly values: CSSNumericArray; } @@ -3916,9 +5195,17 @@ declare var CSSMathSum: { new(...args: CSSNumberish[]): CSSMathSum; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathValue) */ +/** + * The **`CSSMathValue`** interface of the CSS Typed Object Model API a base class for classes representing complex numeric values. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathValue) + */ interface CSSMathValue extends CSSNumericValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathValue/operator) */ + /** + * The **`CSSMathValue.operator`** read-only property of the CSSMathValue interface indicates the operator that the current subtype represents. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMathValue/operator) + */ readonly operator: CSSMathOperator; } @@ -3927,9 +5214,17 @@ declare var CSSMathValue: { new(): CSSMathValue; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMatrixComponent) */ +/** + * The **`CSSMatrixComponent`** interface of the CSS Typed Object Model API represents the matrix() and matrix3d() values of the individual transform property in CSS. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMatrixComponent) + */ interface CSSMatrixComponent extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMatrixComponent/matrix) */ + /** + * The **`matrix`** property of the See the matrix() and matrix3d() pages for examples. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMatrixComponent/matrix) + */ matrix: DOMMatrix; } @@ -3939,12 +5234,16 @@ declare var CSSMatrixComponent: { }; /** - * A single CSS @media rule. It implements the CSSConditionRule interface, and therefore the CSSGroupingRule and the CSSRule interface with a type value of 4 (CSSRule.MEDIA_RULE). + * The **`CSSMediaRule`** interface represents a single CSS @media rule. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMediaRule) */ interface CSSMediaRule extends CSSConditionRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMediaRule/media) */ + /** + * The read-only **`media`** property of the destination medium for style information. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSMediaRule/media) + */ get media(): MediaList; set media(mediaText: string); } @@ -3955,14 +5254,22 @@ declare var CSSMediaRule: { }; /** - * An object representing a single CSS @namespace at-rule. It implements the CSSRule interface, with a type value of 10 (CSSRule.NAMESPACE_RULE). + * The **`CSSNamespaceRule`** interface describes an object representing a single CSS @namespace at-rule. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNamespaceRule) */ interface CSSNamespaceRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNamespaceRule/namespaceURI) */ + /** + * The read-only **`namespaceURI`** property of the CSSNamespaceRule returns a string containing the text of the URI of the given namespace. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNamespaceRule/namespaceURI) + */ readonly namespaceURI: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNamespaceRule/prefix) */ + /** + * The read-only **`prefix`** property of the CSSNamespaceRule returns a string with the name of the prefix associated to this namespace. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNamespaceRule/prefix) + */ readonly prefix: string; } @@ -3971,9 +5278,17 @@ declare var CSSNamespaceRule: { new(): CSSNamespaceRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNestedDeclarations) */ +/** + * The **`CSSNestedDeclarations`** interface of the CSS Rule API is used to group nested CSSRules. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNestedDeclarations) + */ interface CSSNestedDeclarations extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNestedDeclarations/style) */ + /** + * The read-only **`style`** property of the CSSNestedDeclarations interface represents the styles associated with the nested rules. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNestedDeclarations/style) + */ get style(): CSSStyleDeclaration; set style(cssText: string); } @@ -3983,9 +5298,17 @@ declare var CSSNestedDeclarations: { new(): CSSNestedDeclarations; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericArray) */ +/** + * The **`CSSNumericArray`** interface of the CSS Typed Object Model API contains a list of CSSNumericValue objects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericArray) + */ interface CSSNumericArray { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericArray/length) */ + /** + * The read-only **`length`** property of the An integer representing the number of CSSNumericValue objects in the list. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericArray/length) + */ readonly length: number; forEach(callbackfn: (value: CSSNumericValue, key: number, parent: CSSNumericArray) => void, thisArg?: any): void; [index: number]: CSSNumericValue; @@ -3996,46 +5319,102 @@ declare var CSSNumericArray: { new(): CSSNumericArray; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue) */ +/** + * The **`CSSNumericValue`** interface of the CSS Typed Object Model API represents operations that all numeric values can perform. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue) + */ interface CSSNumericValue extends CSSStyleValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/add) */ + /** + * The **`add()`** method of the `CSSNumericValue`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/add) + */ add(...values: CSSNumberish[]): CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/div) */ + /** + * The **`div()`** method of the supplied value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/div) + */ div(...values: CSSNumberish[]): CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/equals) */ + /** + * The **`equals()`** method of the value are strictly equal. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/equals) + */ equals(...value: CSSNumberish[]): boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/max) */ + /** + * The **`max()`** method of the passed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/max) + */ max(...values: CSSNumberish[]): CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/min) */ + /** + * The **`min()`** method of the values passed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/min) + */ min(...values: CSSNumberish[]): CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/mul) */ + /** + * The **`mul()`** method of the the supplied value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/mul) + */ mul(...values: CSSNumberish[]): CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/sub) */ + /** + * The **`sub()`** method of the `CSSNumericValue`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/sub) + */ sub(...values: CSSNumberish[]): CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/to) */ + /** + * The **`to()`** method of the another. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/to) + */ to(unit: string): CSSUnitValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/toSum) */ + /** + * The **`toSum()`** method of the ```js-nolint toSum(units) ``` - `units` - : The units to convert to. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/toSum) + */ toSum(...units: string[]): CSSMathSum; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/type) */ + /** + * The **`type()`** method of the `CSSNumericValue`, one of `angle`, `flex`, `frequency`, `length`, `resolution`, `percent`, `percentHint`, or `time`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/type) + */ type(): CSSNumericType; } declare var CSSNumericValue: { prototype: CSSNumericValue; new(): CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/parse_static) */ + /** + * The **`parse()`** static method of the members are value and the units. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSNumericValue/parse_static) + */ parse(cssText: string): CSSNumericValue; }; /** - * CSSPageRule is an interface representing a single CSS @page rule. It implements the CSSRule interface with a type value of 6 (CSSRule.PAGE_RULE). + * **`CSSPageRule`** represents a single CSS @page rule. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPageRule) */ interface CSSPageRule extends CSSGroupingRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPageRule/selectorText) */ + /** + * The **`selectorText`** property of the CSSPageRule interface gets and sets the selectors associated with the `CSSPageRule`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPageRule/selectorText) + */ selectorText: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPageRule/style) */ + /** + * The **`style`** read-only property of the CSSPageRule interface returns a CSSPageDescriptors object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPageRule/style) + */ get style(): CSSStyleDeclaration; set style(cssText: string); } @@ -4045,9 +5424,17 @@ declare var CSSPageRule: { new(): CSSPageRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPerspective) */ +/** + * The **`CSSPerspective`** interface of the CSS Typed Object Model API represents the perspective() value of the individual transform property in CSS. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPerspective) + */ interface CSSPerspective extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPerspective/length) */ + /** + * The **`length`** property of the It is used to apply a perspective transform to the element and its content. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPerspective/length) + */ length: CSSPerspectiveValue; } @@ -4056,15 +5443,35 @@ declare var CSSPerspective: { new(length: CSSPerspectiveValue): CSSPerspective; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule) */ +/** + * The **`CSSPropertyRule`** interface of the CSS Properties and Values API represents a single CSS @property rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule) + */ interface CSSPropertyRule extends CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/inherits) */ + /** + * The read-only **`inherits`** property of the CSSPropertyRule interface returns the inherit flag of the custom property registration represented by the @property rule, a boolean describing whether or not the property inherits by default. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/inherits) + */ readonly inherits: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/initialValue) */ + /** + * The read-only **`initialValue`** nullable property of the CSSPropertyRule interface returns the initial value of the custom property registration represented by the @property rule, controlling the property's initial value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/initialValue) + */ readonly initialValue: string | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/name) */ + /** + * The read-only **`name`** property of the CSSPropertyRule interface represents the property name, this being the serialization of the name given to the custom property in the @property rule's prelude. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/name) + */ readonly name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/syntax) */ + /** + * The read-only **`syntax`** property of the CSSPropertyRule interface returns the literal syntax of the custom property registration represented by the @property rule, controlling how the property's value is parsed at computed-value time. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSPropertyRule/syntax) + */ readonly syntax: string; } @@ -4073,15 +5480,35 @@ declare var CSSPropertyRule: { new(): CSSPropertyRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate) */ +/** + * The **`CSSRotate`** interface of the CSS Typed Object Model API represents the rotate value of the individual transform property in CSS. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate) + */ interface CSSRotate extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/angle) */ + /** + * The **`angle`** property of the denotes a clockwise rotation, a negative angle a counter-clockwise one. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/angle) + */ angle: CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/x) */ + /** + * The **`x`** property of the translating vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/x) + */ x: CSSNumberish; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/y) */ + /** + * The **`y`** property of the translating vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/y) + */ y: CSSNumberish; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/z) */ + /** + * The **`z`** property of the vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRotate/z) + */ z: CSSNumberish; } @@ -4092,18 +5519,31 @@ declare var CSSRotate: { }; /** - * A single CSS rule. There are several types of rules, listed in the Type constants section below. + * The **`CSSRule`** interface represents a single CSS rule. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule) */ interface CSSRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule/cssText) */ - cssText: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule/parentRule) */ - readonly parentRule: CSSRule | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule/parentStyleSheet) */ + /** + * The **`cssText`** property of the CSSRule interface returns the actual text of a CSSStyleSheet style-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule/cssText) + */ + cssText: string; + /** + * The **`parentRule`** property of the CSSRule interface returns the containing rule of the current rule if this exists, or otherwise returns null. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule/parentRule) + */ + readonly parentRule: CSSRule | null; + /** + * The **`parentStyleSheet`** property of the the current rule is defined. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule/parentStyleSheet) + */ readonly parentStyleSheet: CSSStyleSheet | null; /** + * The read-only **`type`** property of the indicating which type of rule the CSSRule represents. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRule/type) @@ -4141,14 +5581,22 @@ declare var CSSRule: { }; /** - * A CSSRuleList is an (indirect-modify only) array-like object containing an ordered collection of CSSRule objects. + * A `CSSRuleList` represents an ordered collection of read-only CSSRule objects. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRuleList) */ interface CSSRuleList { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRuleList/length) */ + /** + * The **`length`** property of the CSSRuleList interface returns the number of CSSRule objects in the list. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRuleList/length) + */ readonly length: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRuleList/item) */ + /** + * The **`item()`** method of the CSSRuleList interface returns the CSSRule object at the specified `index` or `null` if the specified `index` doesn't exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSRuleList/item) + */ item(index: number): CSSRule | null; [index: number]: CSSRule; } @@ -4158,13 +5606,29 @@ declare var CSSRuleList: { new(): CSSRuleList; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale) */ +/** + * The **`CSSScale`** interface of the CSS Typed Object Model API represents the scale() and scale3d() values of the individual transform property in CSS. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale) + */ interface CSSScale extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale/x) */ + /** + * The **`x`** property of the translating vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale/x) + */ x: CSSNumberish; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale/y) */ + /** + * The **`y`** property of the translating vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale/y) + */ y: CSSNumberish; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale/z) */ + /** + * The **`z`** property of the vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScale/z) + */ z: CSSNumberish; } @@ -4173,11 +5637,23 @@ declare var CSSScale: { new(x: CSSNumberish, y: CSSNumberish, z?: CSSNumberish): CSSScale; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScopeRule) */ +/** + * The **`CSSScopeRule`** interface of the CSS Object Model represents a CSS @scope at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScopeRule) + */ interface CSSScopeRule extends CSSGroupingRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScopeRule/end) */ + /** + * The **`end`** property of the CSSScopeRule interface returns a string containing the value of the `@scope` at-rule's scope limit. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScopeRule/end) + */ readonly end: string | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScopeRule/start) */ + /** + * The **`start`** property of the CSSScopeRule interface returns a string containing the value of the `@scope` at-rule's scope root. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSScopeRule/start) + */ readonly start: string | null; } @@ -4186,11 +5662,23 @@ declare var CSSScopeRule: { new(): CSSScopeRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkew) */ +/** + * The **`CSSSkew`** interface of the CSS Typed Object Model API is part of the CSSTransformValue interface. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkew) + */ interface CSSSkew extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkew/ax) */ + /** + * The **`ax`** property of the along the x-axis (or abscissa). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkew/ax) + */ ax: CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkew/ay) */ + /** + * The **`ay`** property of the along the y-axis (or ordinate). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkew/ay) + */ ay: CSSNumericValue; } @@ -4199,9 +5687,17 @@ declare var CSSSkew: { new(ax: CSSNumericValue, ay: CSSNumericValue): CSSSkew; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewX) */ +/** + * The **`CSSSkewX`** interface of the CSS Typed Object Model API represents the `skewX()` value of the individual transform property in CSS. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewX) + */ interface CSSSkewX extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewX/ax) */ + /** + * The **`ax`** property of the along the x-axis (or abscissa). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewX/ax) + */ ax: CSSNumericValue; } @@ -4210,9 +5706,17 @@ declare var CSSSkewX: { new(ax: CSSNumericValue): CSSSkewX; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewY) */ +/** + * The **`CSSSkewY`** interface of the CSS Typed Object Model API represents the `skewY()` value of the individual transform property in CSS. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewY) + */ interface CSSSkewY extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewY/ay) */ + /** + * The **`ay`** property of the along the y-axis (or ordinate). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSkewY/ay) + */ ay: CSSNumericValue; } @@ -4221,7 +5725,11 @@ declare var CSSSkewY: { new(ay: CSSNumericValue): CSSSkewY; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStartingStyleRule) */ +/** + * The **`CSSStartingStyleRule`** interface of the CSS Object Model represents a CSS @starting-style at-rule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStartingStyleRule) + */ interface CSSStartingStyleRule extends CSSGroupingRule { } @@ -4231,7 +5739,7 @@ declare var CSSStartingStyleRule: { }; /** - * An object that is a CSS declaration block, and exposes style information and various style-related methods and properties. + * The **`CSSStyleDeclaration`** interface represents an object that is a CSS declaration block, and exposes style information and various style-related methods and properties. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration) */ @@ -4514,7 +6022,11 @@ interface CSSStyleDeclaration { counterSet: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/cssFloat) */ cssFloat: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/cssText) */ + /** + * The **`cssText`** property of the CSSStyleDeclaration interface returns or sets the text of the element's **inline** style declaration only. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/cssText) + */ cssText: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/cursor) */ cursor: string; @@ -4576,7 +6088,11 @@ interface CSSStyleDeclaration { fontSize: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-size-adjust) */ fontSizeAdjust: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-stretch) */ + /** + * @deprecated + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-stretch) + */ fontStretch: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/font-style) */ fontStyle: string; @@ -4650,6 +6166,8 @@ interface CSSStyleDeclaration { height: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/hyphenate-character) */ hyphenateCharacter: string; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/hyphenate-limit-chars) */ + hyphenateLimitChars: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/hyphens) */ hyphens: string; /** @@ -4686,7 +6204,11 @@ interface CSSStyleDeclaration { justifySelf: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/left) */ left: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/length) */ + /** + * The read-only property returns an integer that represents the number of style declarations in this CSS declaration block. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/length) + */ readonly length: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/letter-spacing) */ letterSpacing: string; @@ -4812,8 +6334,12 @@ interface CSSStyleDeclaration { overflow: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/overflow-anchor) */ overflowAnchor: string; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/overflow-block) */ + overflowBlock: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/overflow-clip-margin) */ overflowClipMargin: string; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/overflow-inline) */ + overflowInline: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/overflow-wrap) */ overflowWrap: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/overflow-x) */ @@ -4874,7 +6400,11 @@ interface CSSStyleDeclaration { pageBreakInside: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/paint-order) */ paintOrder: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/parentRule) */ + /** + * The **CSSStyleDeclaration.parentRule** read-only property returns a CSSRule that is the parent of this style block, e.g., a CSSStyleRule representing the style for a CSS selector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/parentRule) + */ readonly parentRule: CSSRule | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/perspective) */ perspective: string; @@ -5010,8 +6540,11 @@ interface CSSStyleDeclaration { textAlignLast: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/text-anchor) */ textAnchor: string; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/text-box) */ textBox: string; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/text-box-edge) */ textBoxEdge: string; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/text-box-trim) */ textBoxTrim: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/text-combine-upright) */ textCombineUpright: string; @@ -5091,6 +6624,7 @@ interface CSSStyleDeclaration { vectorEffect: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/vertical-align) */ verticalAlign: string; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/view-transition-class) */ viewTransitionClass: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/view-transition-name) */ viewTransitionName: string; @@ -5324,7 +6858,7 @@ interface CSSStyleDeclaration { * [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/justify-content) */ webkitJustifyContent: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/-webkit-line-clamp) */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/line-clamp) */ webkitLineClamp: string; /** * @deprecated This is a legacy alias of `mask`. @@ -5526,15 +7060,35 @@ interface CSSStyleDeclaration { zIndex: string; /** [MDN Reference](https://developer.mozilla.org/docs/Web/CSS/zoom) */ zoom: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/getPropertyPriority) */ + /** + * The **CSSStyleDeclaration.getPropertyPriority()** method interface returns a string that provides all explicitly set priorities on the CSS property. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/getPropertyPriority) + */ getPropertyPriority(property: string): string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/getPropertyValue) */ + /** + * The **CSSStyleDeclaration.getPropertyValue()** method interface returns a string containing the value of a specified CSS property. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/getPropertyValue) + */ getPropertyValue(property: string): string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/item) */ + /** + * The `CSSStyleDeclaration.item()` method interface returns a CSS property name from a CSSStyleDeclaration by index. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/item) + */ item(index: number): string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/removeProperty) */ + /** + * The **`CSSStyleDeclaration.removeProperty()`** method interface removes a property from a CSS style declaration object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/removeProperty) + */ removeProperty(property: string): string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/setProperty) */ + /** + * The **`CSSStyleDeclaration.setProperty()`** method interface sets a new value for a property on a CSS style declaration object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleDeclaration/setProperty) + */ setProperty(property: string, value: string | null, priority?: string): void; [index: number]: string; } @@ -5545,17 +7099,29 @@ declare var CSSStyleDeclaration: { }; /** - * CSSStyleRule represents a single CSS style rule. It implements the CSSRule interface with a type value of 1 (CSSRule.STYLE_RULE). + * The **`CSSStyleRule`** interface represents a single CSS style rule. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleRule) */ interface CSSStyleRule extends CSSGroupingRule { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleRule/selectorText) */ + /** + * The **`selectorText`** property of the CSSStyleRule interface gets and sets the selectors associated with the `CSSStyleRule`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleRule/selectorText) + */ selectorText: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleRule/style) */ + /** + * The read-only **`style`** property is the CSSStyleDeclaration interface for the declaration block of the CSSStyleRule. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleRule/style) + */ get style(): CSSStyleDeclaration; set style(cssText: string); - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleRule/styleMap) */ + /** + * The **`styleMap`** read-only property of the which provides access to the rule's property-value pairs. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleRule/styleMap) + */ readonly styleMap: StylePropertyMap; } @@ -5565,40 +7131,67 @@ declare var CSSStyleRule: { }; /** - * A single CSS style sheet. It inherits properties and methods from its parent, StyleSheet. + * The **`CSSStyleSheet`** interface represents a single CSS stylesheet, and lets you inspect and modify the list of rules contained in the stylesheet. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet) */ interface CSSStyleSheet extends StyleSheet { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/cssRules) */ + /** + * The read-only CSSStyleSheet property **`cssRules`** returns a live CSSRuleList which provides a real-time, up-to-date list of every CSS rule which comprises the stylesheet. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/cssRules) + */ readonly cssRules: CSSRuleList; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/ownerRule) */ + /** + * The read-only CSSStyleSheet property **`ownerRule`** returns the CSSImportRule corresponding to the @import at-rule which imported the stylesheet into the document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/ownerRule) + */ readonly ownerRule: CSSRule | null; /** + * **`rules`** is a _deprecated_ _legacy property_ of the CSSStyleSheet interface. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/rules) */ readonly rules: CSSRuleList; /** + * The obsolete CSSStyleSheet interface's **`addRule()`** _legacy method_ adds a new rule to the stylesheet. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/addRule) */ addRule(selector?: string, style?: string, index?: number): number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/deleteRule) */ + /** + * The CSSStyleSheet method **`deleteRule()`** removes a rule from the stylesheet object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/deleteRule) + */ deleteRule(index: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/insertRule) */ + /** + * The **`CSSStyleSheet.insertRule()`** method inserts a new CSS rule into the current style sheet. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/insertRule) + */ insertRule(rule: string, index?: number): number; /** + * The obsolete CSSStyleSheet method **`removeRule()`** removes a rule from the stylesheet object. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/removeRule) */ removeRule(index?: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/replace) */ + /** + * The **`replace()`** method of the CSSStyleSheet interface asynchronously replaces the content of the stylesheet with the content passed into it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/replace) + */ replace(text: string): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/replaceSync) */ + /** + * The **`replaceSync()`** method of the CSSStyleSheet interface synchronously replaces the content of the stylesheet with the content passed into it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleSheet/replaceSync) + */ replaceSync(text: string): void; } @@ -5607,7 +7200,11 @@ declare var CSSStyleSheet: { new(options?: CSSStyleSheetInit): CSSStyleSheet; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleValue) */ +/** + * The **`CSSStyleValue`** interface of the CSS Typed Object Model API is the base class of all CSS values accessible through the Typed OM API. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleValue) + */ interface CSSStyleValue { toString(): string; } @@ -5615,14 +7212,22 @@ interface CSSStyleValue { declare var CSSStyleValue: { prototype: CSSStyleValue; new(): CSSStyleValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleValue/parse_static) */ + /** + * The **`parse()`** static method of the CSSStyleValue interface sets a specific CSS property to the specified values and returns the first value as a CSSStyleValue object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleValue/parse_static) + */ parse(property: string, cssText: string): CSSStyleValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleValue/parseAll_static) */ + /** + * The **`parseAll()`** static method of the CSSStyleValue interface sets all occurrences of a specific CSS property to the specified value and returns an array of CSSStyleValue objects, each containing one of the supplied values. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSStyleValue/parseAll_static) + */ parseAll(property: string, cssText: string): CSSStyleValue[]; }; /** - * An object representing a single CSS @supports at-rule. It implements the CSSConditionRule interface, and therefore the CSSRule and CSSGroupingRule interfaces with a type value of 12 (CSSRule.SUPPORTS_RULE). + * The **`CSSSupportsRule`** interface represents a single CSS @supports at-rule. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSSupportsRule) */ @@ -5634,11 +7239,23 @@ declare var CSSSupportsRule: { new(): CSSSupportsRule; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformComponent) */ +/** + * The **`CSSTransformComponent`** interface of the CSS Typed Object Model API is part of the CSSTransformValue interface. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformComponent) + */ interface CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformComponent/is2D) */ + /** + * The **`is2D`** read-only property of the CSSTransformComponent interface indicates where the transform is 2D or 3D. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformComponent/is2D) + */ is2D: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformComponent/toMatrix) */ + /** + * The **`toMatrix()`** method of the object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformComponent/toMatrix) + */ toMatrix(): DOMMatrix; toString(): string; } @@ -5648,13 +7265,29 @@ declare var CSSTransformComponent: { new(): CSSTransformComponent; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue) */ +/** + * The **`CSSTransformValue`** interface of the CSS Typed Object Model API represents `transform-list` values as used by the CSS transform property. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue) + */ interface CSSTransformValue extends CSSStyleValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue/is2D) */ + /** + * The read-only **`is2D`** property of the In the case of the `CSSTransformValue` this property returns true unless any of the individual functions return false for `Is2D`, in which case it returns false. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue/is2D) + */ readonly is2D: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue/length) */ + /** + * The read-only **`length`** property of the the list. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue/length) + */ readonly length: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue/toMatrix) */ + /** + * The **`toMatrix()`** method of the ```js-nolint toMatrix() ``` None. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransformValue/toMatrix) + */ toMatrix(): DOMMatrix; forEach(callbackfn: (value: CSSTransformComponent, key: number, parent: CSSTransformValue) => void, thisArg?: any): void; [index: number]: CSSTransformComponent; @@ -5665,9 +7298,17 @@ declare var CSSTransformValue: { new(transforms: CSSTransformComponent[]): CSSTransformValue; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransition) */ +/** + * The **`CSSTransition`** interface of the Web Animations API represents an Animation object used for a CSS Transition. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransition) + */ interface CSSTransition extends Animation { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransition/transitionProperty) */ + /** + * The **`transitionProperty`** property of the name** of the transition. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTransition/transitionProperty) + */ readonly transitionProperty: string; addEventListener(type: K, listener: (this: CSSTransition, ev: AnimationEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -5680,13 +7321,29 @@ declare var CSSTransition: { new(): CSSTransition; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate) */ +/** + * The **`CSSTranslate`** interface of the CSS Typed Object Model API represents the translate() value of the individual transform property in CSS. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate) + */ interface CSSTranslate extends CSSTransformComponent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate/x) */ + /** + * The **`x`** property of the translating vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate/x) + */ x: CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate/y) */ + /** + * The **`y`** property of the translating vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate/y) + */ y: CSSNumericValue; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate/z) */ + /** + * The **`z`** property of the vector. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSTranslate/z) + */ z: CSSNumericValue; } @@ -5695,11 +7352,23 @@ declare var CSSTranslate: { new(x: CSSNumericValue, y: CSSNumericValue, z?: CSSNumericValue): CSSTranslate; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnitValue) */ +/** + * The **`CSSUnitValue`** interface of the CSS Typed Object Model API represents values that contain a single unit type. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnitValue) + */ interface CSSUnitValue extends CSSNumericValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnitValue/unit) */ + /** + * The **`CSSUnitValue.unit`** read-only property of the CSSUnitValue interface returns a string indicating the type of unit. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnitValue/unit) + */ readonly unit: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnitValue/value) */ + /** + * The **`CSSUnitValue.value`** property of the A double. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnitValue/value) + */ value: number; } @@ -5708,9 +7377,17 @@ declare var CSSUnitValue: { new(value: number, unit: string): CSSUnitValue; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnparsedValue) */ +/** + * The **`CSSUnparsedValue`** interface of the CSS Typed Object Model API represents property values that reference custom properties. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnparsedValue) + */ interface CSSUnparsedValue extends CSSStyleValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnparsedValue/length) */ + /** + * The **`length`** read-only property of the An integer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSUnparsedValue/length) + */ readonly length: number; forEach(callbackfn: (value: CSSUnparsedSegment, key: number, parent: CSSUnparsedValue) => void, thisArg?: any): void; [index: number]: CSSUnparsedSegment; @@ -5721,11 +7398,23 @@ declare var CSSUnparsedValue: { new(members: CSSUnparsedSegment[]): CSSUnparsedValue; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSVariableReferenceValue) */ +/** + * The **`CSSVariableReferenceValue`** interface of the CSS Typed Object Model API allows you to create a custom name for a built-in CSS value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSVariableReferenceValue) + */ interface CSSVariableReferenceValue { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSVariableReferenceValue/fallback) */ + /** + * The **`fallback`** read-only property of the A CSSUnparsedValue. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSVariableReferenceValue/fallback) + */ readonly fallback: CSSUnparsedValue | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSVariableReferenceValue/variable) */ + /** + * The **`variable`** property of the A string beginning with `--` (that is, a custom property name). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CSSVariableReferenceValue/variable) + */ variable: string; } @@ -5745,25 +7434,53 @@ declare var CSSViewTransitionRule: { }; /** - * Provides a storage mechanism for Request / Response object pairs that are cached, for example as part of the ServiceWorker life cycle. Note that the Cache interface is exposed to windowed scopes as well as workers. You don't have to use it in conjunction with service workers, even though it is defined in the service worker spec. + * The **`Cache`** interface provides a persistent storage mechanism for Request / Response object pairs that are cached in long lived memory. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache) */ interface Cache { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/add) */ + /** + * The **`add()`** method of the Cache interface takes a URL, retrieves it, and adds the resulting response object to the given cache. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/add) + */ add(request: RequestInfo | URL): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/addAll) */ + /** + * The **`addAll()`** method of the Cache interface takes an array of URLs, retrieves them, and adds the resulting response objects to the given cache. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/addAll) + */ addAll(requests: RequestInfo[]): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/delete) */ + /** + * The **`delete()`** method of the Cache interface finds the Cache entry whose key is the request, and if found, deletes the Cache entry and returns a Promise that resolves to `true`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/delete) + */ delete(request: RequestInfo | URL, options?: CacheQueryOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/keys) */ + /** + * The **`keys()`** method of the Cache interface returns a representing the keys of the Cache. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/keys) + */ keys(request?: RequestInfo | URL, options?: CacheQueryOptions): Promise>; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/match) */ + /** + * The **`match()`** method of the Cache interface returns a Promise that resolves to the Response associated with the first matching request in the Cache object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/match) + */ match(request: RequestInfo | URL, options?: CacheQueryOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/matchAll) */ + /** + * The **`matchAll()`** method of the Cache interface returns a Promise that resolves to an array of all matching responses in the Cache object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/matchAll) + */ matchAll(request?: RequestInfo | URL, options?: CacheQueryOptions): Promise>; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/put) */ + /** + * The **`put()`** method of the Often, you will just want to Window/fetch one or more requests, then add the result straight to your cache. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Cache/put) + */ put(request: RequestInfo | URL, response: Response): Promise; } @@ -5773,21 +7490,41 @@ declare var Cache: { }; /** - * The storage for Cache objects. + * The **`CacheStorage`** interface represents the storage for Cache objects. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage) */ interface CacheStorage { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/delete) */ + /** + * The **`delete()`** method of the CacheStorage interface finds the Cache object matching the `cacheName`, and if found, deletes the Cache object and returns a Promise that resolves to `true`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/delete) + */ delete(cacheName: string): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/has) */ + /** + * The **`has()`** method of the CacheStorage interface returns a Promise that resolves to `true` if a You can access `CacheStorage` through the Window.caches property in windows or through the WorkerGlobalScope.caches property in workers. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/has) + */ has(cacheName: string): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/keys) */ + /** + * The **`keys()`** method of the CacheStorage interface returns a Promise that will resolve with an array containing strings corresponding to all of the named Cache objects tracked by the CacheStorage object in the order they were created. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/keys) + */ keys(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/match) */ + /** + * The **`match()`** method of the CacheStorage interface checks if a given Request or URL string is a key for a stored Response. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/match) + */ match(request: RequestInfo | URL, options?: MultiCacheQueryOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/open) */ + /** + * The **`open()`** method of the the Cache object matching the `cacheName`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CacheStorage/open) + */ open(cacheName: string): Promise; } @@ -5796,11 +7533,23 @@ declare var CacheStorage: { new(): CacheStorage; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasCaptureMediaStreamTrack) */ +/** + * The **`CanvasCaptureMediaStreamTrack`** interface of the Media Capture and Streams API represents the video track contained in a MediaStream being generated from a canvas following a call to HTMLCanvasElement.captureStream(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasCaptureMediaStreamTrack) + */ interface CanvasCaptureMediaStreamTrack extends MediaStreamTrack { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasCaptureMediaStreamTrack/canvas) */ + /** + * The **`canvas`** read-only property of the CanvasCaptureMediaStreamTrack interface returns the HTMLCanvasElement from which frames are being captured. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasCaptureMediaStreamTrack/canvas) + */ readonly canvas: HTMLCanvasElement; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasCaptureMediaStreamTrack/requestFrame) */ + /** + * The **`requestFrame()`** method of the CanvasCaptureMediaStreamTrack interface requests that a frame be captured from the canvas and sent to the stream. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasCaptureMediaStreamTrack/requestFrame) + */ requestFrame(): void; addEventListener(type: K, listener: (this: CanvasCaptureMediaStreamTrack, ev: MediaStreamTrackEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -5868,15 +7617,13 @@ interface CanvasFilters { } /** - * An opaque object describing a gradient. It is returned by the methods CanvasRenderingContext2D.createLinearGradient() or CanvasRenderingContext2D.createRadialGradient(). + * The **`CanvasGradient`** interface represents an opaque object describing a gradient. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasGradient) */ interface CanvasGradient { /** - * Adds a color stop with the given color to the gradient at the given offset. 0.0 is the offset at one end of the gradient, 1.0 is the offset at the other end. - * - * Throws an "IndexSizeError" DOMException if the offset is out of range. Throws a "SyntaxError" DOMException if the color cannot be parsed. + * The **`CanvasGradient.addColorStop()`** method adds a new color stop, defined by an `offset` and a `color`, to a given canvas gradient. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasGradient/addColorStop) */ @@ -5891,12 +7638,12 @@ declare var CanvasGradient: { interface CanvasImageData { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/createImageData) */ createImageData(sw: number, sh: number, settings?: ImageDataSettings): ImageData; - createImageData(imagedata: ImageData): ImageData; + createImageData(imageData: ImageData): ImageData; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/getImageData) */ getImageData(sx: number, sy: number, sw: number, sh: number, settings?: ImageDataSettings): ImageData; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/putImageData) */ - putImageData(imagedata: ImageData, dx: number, dy: number): void; - putImageData(imagedata: ImageData, dx: number, dy: number, dirtyX: number, dirtyY: number, dirtyWidth: number, dirtyHeight: number): void; + putImageData(imageData: ImageData, dx: number, dy: number): void; + putImageData(imageData: ImageData, dx: number, dy: number, dirtyX: number, dirtyY: number, dirtyWidth: number, dirtyHeight: number): void; } interface CanvasImageSmoothing { @@ -5947,13 +7694,13 @@ interface CanvasPathDrawingStyles { } /** - * An opaque object describing a pattern, based on an image, a canvas, or a video, created by the CanvasRenderingContext2D.createPattern() method. + * The **`CanvasPattern`** interface represents an opaque object describing a pattern, based on an image, a canvas, or a video, created by the CanvasRenderingContext2D.createPattern() method. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasPattern) */ interface CanvasPattern { /** - * Sets the transformation matrix that will be used when rendering the pattern during a fill or stroke painting operation. + * The **`CanvasPattern.setTransform()`** method uses a DOMMatrix object as the pattern's transformation matrix and invokes it on the pattern. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasPattern/setTransform) */ @@ -5975,12 +7722,16 @@ interface CanvasRect { } /** - * The CanvasRenderingContext2D interface, part of the Canvas API, provides the 2D rendering context for the drawing surface of a element. It is used for drawing shapes, text, images, and other objects. + * The **`CanvasRenderingContext2D`** interface, part of the Canvas API, provides the 2D rendering context for the drawing surface of a canvas element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D) */ interface CanvasRenderingContext2D extends CanvasCompositing, CanvasDrawImage, CanvasDrawPath, CanvasFillStrokeStyles, CanvasFilters, CanvasImageData, CanvasImageSmoothing, CanvasPath, CanvasPathDrawingStyles, CanvasRect, CanvasSettings, CanvasShadowStyles, CanvasState, CanvasText, CanvasTextDrawingStyles, CanvasTransform, CanvasUserInterface { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/canvas) */ + /** + * The **`CanvasRenderingContext2D.canvas`** property, part of the Canvas API, is a read-only reference to the might be `null` if there is no associated canvas element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CanvasRenderingContext2D/canvas) + */ readonly canvas: HTMLCanvasElement; } @@ -6072,7 +7823,11 @@ interface CanvasUserInterface { drawFocusIfNeeded(path: Path2D, element: Element): void; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CaretPosition) */ +/** + * The `CaretPosition` interface represents the caret position, an indicator for the text insertion point. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CaretPosition) + */ interface CaretPosition { readonly offset: number; readonly offsetNode: Node; @@ -6085,7 +7840,7 @@ declare var CaretPosition: { }; /** - * The ChannelMergerNode interface, often used in conjunction with its opposite, ChannelSplitterNode, reunites different mono inputs into a single output. Each input is used to fill a channel of the output. This is useful for accessing each channels separately, e.g. for performing channel mixing where gain must be separately controlled on each channel. + * The `ChannelMergerNode` interface, often used in conjunction with its opposite, ChannelSplitterNode, reunites different mono inputs into a single output. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ChannelMergerNode) */ @@ -6098,7 +7853,7 @@ declare var ChannelMergerNode: { }; /** - * The ChannelSplitterNode interface, often used in conjunction with its opposite, ChannelMergerNode, separates the different channels of an audio source into a set of mono outputs. This is useful for accessing each channel separately, e.g. for performing channel mixing where gain must be separately controlled on each channel. + * The `ChannelSplitterNode` interface, often used in conjunction with its opposite, ChannelMergerNode, separates the different channels of an audio source into a set of mono outputs. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ChannelSplitterNode) */ @@ -6111,26 +7866,57 @@ declare var ChannelSplitterNode: { }; /** - * The CharacterData abstract interface represents a Node object that contains characters. This is an abstract interface, meaning there aren't any object of type CharacterData: it is implemented by other interfaces, like Text, Comment, or ProcessingInstruction which aren't abstract. + * The **`CharacterData`** abstract interface represents a Node object that contains characters. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData) */ interface CharacterData extends Node, ChildNode, NonDocumentTypeChildNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/data) */ + /** + * The **`data`** property of the CharacterData interface represent the value of the current object's data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/data) + */ data: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/length) */ + /** + * The read-only **`CharacterData.length`** property returns the number of characters in the contained data, as a positive integer. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/length) + */ readonly length: number; readonly ownerDocument: Document; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/appendData) */ + /** + * The **`appendData()`** method of the CharacterData interface adds the provided data to the end of the node's current data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/appendData) + */ appendData(data: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/deleteData) */ + /** + * The **`deleteData()`** method of the CharacterData interface removes all or part of the data from this `CharacterData` node. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/deleteData) + */ deleteData(offset: number, count: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/insertData) */ - insertData(offset: number, data: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/replaceData) */ - replaceData(offset: number, count: number, data: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/substringData) */ + /** + * The **`insertData()`** method of the CharacterData interface inserts the provided data into this `CharacterData` node's current data, at the provided offset from the start of the existing data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/insertData) + */ + insertData(offset: number, data: string): void; + /** + * The **`replaceData()`** method of the CharacterData interface removes a certain number of characters of the existing text in a given `CharacterData` node and replaces those characters with the text provided. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/replaceData) + */ + replaceData(offset: number, count: number, data: string): void; + /** + * The **`substringData()`** method of the CharacterData interface returns a portion of the existing data, starting at the specified index and extending for a given number of characters afterwards. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CharacterData/substringData) + */ substringData(offset: number, count: number): string; + /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) */ + get textContent(): string; + set textContent(value: string | null); } declare var CharacterData: { @@ -6176,18 +7962,35 @@ interface ClientRect extends DOMRect { } /** + * The **`Clipboard`** interface of the Clipboard API provides read and write access to the contents of the system clipboard. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard) */ interface Clipboard extends EventTarget { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/read) */ + /** + * The **`read()`** method of the Clipboard interface requests a copy of the clipboard's contents, fulfilling the returned Promise with the data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/read) + */ read(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/readText) */ + /** + * The **`readText()`** method of the Clipboard interface returns a Promise which fulfills with a copy of the textual contents of the system clipboard. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/readText) + */ readText(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/write) */ + /** + * The **`write()`** method of the Clipboard interface writes arbitrary ClipboardItem data such as images and text to the clipboard, fulfilling the returned Promise on completion. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/write) + */ write(data: ClipboardItems): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/writeText) */ + /** + * The **`writeText()`** method of the Clipboard interface writes the specified text to the system clipboard, returning a Promise that is resolved once the system clipboard has been updated. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Clipboard/writeText) + */ writeText(data: string): Promise; } @@ -6197,12 +8000,16 @@ declare var Clipboard: { }; /** - * Events providing information related to modification of the clipboard, that is cut, copy, and paste events. + * The **`ClipboardEvent`** interface of the Clipboard API represents events providing information related to modification of the clipboard, that is Element/cut_event, Element/copy_event, and Element/paste_event events. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardEvent) */ interface ClipboardEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardEvent/clipboardData) */ + /** + * The **`clipboardData`** property of the ClipboardEvent interface holds a DataTransfer object, which can be used to: - specify what data should be put into the clipboard from the Element/cut_event and Element/copy_event event handlers, typically with a DataTransfer.setData call; - obtain the data to be pasted from the Element/paste_event event handler, typically with a DataTransfer.getData call. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardEvent/clipboardData) + */ readonly clipboardData: DataTransfer | null; } @@ -6212,46 +8019,63 @@ declare var ClipboardEvent: { }; /** + * The **`ClipboardItem`** interface of the Clipboard API represents a single item format, used when reading or writing clipboard data using Clipboard.read() and Clipboard.write() respectively. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem) */ interface ClipboardItem { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/presentationStyle) */ + /** + * The read-only **`presentationStyle`** property of the ClipboardItem interface returns a string indicating how an item should be presented. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/presentationStyle) + */ readonly presentationStyle: PresentationStyle; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/types) */ + /** + * The read-only **`types`** property of the ClipboardItem interface returns an Array of MIME type available within the ClipboardItem. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/types) + */ readonly types: ReadonlyArray; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/getType) */ + /** + * The **`getType()`** method of the ClipboardItem interface returns a Promise that resolves with a Blob of the requested MIME type or an error if the MIME type is not found. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/getType) + */ getType(type: string): Promise; } declare var ClipboardItem: { prototype: ClipboardItem; new(items: Record>, options?: ClipboardItemOptions): ClipboardItem; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/supports_static) */ + /** + * The **`supports()`** static method of the ClipboardItem interface returns `true` if the given MIME type is supported by the clipboard, and `false` otherwise. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ClipboardItem/supports_static) + */ supports(type: string): boolean; }; /** - * A CloseEvent is sent to clients using WebSockets when the connection is closed. This is delivered to the listener indicated by the WebSocket object's onclose attribute. + * A `CloseEvent` is sent to clients using WebSockets when the connection is closed. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent) */ interface CloseEvent extends Event { /** - * Returns the WebSocket connection close code provided by the server. + * The **`code`** read-only property of the CloseEvent interface returns a WebSocket connection close code indicating the reason the connection was closed. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/code) */ readonly code: number; /** - * Returns the WebSocket connection close reason provided by the server. + * The **`reason`** read-only property of the CloseEvent interface returns the WebSocket connection close reason the server gave for closing the connection; that is, a concise human-readable prose explanation for the closure. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/reason) */ readonly reason: string; /** - * Returns true if the connection closed cleanly; false otherwise. + * The **`wasClean`** read-only property of the CloseEvent interface returns `true` if the connection closed cleanly. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CloseEvent/wasClean) */ @@ -6264,7 +8088,7 @@ declare var CloseEvent: { }; /** - * Textual notations within markup; although it is generally not visually shown, such comments are available to be read in the source view. + * The **`Comment`** interface represents textual notations within markup; although it is generally not visually shown, such comments are available to be read in the source view. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Comment) */ @@ -6277,14 +8101,19 @@ declare var Comment: { }; /** - * The DOM CompositionEvent represents events that occur due to the user indirectly entering text. + * The DOM **`CompositionEvent`** represents events that occur due to the user indirectly entering text. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompositionEvent) */ interface CompositionEvent extends UIEvent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompositionEvent/data) */ + /** + * The **`data`** read-only property of the method that raised the event; its exact nature varies depending on the type of event that generated the `CompositionEvent` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompositionEvent/data) + */ readonly data: string; /** + * The **`initCompositionEvent()`** method of the CompositionEvent interface initializes the attributes of a `CompositionEvent` object instance. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompositionEvent/initCompositionEvent) @@ -6297,9 +8126,13 @@ declare var CompositionEvent: { new(type: string, eventInitDict?: CompositionEventInit): CompositionEvent; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompressionStream) */ +/** + * The **`CompressionStream`** interface of the Compression Streams API is an API for compressing a stream of data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CompressionStream) + */ interface CompressionStream extends GenericTransformStream { - readonly readable: ReadableStream; + readonly readable: ReadableStream>; readonly writable: WritableStream; } @@ -6308,9 +8141,17 @@ declare var CompressionStream: { new(format: CompressionFormat): CompressionStream; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConstantSourceNode) */ +/** + * The `ConstantSourceNode` interface—part of the Web Audio API—represents an audio source (based upon AudioScheduledSourceNode) whose output is single unchanging value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConstantSourceNode) + */ interface ConstantSourceNode extends AudioScheduledSourceNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConstantSourceNode/offset) */ + /** + * The read-only `offset` property of the ConstantSourceNode interface returns a AudioParam object indicating the numeric a-rate value which is always returned by the source when asked for the next sample. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConstantSourceNode/offset) + */ readonly offset: AudioParam; addEventListener(type: K, listener: (this: ConstantSourceNode, ev: AudioScheduledSourceNodeEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; @@ -6323,9 +8164,17 @@ declare var ConstantSourceNode: { new(context: BaseAudioContext, options?: ConstantSourceOptions): ConstantSourceNode; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ContentVisibilityAutoStateChangeEvent) */ +/** + * The **`ContentVisibilityAutoStateChangeEvent`** interface is the event object for the element/contentvisibilityautostatechange_event event, which fires on any element with content-visibility set on it when it starts or stops being relevant to the user and skipping its contents. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ContentVisibilityAutoStateChangeEvent) + */ interface ContentVisibilityAutoStateChangeEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ContentVisibilityAutoStateChangeEvent/skipped) */ + /** + * The `skipped` read-only property of the ContentVisibilityAutoStateChangeEvent interface returns `true` if the user agent skips the element's contents, or `false` otherwise. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ContentVisibilityAutoStateChangeEvent/skipped) + */ readonly skipped: boolean; } @@ -6335,14 +8184,22 @@ declare var ContentVisibilityAutoStateChangeEvent: { }; /** - * An AudioNode that performs a Linear Convolution on a given AudioBuffer, often used to achieve a reverb effect. A ConvolverNode always has exactly one input and one output. + * The `ConvolverNode` interface is an AudioNode that performs a Linear Convolution on a given AudioBuffer, often used to achieve a reverb effect. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConvolverNode) */ interface ConvolverNode extends AudioNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConvolverNode/buffer) */ + /** + * The **`buffer`** property of the ConvolverNode interface represents a mono, stereo, or 4-channel AudioBuffer containing the (possibly multichannel) impulse response used by the `ConvolverNode` to create the reverb effect. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConvolverNode/buffer) + */ buffer: AudioBuffer | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConvolverNode/normalize) */ + /** + * The `normalize` property of the ConvolverNode interface is a boolean that controls whether the impulse response from the buffer will be scaled by an equal-power normalization when the `buffer` attribute is set, or not. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ConvolverNode/normalize) + */ normalize: boolean; } @@ -6352,12 +8209,126 @@ declare var ConvolverNode: { }; /** - * This Streams API interface provides a built-in byte length queuing strategy that can be used when constructing streams. + * The **`CookieChangeEvent`** interface of the Cookie Store API is the event type of the CookieStore/change_event event fired at a CookieStore when any cookies are created or deleted. + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieChangeEvent) + */ +interface CookieChangeEvent extends Event { + /** + * The **`changed`** read-only property of the CookieChangeEvent interface returns an array of the cookies that have been changed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieChangeEvent/changed) + */ + readonly changed: ReadonlyArray; + /** + * The **`deleted`** read-only property of the CookieChangeEvent interface returns an array of the cookies that have been deleted by the given `CookieChangeEvent` instance. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieChangeEvent/deleted) + */ + readonly deleted: ReadonlyArray; +} + +declare var CookieChangeEvent: { + prototype: CookieChangeEvent; + new(type: string, eventInitDict?: CookieChangeEventInit): CookieChangeEvent; +}; + +interface CookieStoreEventMap { + "change": CookieChangeEvent; +} + +/** + * The **`CookieStore`** interface of the Cookie Store API provides methods for getting and setting cookies asynchronously from either a page or a service worker. + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStore) + */ +interface CookieStore extends EventTarget { + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStore/change_event) */ + onchange: ((this: CookieStore, ev: CookieChangeEvent) => any) | null; + /** + * The **`delete()`** method of the CookieStore interface deletes a cookie that matches the given `name` or `options` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStore/delete) + */ + delete(name: string): Promise; + delete(options: CookieStoreDeleteOptions): Promise; + /** + * The **`get()`** method of the CookieStore interface returns a Promise that resolves to a single cookie matching the given `name` or `options` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStore/get) + */ + get(name: string): Promise; + get(options?: CookieStoreGetOptions): Promise; + /** + * The **`getAll()`** method of the CookieStore interface returns a Promise that resolves as an array of cookies that match the `name` or `options` passed to it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStore/getAll) + */ + getAll(name: string): Promise; + getAll(options?: CookieStoreGetOptions): Promise; + /** + * The **`set()`** method of the CookieStore interface sets a cookie with the given `name` and `value` or `options` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStore/set) + */ + set(name: string, value: string): Promise; + set(options: CookieInit): Promise; + addEventListener(type: K, listener: (this: CookieStore, ev: CookieStoreEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; + addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; + removeEventListener(type: K, listener: (this: CookieStore, ev: CookieStoreEventMap[K]) => any, options?: boolean | EventListenerOptions): void; + removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void; +} + +declare var CookieStore: { + prototype: CookieStore; + new(): CookieStore; +}; + +/** + * The **`CookieStoreManager`** interface of the Cookie Store API allows service workers to subscribe to cookie change events. + * Available only in secure contexts. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStoreManager) + */ +interface CookieStoreManager { + /** + * The **`getSubscriptions()`** method of the CookieStoreManager interface returns a list of all the cookie change subscriptions for this ServiceWorkerRegistration. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStoreManager/getSubscriptions) + */ + getSubscriptions(): Promise; + /** + * The **`subscribe()`** method of the CookieStoreManager interface subscribes a ServiceWorkerRegistration to cookie change events. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStoreManager/subscribe) + */ + subscribe(subscriptions: CookieStoreGetOptions[]): Promise; + /** + * The **`unsubscribe()`** method of the CookieStoreManager interface stops the ServiceWorkerRegistration from receiving previously subscribed events. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CookieStoreManager/unsubscribe) + */ + unsubscribe(subscriptions: CookieStoreGetOptions[]): Promise; +} + +declare var CookieStoreManager: { + prototype: CookieStoreManager; + new(): CookieStoreManager; +}; + +/** + * The **`CountQueuingStrategy`** interface of the Streams API provides a built-in chunk counting queuing strategy that can be used when constructing streams. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy) */ interface CountQueuingStrategy extends QueuingStrategy { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy/highWaterMark) */ + /** + * The read-only **`CountQueuingStrategy.highWaterMark`** property returns the total number of chunks that can be contained in the internal queue before backpressure is applied. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy/highWaterMark) + */ readonly highWaterMark: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CountQueuingStrategy/size) */ readonly size: QueuingStrategySize; @@ -6369,14 +8340,23 @@ declare var CountQueuingStrategy: { }; /** + * The **`Credential`** interface of the Credential Management API provides information about an entity (usually a user) normally as a prerequisite to a trust decision. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Credential) */ interface Credential { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Credential/id) */ + /** + * The **`id`** read-only property of the Credential interface returns a string containing the credential's identifier. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Credential/id) + */ readonly id: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Credential/type) */ + /** + * The **`type`** read-only property of the Credential interface returns a string containing the credential's type. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Credential/type) + */ readonly type: string; } @@ -6386,18 +8366,35 @@ declare var Credential: { }; /** + * The **`CredentialsContainer`** interface of the Credential Management API exposes methods to request credentials and notify the user agent when events such as successful sign in or sign out happen. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer) */ interface CredentialsContainer { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/create) */ + /** + * The **`create()`** method of the CredentialsContainer interface creates a new credential, which can then be stored and later retrieved using the CredentialsContainer.get method. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/create) + */ create(options?: CredentialCreationOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/get) */ + /** + * The **`get()`** method of the CredentialsContainer interface returns a Promise that fulfills with a single credential, which can then be used to authenticate a user to a website. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/get) + */ get(options?: CredentialRequestOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/preventSilentAccess) */ + /** + * The **`preventSilentAccess()`** method of the CredentialsContainer interface sets a flag that specifies whether automatic log in is allowed for future visits to the current origin, then returns a Promise that resolves to `undefined`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/preventSilentAccess) + */ preventSilentAccess(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/store) */ + /** + * The **`store()`** method of the ```js-nolint store(credentials) ``` - `credentials` - : A valid Credential instance. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CredentialsContainer/store) + */ store(credential: Credential): Promise; } @@ -6407,20 +8404,26 @@ declare var CredentialsContainer: { }; /** - * Basic cryptography features available in the current context. It allows access to a cryptographically strong random number generator and to cryptographic primitives. + * The **`Crypto`** interface represents basic cryptography features available in the current context. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto) */ interface Crypto { /** + * The **`Crypto.subtle`** read-only property returns a cryptographic operations. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/subtle) */ readonly subtle: SubtleCrypto; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/getRandomValues) */ - getRandomValues(array: T): T; /** + * The **`Crypto.getRandomValues()`** method lets you get cryptographically strong random values. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/getRandomValues) + */ + getRandomValues(array: T): T; + /** + * The **`randomUUID()`** method of the Crypto interface is used to generate a v4 UUID using a cryptographically secure random number generator. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Crypto/randomUUID) @@ -6434,19 +8437,35 @@ declare var Crypto: { }; /** - * The CryptoKey dictionary of the Web Crypto API represents a cryptographic key. + * The **`CryptoKey`** interface of the Web Crypto API represents a cryptographic key obtained from one of the SubtleCrypto methods SubtleCrypto.generateKey, SubtleCrypto.deriveKey, SubtleCrypto.importKey, or SubtleCrypto.unwrapKey. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey) */ interface CryptoKey { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/algorithm) */ + /** + * The read-only **`algorithm`** property of the CryptoKey interface returns an object describing the algorithm for which this key can be used, and any associated extra parameters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/algorithm) + */ readonly algorithm: KeyAlgorithm; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/extractable) */ + /** + * The read-only **`extractable`** property of the CryptoKey interface indicates whether or not the key may be extracted using `SubtleCrypto.exportKey()` or `SubtleCrypto.wrapKey()`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/extractable) + */ readonly extractable: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/type) */ + /** + * The read-only **`type`** property of the CryptoKey interface indicates which kind of key is represented by the object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/type) + */ readonly type: KeyType; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/usages) */ + /** + * The read-only **`usages`** property of the CryptoKey interface indicates what can be done with the key. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CryptoKey/usages) + */ readonly usages: KeyUsage[]; } @@ -6455,17 +8474,41 @@ declare var CryptoKey: { new(): CryptoKey; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry) */ +/** + * The **`CustomElementRegistry`** interface provides methods for registering custom elements and querying registered elements. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry) + */ interface CustomElementRegistry { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/define) */ + /** + * The **`define()`** method of the CustomElementRegistry interface adds a definition for a custom element to the custom element registry, mapping its name to the constructor which will be used to create it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/define) + */ define(name: string, constructor: CustomElementConstructor, options?: ElementDefinitionOptions): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/get) */ + /** + * The **`get()`** method of the previously-defined custom element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/get) + */ get(name: string): CustomElementConstructor | undefined; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/getName) */ + /** + * The **`getName()`** method of the previously-defined custom element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/getName) + */ getName(constructor: CustomElementConstructor): string | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/upgrade) */ + /** + * The **`upgrade()`** method of the elements in a Node subtree, even before they are connected to the main document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/upgrade) + */ upgrade(root: Node): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/whenDefined) */ + /** + * The **`whenDefined()`** method of the resolves when the named element is defined. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomElementRegistry/whenDefined) + */ whenDefined(name: string): Promise; } @@ -6474,15 +8517,20 @@ declare var CustomElementRegistry: { new(): CustomElementRegistry; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent) */ +/** + * The **`CustomEvent`** interface represents events initialized by an application for any purpose. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent) + */ interface CustomEvent extends Event { /** - * Returns any custom data event was created with. Typically used for synthetic events. + * The read-only **`detail`** property of the CustomEvent interface returns any data passed when initializing the event. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent/detail) */ readonly detail: T; /** + * The **`CustomEvent.initCustomEvent()`** method initializes a CustomEvent object. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomEvent/initCustomEvent) @@ -6495,7 +8543,11 @@ declare var CustomEvent: { new(type: string, eventInitDict?: CustomEventInit): CustomEvent; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomStateSet) */ +/** + * The **`CustomStateSet`** interface of the Document Object Model stores a list of states for an autonomous custom element, and allows states to be added and removed from the set. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/CustomStateSet) + */ interface CustomStateSet { forEach(callbackfn: (value: string, key: string, parent: CustomStateSet) => void, thisArg?: any): void; } @@ -6506,20 +8558,29 @@ declare var CustomStateSet: { }; /** - * An abnormal event (called an exception) which occurs as a result of calling a method or accessing a property of a web API. + * The **`DOMException`** interface represents an abnormal event (called an **exception**) that occurs as a result of calling a method or accessing a property of a web API. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException) */ interface DOMException extends Error { /** + * The **`code`** read-only property of the DOMException interface returns one of the legacy error code constants, or `0` if none match. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/code) */ readonly code: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/message) */ + /** + * The **`message`** read-only property of the a message or description associated with the given error name. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/message) + */ readonly message: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/name) */ + /** + * The **`name`** read-only property of the one of the strings associated with an error name. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMException/name) + */ readonly name: string; readonly INDEX_SIZE_ERR: 1; readonly DOMSTRING_SIZE_ERR: 2; @@ -6579,18 +8640,31 @@ declare var DOMException: { }; /** - * An object providing methods which are not dependent on any particular document. Such an object is returned by the Document.implementation property. + * The **`DOMImplementation`** interface represents an object providing methods which are not dependent on any particular document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation) */ interface DOMImplementation { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation/createDocument) */ + /** + * The **`DOMImplementation.createDocument()`** method creates and returns an XMLDocument. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation/createDocument) + */ createDocument(namespace: string | null, qualifiedName: string | null, doctype?: DocumentType | null): XMLDocument; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation/createDocumentType) */ - createDocumentType(qualifiedName: string, publicId: string, systemId: string): DocumentType; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation/createHTMLDocument) */ + /** + * The **`DOMImplementation.createDocumentType()`** method returns a DocumentType object which can either be used with into the document via methods like Node.insertBefore() or ```js-nolint createDocumentType(qualifiedNameStr, publicId, systemId) ``` - `qualifiedNameStr` - : A string containing the qualified name, like `svg:svg`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation/createDocumentType) + */ + createDocumentType(name: string, publicId: string, systemId: string): DocumentType; + /** + * The **`DOMImplementation.createHTMLDocument()`** method creates a new HTML Document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation/createHTMLDocument) + */ createHTMLDocument(title?: string): Document; /** + * The **`DOMImplementation.hasFeature()`** method returns a boolean flag indicating if a given feature is supported. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMImplementation/hasFeature) @@ -6603,7 +8677,11 @@ declare var DOMImplementation: { new(): DOMImplementation; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix) */ +/** + * The **`DOMMatrix`** interface represents 4×4 matrices, suitable for 2D and 3D operations including rotation and translation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix) + */ interface DOMMatrix extends DOMMatrixReadOnly { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix#instance_properties) */ a: number; @@ -6649,33 +8727,85 @@ interface DOMMatrix extends DOMMatrixReadOnly { m43: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix#instance_properties) */ m44: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/invertSelf) */ + /** + * The **`invertSelf()`** method of the DOMMatrix interface inverts the original matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/invertSelf) + */ invertSelf(): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/multiplySelf) */ + /** + * The **`multiplySelf()`** method of the DOMMatrix interface multiplies a matrix by the `otherMatrix` parameter, computing the dot product of the original matrix and the specified matrix: `A⋅B`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/multiplySelf) + */ multiplySelf(other?: DOMMatrixInit): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/preMultiplySelf) */ + /** + * The **`preMultiplySelf()`** method of the DOMMatrix interface modifies the matrix by pre-multiplying it with the specified `DOMMatrix`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/preMultiplySelf) + */ preMultiplySelf(other?: DOMMatrixInit): DOMMatrix; + /** + * The `rotateAxisAngleSelf()` method of the DOMMatrix interface is a transformation method that rotates the source matrix by the given vector and angle, returning the altered matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/rotateAxisAngleSelf) + */ rotateAxisAngleSelf(x?: number, y?: number, z?: number, angle?: number): DOMMatrix; + /** + * The `rotateFromVectorSelf()` method of the DOMMatrix interface is a mutable transformation method that modifies a matrix by rotating the matrix by the angle between the specified vector and `(1, 0)`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/rotateFromVectorSelf) + */ rotateFromVectorSelf(x?: number, y?: number): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/rotateSelf) */ + /** + * The `rotateSelf()` method of the DOMMatrix interface is a mutable transformation method that modifies a matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/rotateSelf) + */ rotateSelf(rotX?: number, rotY?: number, rotZ?: number): DOMMatrix; + /** + * The **`scale3dSelf()`** method of the DOMMatrix interface is a mutable transformation method that modifies a matrix by applying a specified scaling factor to all three axes, centered on the given origin, with a default origin of `(0, 0, 0)`, returning the 3D-scaled matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/scale3dSelf) + */ scale3dSelf(scale?: number, originX?: number, originY?: number, originZ?: number): DOMMatrix; + /** + * The **`scaleSelf()`** method of the DOMMatrix interface is a mutable transformation method that modifies a matrix by applying a specified scaling factor, centered on the given origin, with a default origin of `(0, 0)`, returning the scaled matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/scaleSelf) + */ scaleSelf(scaleX?: number, scaleY?: number, scaleZ?: number, originX?: number, originY?: number, originZ?: number): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/setMatrixValue) */ + /** + * The **`setMatrixValue()`** method of the DOMMatrix interface replaces the contents of the matrix with the matrix described by the specified transform or transforms, returning itself. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/setMatrixValue) + */ setMatrixValue(transformList: string): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/skewXSelf) */ + /** + * The `skewXSelf()` method of the DOMMatrix interface is a mutable transformation method that modifies a matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/skewXSelf) + */ skewXSelf(sx?: number): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/skewYSelf) */ + /** + * The `skewYSelf()` method of the DOMMatrix interface is a mutable transformation method that modifies a matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/skewYSelf) + */ skewYSelf(sy?: number): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/translateSelf) */ + /** + * The `translateSelf()` method of the DOMMatrix interface is a mutable transformation method that modifies a matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrix/translateSelf) + */ translateSelf(tx?: number, ty?: number, tz?: number): DOMMatrix; } declare var DOMMatrix: { prototype: DOMMatrix; new(init?: string | number[]): DOMMatrix; - fromFloat32Array(array32: Float32Array): DOMMatrix; - fromFloat64Array(array64: Float64Array): DOMMatrix; + fromFloat32Array(array32: Float32Array): DOMMatrix; + fromFloat64Array(array64: Float64Array): DOMMatrix; fromMatrix(other?: DOMMatrixInit): DOMMatrix; }; @@ -6685,7 +8815,11 @@ declare var SVGMatrix: typeof DOMMatrix; type WebKitCSSMatrix = DOMMatrix; declare var WebKitCSSMatrix: typeof DOMMatrix; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly) */ +/** + * The **`DOMMatrixReadOnly`** interface represents a read-only 4×4 matrix, suitable for 2D and 3D operations. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly) + */ interface DOMMatrixReadOnly { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly#instance_properties) */ readonly a: number; @@ -6699,9 +8833,17 @@ interface DOMMatrixReadOnly { readonly e: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly#instance_properties) */ readonly f: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/is2D) */ + /** + * The readonly **`is2D`** property of the DOMMatrixReadOnly interface is a Boolean flag that is `true` when the matrix is 2D. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/is2D) + */ readonly is2D: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/isIdentity) */ + /** + * The readonly **`isIdentity`** property of the DOMMatrixReadOnly interface is a Boolean whose value is `true` if the matrix is the identity matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/isIdentity) + */ readonly isIdentity: boolean; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly#instance_properties) */ readonly m11: number; @@ -6735,33 +8877,103 @@ interface DOMMatrixReadOnly { readonly m43: number; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly#instance_properties) */ readonly m44: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/flipX) */ + /** + * The **`flipX()`** method of the DOMMatrixReadOnly interface creates a new matrix being the result of the original matrix flipped about the x-axis. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/flipX) + */ flipX(): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/flipY) */ + /** + * The **`flipY()`** method of the DOMMatrixReadOnly interface creates a new matrix being the result of the original matrix flipped about the y-axis. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/flipY) + */ flipY(): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/inverse) */ + /** + * The **`inverse()`** method of the DOMMatrixReadOnly interface creates a new matrix which is the inverse of the original matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/inverse) + */ inverse(): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/multiply) */ + /** + * The **`multiply()`** method of the DOMMatrixReadOnly interface creates and returns a new matrix which is the dot product of the matrix and the `otherMatrix` parameter. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/multiply) + */ multiply(other?: DOMMatrixInit): DOMMatrix; + /** + * The `rotate()` method of the DOMMatrixReadOnly interface returns a new DOMMatrix created by rotating the source matrix around each of its axes by the specified number of degrees. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/rotate) + */ rotate(rotX?: number, rotY?: number, rotZ?: number): DOMMatrix; - rotateAxisAngle(x?: number, y?: number, z?: number, angle?: number): DOMMatrix; + /** + * The `rotateAxisAngle()` method of the DOMMatrixReadOnly interface returns a new DOMMatrix created by rotating the source matrix by the given vector and angle. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/rotateAxisAngle) + */ + rotateAxisAngle(x?: number, y?: number, z?: number, angle?: number): DOMMatrix; + /** + * The `rotateFromVector()` method of the DOMMatrixReadOnly interface is returns a new DOMMatrix created by rotating the source matrix by the angle between the specified vector and `(1, 0)`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/rotateFromVector) + */ rotateFromVector(x?: number, y?: number): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/scale) */ + /** + * The **`scale()`** method of the original matrix with a scale transform applied. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/scale) + */ scale(scaleX?: number, scaleY?: number, scaleZ?: number, originX?: number, originY?: number, originZ?: number): DOMMatrix; + /** + * The **`scale3d()`** method of the DOMMatrixReadOnly interface creates a new matrix which is the result of a 3D scale transform being applied to the matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/scale3d) + */ scale3d(scale?: number, originX?: number, originY?: number, originZ?: number): DOMMatrix; /** @deprecated */ scaleNonUniform(scaleX?: number, scaleY?: number): DOMMatrix; + /** + * The `skewX()` method of the DOMMatrixReadOnly interface returns a new DOMMatrix created by applying the specified skew transformation to the source matrix along its x-axis. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/skewX) + */ skewX(sx?: number): DOMMatrix; + /** + * The `skewY()` method of the DOMMatrixReadOnly interface returns a new DOMMatrix created by applying the specified skew transformation to the source matrix along its y-axis. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/skewY) + */ skewY(sy?: number): DOMMatrix; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/toFloat32Array) */ - toFloat32Array(): Float32Array; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/toFloat64Array) */ - toFloat64Array(): Float64Array; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/toJSON) */ + /** + * The **`toFloat32Array()`** method of the DOMMatrixReadOnly interface returns a new Float32Array containing all 16 elements (`m11`, `m12`, `m13`, `m14`, `m21`, `m22`, `m23`, `m24`, `m31`, `m32`, `m33`, `m34`, `m41`, `m42`, `m43`, `m44`) which comprise the matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/toFloat32Array) + */ + toFloat32Array(): Float32Array; + /** + * The **`toFloat64Array()`** method of the DOMMatrixReadOnly interface returns a new Float64Array containing all 16 elements (`m11`, `m12`, `m13`, `m14`, `m21`, `m22`, `m23`, `m24`, `m31`, `m32`, `m33`, `m34`, `m41`, `m42`, `m43`, `m44`) which comprise the matrix. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/toFloat64Array) + */ + toFloat64Array(): Float64Array; + /** + * The **`toJSON()`** method of the DOMMatrixReadOnly interface creates and returns a JSON object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/toJSON) + */ toJSON(): any; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/transformPoint) */ + /** + * The **`transformPoint`** method of the You can also create a new `DOMPoint` by applying a matrix to a point with the DOMPointReadOnly.matrixTransform() method. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/transformPoint) + */ transformPoint(point?: DOMPointInit): DOMPoint; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/translate) */ + /** + * The `translate()` method of the DOMMatrixReadOnly interface creates a new matrix being the result of the original matrix with a translation applied. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMMatrixReadOnly/translate) + */ translate(tx?: number, ty?: number, tz?: number): DOMMatrix; toString(): string; } @@ -6769,25 +8981,19 @@ interface DOMMatrixReadOnly { declare var DOMMatrixReadOnly: { prototype: DOMMatrixReadOnly; new(init?: string | number[]): DOMMatrixReadOnly; - fromFloat32Array(array32: Float32Array): DOMMatrixReadOnly; - fromFloat64Array(array64: Float64Array): DOMMatrixReadOnly; + fromFloat32Array(array32: Float32Array): DOMMatrixReadOnly; + fromFloat64Array(array64: Float64Array): DOMMatrixReadOnly; fromMatrix(other?: DOMMatrixInit): DOMMatrixReadOnly; }; /** - * Provides the ability to parse XML or HTML source code from a string into a DOM Document. + * The **`DOMParser`** interface provides the ability to parse XML or HTML source code from a string into a DOM Document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMParser) */ interface DOMParser { /** - * Parses string using either the HTML or XML parser, according to type, and returns the resulting Document. type can be "text/html" (which will invoke the HTML parser), or any of "text/xml", "application/xml", "application/xhtml+xml", or "image/svg+xml" (which will invoke the XML parser). - * - * For the XML parser, if string cannot be parsed, then the returned Document will contain elements describing the resulting error. - * - * Note that script elements are not evaluated during parsing, and the resulting document's encoding will always be UTF-8. - * - * Values other than the above for type will cause a TypeError exception to be thrown. + * The **`parseFromString()`** method of the DOMParser interface parses a string containing either HTML or XML, returning an HTMLDocument or an XMLDocument. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMParser/parseFromString) */ @@ -6799,64 +9005,148 @@ declare var DOMParser: { new(): DOMParser; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint) */ +/** + * A **`DOMPoint`** object represents a 2D or 3D point in a coordinate system; it includes values for the coordinates in up to three dimensions, as well as an optional perspective value. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint) + */ interface DOMPoint extends DOMPointReadOnly { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/w) */ + /** + * The **`DOMPoint`** interface's **`w`** property holds the point's perspective value, w, for a point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/w) + */ w: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/x) */ + /** + * The **`DOMPoint`** interface's **`x`** property holds the horizontal coordinate, x, for a point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/x) + */ x: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/y) */ + /** + * The **`DOMPoint`** interface's **`y`** property holds the vertical coordinate, _y_, for a point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/y) + */ y: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/z) */ + /** + * The **`DOMPoint`** interface's **`z`** property specifies the depth coordinate of a point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/z) + */ z: number; } declare var DOMPoint: { prototype: DOMPoint; new(x?: number, y?: number, z?: number, w?: number): DOMPoint; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/fromPoint_static) */ + /** + * The **`fromPoint()`** static method of the DOMPoint interface creates and returns a new mutable `DOMPoint` object given a source point. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPoint/fromPoint_static) + */ fromPoint(other?: DOMPointInit): DOMPoint; }; type SVGPoint = DOMPoint; declare var SVGPoint: typeof DOMPoint; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly) */ +/** + * The **`DOMPointReadOnly`** interface specifies the coordinate and perspective fields used by DOMPoint to define a 2D or 3D point in a coordinate system. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly) + */ interface DOMPointReadOnly { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/w) */ + /** + * The **`DOMPointReadOnly`** interface's **`w`** property holds the point's perspective value, `w`, for a read-only point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/w) + */ readonly w: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/x) */ + /** + * The **`DOMPointReadOnly`** interface's **`x`** property holds the horizontal coordinate, x, for a read-only point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/x) + */ readonly x: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/y) */ + /** + * The **`DOMPointReadOnly`** interface's **`y`** property holds the vertical coordinate, y, for a read-only point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/y) + */ readonly y: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/z) */ + /** + * The **`DOMPointReadOnly`** interface's **`z`** property holds the depth coordinate, z, for a read-only point in space. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/z) + */ readonly z: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/matrixTransform) */ + /** + * The **`matrixTransform()`** method of the DOMPointReadOnly interface applies a matrix transform specified as an object to the DOMPointReadOnly object, creating and returning a new `DOMPointReadOnly` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/matrixTransform) + */ matrixTransform(matrix?: DOMMatrixInit): DOMPoint; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/toJSON) */ + /** + * The DOMPointReadOnly method `toJSON()` returns an object giving the ```js-nolint toJSON() ``` None. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/toJSON) + */ toJSON(): any; } declare var DOMPointReadOnly: { prototype: DOMPointReadOnly; new(x?: number, y?: number, z?: number, w?: number): DOMPointReadOnly; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/fromPoint_static) */ + /** + * The static **DOMPointReadOnly** method `fromPoint()` creates and returns a new `DOMPointReadOnly` object given a source point. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMPointReadOnly/fromPoint_static) + */ fromPoint(other?: DOMPointInit): DOMPointReadOnly; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad) */ +/** + * A `DOMQuad` is a collection of four `DOMPoint`s defining the corners of an arbitrary quadrilateral. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad) + */ interface DOMQuad { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p1) */ + /** + * The **`DOMQuad`** interface's **`p1`** property holds the DOMPoint object that represents one of the four corners of the `DOMQuad`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p1) + */ readonly p1: DOMPoint; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p2) */ + /** + * The **`DOMQuad`** interface's **`p2`** property holds the DOMPoint object that represents one of the four corners of the `DOMQuad`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p2) + */ readonly p2: DOMPoint; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p3) */ + /** + * The **`DOMQuad`** interface's **`p3`** property holds the DOMPoint object that represents one of the four corners of the `DOMQuad`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p3) + */ readonly p3: DOMPoint; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p4) */ + /** + * The **`DOMQuad`** interface's **`p4`** property holds the DOMPoint object that represents one of the four corners of the `DOMQuad`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/p4) + */ readonly p4: DOMPoint; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/getBounds) */ + /** + * The DOMQuad method `getBounds()` returns a DOMRect object representing the smallest rectangle that fully contains the `DOMQuad` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/getBounds) + */ getBounds(): DOMRect; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/toJSON) */ + /** + * The DOMQuad method `toJSON()` returns a ```js-nolint toJSON() ``` None. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMQuad/toJSON) + */ toJSON(): any; } @@ -6867,33 +9157,69 @@ declare var DOMQuad: { fromRect(other?: DOMRectInit): DOMQuad; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect) */ +/** + * A **`DOMRect`** describes the size and position of a rectangle. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect) + */ interface DOMRect extends DOMRectReadOnly { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/height) */ + /** + * The **`height`** property of the DOMRect interface represents the height of the rectangle. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/height) + */ height: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/width) */ + /** + * The **`width`** property of the DOMRect interface represents the width of the rectangle. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/width) + */ width: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/x) */ + /** + * The **`x`** property of the DOMRect interface represents the x-coordinate of the rectangle, which is the horizontal distance between the viewport's left edge and the rectangle's origin. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/x) + */ x: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/y) */ + /** + * The **`y`** property of the DOMRect interface represents the y-coordinate of the rectangle, which is the vertical distance between the viewport's top edge and the rectangle's origin. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/y) + */ y: number; } declare var DOMRect: { prototype: DOMRect; new(x?: number, y?: number, width?: number, height?: number): DOMRect; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/fromRect_static) */ + /** + * The **`fromRect()`** static method of the object with a given location and dimensions. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRect/fromRect_static) + */ fromRect(other?: DOMRectInit): DOMRect; }; type SVGRect = DOMRect; declare var SVGRect: typeof DOMRect; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectList) */ +/** + * The **`DOMRectList`** interface represents a collection of DOMRect objects, typically used to hold the rectangles associated with a particular element, like bounding boxes returned by methods such as Element.getClientRects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectList) + */ interface DOMRectList { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectList/length) */ + /** + * The read-only **`length`** property of the DOMRectList interface returns the number of DOMRect objects in the list. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectList/length) + */ readonly length: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectList/item) */ + /** + * The DOMRectList method `item()` returns the DOMRect at the specified index within the list, or `null` if the index is out of range. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectList/item) + */ item(index: number): DOMRect | null; [index: number]: DOMRect; } @@ -6903,55 +9229,99 @@ declare var DOMRectList: { new(): DOMRectList; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly) */ +/** + * The **`DOMRectReadOnly`** interface specifies the standard properties (also used by DOMRect) to define a rectangle whose properties are immutable. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly) + */ interface DOMRectReadOnly { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/bottom) */ + /** + * The **`bottom`** read-only property of the **`DOMRectReadOnly`** interface returns the bottom coordinate value of the `DOMRect`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/bottom) + */ readonly bottom: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/height) */ + /** + * The **`height`** read-only property of the **`DOMRectReadOnly`** interface represents the height of the `DOMRect`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/height) + */ readonly height: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/left) */ + /** + * The **`left`** read-only property of the **`DOMRectReadOnly`** interface returns the left coordinate value of the `DOMRect`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/left) + */ readonly left: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/right) */ + /** + * The **`right`** read-only property of the **`DOMRectReadOnly`** interface returns the right coordinate value of the `DOMRect`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/right) + */ readonly right: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/top) */ + /** + * The **`top`** read-only property of the **`DOMRectReadOnly`** interface returns the top coordinate value of the `DOMRect`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/top) + */ readonly top: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/width) */ + /** + * The **`width`** read-only property of the **`DOMRectReadOnly`** interface represents the width of the `DOMRect`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/width) + */ readonly width: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/x) */ + /** + * The **`x`** read-only property of the **`DOMRectReadOnly`** interface represents the x coordinate of the `DOMRect`'s origin. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/x) + */ readonly x: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/y) */ + /** + * The **`y`** read-only property of the **`DOMRectReadOnly`** interface represents the y coordinate of the `DOMRect`'s origin. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/y) + */ readonly y: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/toJSON) */ + /** + * The DOMRectReadOnly method `toJSON()` returns a JSON representation of the `DOMRectReadOnly` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/toJSON) + */ toJSON(): any; } declare var DOMRectReadOnly: { prototype: DOMRectReadOnly; new(x?: number, y?: number, width?: number, height?: number): DOMRectReadOnly; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/fromRect_static) */ + /** + * The **`fromRect()`** static method of the object with a given location and dimensions. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMRectReadOnly/fromRect_static) + */ fromRect(other?: DOMRectInit): DOMRectReadOnly; }; /** - * A type returned by some APIs which contains a list of DOMString (strings). + * The **`DOMStringList`** interface is a legacy type returned by some APIs and represents a non-modifiable list of strings (`DOMString`). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMStringList) */ interface DOMStringList { /** - * Returns the number of strings in strings. + * The read-only **`length`** property indicates the number of strings in the DOMStringList. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMStringList/length) */ readonly length: number; /** - * Returns true if strings contains string, and false otherwise. + * The **`contains()`** method returns a boolean indicating whether the given string is in the list. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMStringList/contains) */ contains(string: string): boolean; /** - * Returns the string with index index from strings. + * The **`item()`** method returns a string from a `DOMStringList` by index. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMStringList/item) */ @@ -6965,7 +9335,7 @@ declare var DOMStringList: { }; /** - * Used by the dataset HTML attribute to represent data for custom attributes added to elements. + * The **`DOMStringMap`** interface is used for the HTMLElement.dataset attribute, to represent data for custom attributes added to elements. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMStringMap) */ @@ -6979,86 +9349,62 @@ declare var DOMStringMap: { }; /** - * A set of space-separated tokens. Such a set is returned by Element.classList, HTMLLinkElement.relList, HTMLAnchorElement.relList, HTMLAreaElement.relList, HTMLIframeElement.sandbox, or HTMLOutputElement.htmlFor. It is indexed beginning with 0 as with JavaScript Array objects. DOMTokenList is always case-sensitive. + * The **`DOMTokenList`** interface represents a set of space-separated tokens. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList) */ interface DOMTokenList { /** - * Returns the number of tokens. + * The read-only **`length`** property of the DOMTokenList interface is an `integer` representing the number of objects stored in the object. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/length) */ readonly length: number; /** - * Returns the associated set as string. - * - * Can be set, to change the associated attribute. + * The **`value`** property of the DOMTokenList interface is a stringifier that returns the value of the list serialized as a string, or clears and sets the list to the given value. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/value) */ value: string; toString(): string; /** - * Adds all arguments passed, except those already present. - * - * Throws a "SyntaxError" DOMException if one of the arguments is the empty string. - * - * Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace. + * The **`add()`** method of the DOMTokenList interface adds the given tokens to the list, omitting any that are already present. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/add) */ add(...tokens: string[]): void; /** - * Returns true if token is present, and false otherwise. + * The **`contains()`** method of the DOMTokenList interface returns a boolean value — `true` if the underlying list contains the given token, otherwise `false`. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/contains) */ contains(token: string): boolean; /** - * Returns the token with index index. + * The **`item()`** method of the DOMTokenList interface returns an item in the list, determined by its position in the list, its index. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/item) */ item(index: number): string | null; /** - * Removes arguments passed, if they are present. - * - * Throws a "SyntaxError" DOMException if one of the arguments is the empty string. - * - * Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace. + * The **`remove()`** method of the DOMTokenList interface removes the specified _tokens_ from the list. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/remove) */ remove(...tokens: string[]): void; /** - * Replaces token with newToken. - * - * Returns true if token was replaced with newToken, and false otherwise. - * - * Throws a "SyntaxError" DOMException if one of the arguments is the empty string. - * - * Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace. + * The **`replace()`** method of the DOMTokenList interface replaces an existing token with a new token. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/replace) */ replace(token: string, newToken: string): boolean; /** - * Returns true if token is in the associated attribute's supported tokens. Returns false otherwise. - * - * Throws a TypeError if the associated attribute has no supported tokens defined. + * The **`supports()`** method of the DOMTokenList interface returns `true` if a given `token` is in the associated attribute's supported tokens. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/supports) */ supports(token: string): boolean; /** - * If force is not given, "toggles" token, removing it if it's present and adding it if it's not present. If force is true, adds token (same as add()). If force is false, removes token (same as remove()). - * - * Returns true if token is now present, and false otherwise. - * - * Throws a "SyntaxError" DOMException if token is empty. - * - * Throws an "InvalidCharacterError" DOMException if token contains any spaces. + * The **`toggle()`** method of the DOMTokenList interface removes an existing token from the list and returns `false`. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DOMTokenList/toggle) */ @@ -7073,69 +9419,61 @@ declare var DOMTokenList: { }; /** - * Used to hold the data that is being dragged during a drag and drop operation. It may hold one or more data items, each of one or more data types. For more information about drag and drop, see HTML Drag and Drop API. + * The **`DataTransfer`** object is used to hold any data transferred between contexts, such as a drag and drop operation, or clipboard read/write. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer) */ interface DataTransfer { /** - * Returns the kind of operation that is currently selected. If the kind of operation isn't one of those that is allowed by the effectAllowed attribute, then the operation will fail. - * - * Can be set, to change the selected operation. - * - * The possible values are "none", "copy", "link", and "move". + * The **`DataTransfer.dropEffect`** property controls the feedback (typically visual) the user is given during a drag and drop operation. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/dropEffect) */ dropEffect: "none" | "copy" | "link" | "move"; /** - * Returns the kinds of operations that are to be allowed. - * - * Can be set (during the dragstart event), to change the allowed operations. - * - * The possible values are "none", "copy", "copyLink", "copyMove", "link", "linkMove", "move", "all", and "uninitialized", + * The **`DataTransfer.effectAllowed`** property specifies the effect that is allowed for a drag operation. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/effectAllowed) */ effectAllowed: "none" | "copy" | "copyLink" | "copyMove" | "link" | "linkMove" | "move" | "all" | "uninitialized"; /** - * Returns a FileList of the files being dragged, if any. + * The **`files`** read-only property of `DataTransfer` objects is a list of the files in the drag operation. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/files) */ readonly files: FileList; /** - * Returns a DataTransferItemList object, with the drag data. + * The read-only `items` property of the DataTransfer interface is a A DataTransferItemList object containing DataTransferItem objects representing the items being dragged in a drag operation, one list item for each object being dragged. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/items) */ readonly items: DataTransferItemList; /** - * Returns a frozen array listing the formats that were set in the dragstart event. In addition, if any files are being dragged, then one of the types will be the string "Files". + * The **`DataTransfer.types`** read-only property returns the available types that exist in the DataTransfer.items. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/types) */ readonly types: ReadonlyArray; /** - * Removes the data of the specified formats. Removes all data if the argument is omitted. + * The **`DataTransfer.clearData()`** method removes the drag operation's drag data for the given type. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/clearData) */ clearData(format?: string): void; /** - * Returns the specified data. If there is no such data, returns the empty string. + * The **`DataTransfer.getData()`** method retrieves drag data (as a string) for the specified type. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/getData) */ getData(format: string): string; /** - * Adds the specified data. + * The **`DataTransfer.setData()`** method sets the drag operation's drag data to the specified data and type. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/setData) */ setData(format: string, data: string): void; /** - * Uses the given element to update the drag feedback, replacing any previously specified feedback. + * When a drag occurs, a translucent image is generated from the drag target (the element the HTMLElement/dragstart_event event is fired at), and follows the mouse pointer during the drag. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransfer/setDragImage) */ @@ -7148,36 +9486,40 @@ declare var DataTransfer: { }; /** - * One drag data item. During a drag operation, each drag event has a dataTransfer property which contains a list of drag data items. Each item in the list is a DataTransferItem object. + * The **`DataTransferItem`** object represents one drag data item. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItem) */ interface DataTransferItem { /** - * Returns the drag data item kind, one of: "string", "file". + * The read-only **`DataTransferItem.kind`** property returns the kind–a string or a file–of the DataTransferItem object representing the _drag data item_. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItem/kind) */ readonly kind: string; /** - * Returns the drag data item type string. + * The read-only **`DataTransferItem.type`** property returns the type (format) of the DataTransferItem object representing the drag data item. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItem/type) */ readonly type: string; /** - * Returns a File object, if the drag data item kind is File. + * If the item is a file, the **`DataTransferItem.getAsFile()`** method returns the drag data item's File object. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItem/getAsFile) */ getAsFile(): File | null; /** - * Invokes the callback with the string data as the argument, if the drag data item kind is text. + * The **`DataTransferItem.getAsString()`** method invokes the given callback with the drag data item's string data as the argument if the item's DataTransferItem.kind is a _Plain unicode string_ (i.e., `kind` is `string`). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItem/getAsString) */ getAsString(callback: FunctionStringCallback | null): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItem/webkitGetAsEntry) */ + /** + * If the item described by the DataTransferItem is a file, `webkitGetAsEntry()` returns a FileSystemFileEntry or FileSystemDirectoryEntry representing it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItem/webkitGetAsEntry) + */ webkitGetAsEntry(): FileSystemEntry | null; } @@ -7187,32 +9529,32 @@ declare var DataTransferItem: { }; /** - * A list of DataTransferItem objects representing items being dragged. During a drag operation, each DragEvent has a dataTransfer property and that property is a DataTransferItemList. + * The **`DataTransferItemList`** object is a list of DataTransferItem objects representing items being dragged. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItemList) */ interface DataTransferItemList { /** - * Returns the number of items in the drag data store. + * The read-only **`length`** property of the the drag item list. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItemList/length) */ readonly length: number; /** - * Adds a new entry for the given data to the drag data store. If the data is plain text then a type string has to be provided also. + * The **`DataTransferItemList.add()`** method creates a new list. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItemList/add) */ add(data: string, type: string): DataTransferItem | null; add(data: File): DataTransferItem | null; /** - * Removes all the entries in the drag data store. + * The DataTransferItemList method **`clear()`** removes all DataTransferItem objects from the drag data items list, leaving the list empty. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItemList/clear) */ clear(): void; /** - * Removes the indexth entry in the drag data store. + * The **`DataTransferItemList.remove()`** method removes the less than zero or greater than one less than the length of the list, the list will not be changed. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DataTransferItemList/remove) */ @@ -7225,9 +9567,13 @@ declare var DataTransferItemList: { new(): DataTransferItemList; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DecompressionStream) */ +/** + * The **`DecompressionStream`** interface of the Compression Streams API is an API for decompressing a stream of data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DecompressionStream) + */ interface DecompressionStream extends GenericTransformStream { - readonly readable: ReadableStream; + readonly readable: ReadableStream>; readonly writable: WritableStream; } @@ -7237,12 +9583,16 @@ declare var DecompressionStream: { }; /** - * A delay-line; an AudioNode audio-processing module that causes a delay between the arrival of an input data and its propagation to the output. + * The **`DelayNode`** interface represents a delay-line; an AudioNode audio-processing module that causes a delay between the arrival of an input data and its propagation to the output. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DelayNode) */ interface DelayNode extends AudioNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DelayNode/delayTime) */ + /** + * The `delayTime` property of the DelayNode interface is an a-rate AudioParam representing the amount of delay to apply. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DelayNode/delayTime) + */ readonly delayTime: AudioParam; } @@ -7252,19 +9602,35 @@ declare var DelayNode: { }; /** - * The DeviceMotionEvent provides web developers with information about the speed of changes for the device's position and orientation. + * The **`DeviceMotionEvent`** interface of the Device Orientation Events provides web developers with information about the speed of changes for the device's position and orientation. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent) */ interface DeviceMotionEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/acceleration) */ + /** + * The **`acceleration`** read-only property of the DeviceMotionEvent interface returns the acceleration recorded by the device, in meters per second squared (m/s²). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/acceleration) + */ readonly acceleration: DeviceMotionEventAcceleration | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/accelerationIncludingGravity) */ + /** + * The **`accelerationIncludingGravity`** read-only property of the DeviceMotionEvent interface returns the amount of acceleration recorded by the device, in meters per second squared (m/s²). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/accelerationIncludingGravity) + */ readonly accelerationIncludingGravity: DeviceMotionEventAcceleration | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/interval) */ + /** + * The **`interval`** read-only property of the DeviceMotionEvent interface returns the interval, in milliseconds, at which data is obtained from the underlying hardware. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/interval) + */ readonly interval: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/rotationRate) */ + /** + * The **`rotationRate`** read-only property of the DeviceMotionEvent interface returns the rate at which the device is rotating around each of its axes in degrees per second. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEvent/rotationRate) + */ readonly rotationRate: DeviceMotionEventRotationRate | null; } @@ -7274,47 +9640,89 @@ declare var DeviceMotionEvent: { }; /** + * The **`DeviceMotionEventAcceleration`** interface of the Device Orientation Events provides information about the amount of acceleration the device is experiencing along all three axes. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventAcceleration) */ interface DeviceMotionEventAcceleration { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventAcceleration/x) */ + /** + * The **`x`** read-only property of the DeviceMotionEventAcceleration interface indicates the amount of acceleration that occurred along the X axis in a `DeviceMotionEventAcceleration` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventAcceleration/x) + */ readonly x: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventAcceleration/y) */ + /** + * The **`y`** read-only property of the DeviceMotionEventAcceleration interface indicates the amount of acceleration that occurred along the Y axis in a `DeviceMotionEventAcceleration` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventAcceleration/y) + */ readonly y: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventAcceleration/z) */ + /** + * The **`z`** read-only property of the DeviceMotionEventAcceleration interface indicates the amount of acceleration that occurred along the Z axis in a `DeviceMotionEventAcceleration` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventAcceleration/z) + */ readonly z: number | null; } /** + * A **`DeviceMotionEventRotationRate`** interface of the Device Orientation Events provides information about the rate at which the device is rotating around all three axes. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventRotationRate) */ interface DeviceMotionEventRotationRate { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventRotationRate/alpha) */ + /** + * The **`alpha`** read-only property of the DeviceMotionEventRotationRate interface indicates the rate of rotation around the Z axis, in degrees per second. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventRotationRate/alpha) + */ readonly alpha: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventRotationRate/beta) */ + /** + * The **`beta`** read-only property of the DeviceMotionEventRotationRate interface indicates the rate of rotation around the X axis, in degrees per second. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventRotationRate/beta) + */ readonly beta: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventRotationRate/gamma) */ + /** + * The **`gamma`** read-only property of the DeviceMotionEventRotationRate interface indicates the rate of rotation around the Y axis, in degrees per second. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceMotionEventRotationRate/gamma) + */ readonly gamma: number | null; } /** - * The DeviceOrientationEvent provides web developers with information from the physical orientation of the device running the web page. + * The **`DeviceOrientationEvent`** interface of the Device Orientation Events provides web developers with information from the physical orientation of the device running the web page. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent) */ interface DeviceOrientationEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/absolute) */ + /** + * The **`absolute`** read-only property of the DeviceOrientationEvent interface indicates whether or not the device is providing orientation data absolutely (that is, in reference to the Earth's coordinate frame) or using some arbitrary frame determined by the device. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/absolute) + */ readonly absolute: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/alpha) */ + /** + * The **`alpha`** read-only property of the DeviceOrientationEvent interface returns the rotation of the device around the Z axis; that is, the number of degrees by which the device is being twisted around the center of the screen. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/alpha) + */ readonly alpha: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/beta) */ + /** + * The **`beta`** read-only property of the DeviceOrientationEvent interface returns the rotation of the device around the X axis; that is, the number of degrees, ranged between -180 and 180, by which the device is tipped forward or backward. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/beta) + */ readonly beta: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/gamma) */ + /** + * The **`gamma`** read-only property of the DeviceOrientationEvent interface returns the rotation of the device around the Y axis; that is, the number of degrees, ranged between `-90` and `90`, by which the device is tilted left or right. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DeviceOrientationEvent/gamma) + */ readonly gamma: number | null; } @@ -7334,225 +9742,226 @@ interface DocumentEventMap extends GlobalEventHandlersEventMap { } /** - * Any web page loaded in the browser and serves as an entry point into the web page's content, which is the DOM tree. + * The **`Document`** interface represents any web page loaded in the browser and serves as an entry point into the web page's content, which is the DOM tree. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document) */ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEventHandlers, NonElementParentNode, ParentNode, XPathEvaluatorBase { /** - * Sets or gets the URL for the current document. + * The **`URL`** read-only property of the Document interface returns the document location as a string. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/URL) */ readonly URL: string; /** - * Sets or gets the color of all active links in the document. + * Returns or sets the color of an active link in the document body. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/alinkColor) */ alinkColor: string; /** - * Returns a reference to the collection of elements contained by the object. + * The Document interface's read-only **`all`** property returns an HTMLAllCollection rooted at the document node. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/all) */ readonly all: HTMLAllCollection; /** - * Retrieves a collection of all a objects that have a name and/or id property. Objects in this collection are in HTML source order. + * The **`anchors`** read-only property of the An HTMLCollection. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/anchors) */ readonly anchors: HTMLCollectionOf; /** - * Retrieves a collection of all applet objects in the document. + * The **`applets`** property of the Document returns an empty HTMLCollection. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/applets) */ readonly applets: HTMLCollection; /** - * Deprecated. Sets or retrieves a value that indicates the background color behind the object. + * The deprecated `bgColor` property gets or sets the background color of the current document. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/bgColor) */ bgColor: string; /** - * Specifies the beginning and end of the document body. + * The **`Document.body`** property represents the `null` if no such element exists. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/body) */ body: HTMLElement; /** - * Returns document's encoding. + * The **`Document.characterSet`** read-only property returns the character encoding of the document that it's currently rendered with. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/characterSet) */ readonly characterSet: string; /** - * Gets or sets the character set used to encode the object. * @deprecated This is a legacy alias of `characterSet`. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/characterSet) */ readonly charset: string; /** - * Gets a value that indicates whether standards-compliant mode is switched on for the object. + * The **`Document.compatMode`** read-only property indicates whether the document is rendered in Quirks mode or Standards mode. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/compatMode) */ readonly compatMode: string; /** - * Returns document's content type. + * The **`Document.contentType`** read-only property returns the MIME type that the document is being rendered as. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/contentType) */ readonly contentType: string; /** - * Returns the HTTP cookies that apply to the Document. If there are no cookies or cookies can't be applied to this resource, the empty string will be returned. - * - * Can be set, to add a new cookie to the element's set of HTTP cookies. - * - * If the contents are sandboxed into a unique origin (e.g. in an iframe with the sandbox attribute), a "SecurityError" DOMException will be thrown on getting and setting. + * The Document property `cookie` lets you read and write cookies associated with the document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/cookie) */ cookie: string; /** - * Returns the script element, or the SVG script element, that is currently executing, as long as the element represents a classic script. In the case of reentrant script execution, returns the one that most recently started executing amongst those that have not yet finished executing. - * - * Returns null if the Document is not currently executing a script or SVG script element (e.g., because the running script is an event handler, or a timeout), or if the currently executing script or SVG script element represents a module script. + * The **`Document.currentScript`** property returns the script element whose script is currently being processed and isn't a JavaScript module. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/currentScript) */ readonly currentScript: HTMLOrSVGScriptElement | null; /** - * Returns the Window object of the active document. + * In browsers, **`document.defaultView`** returns the This property is read-only. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/defaultView) */ readonly defaultView: (WindowProxy & typeof globalThis) | null; /** - * Sets or gets a value that indicates whether the document can be edited. + * **`document.designMode`** controls whether the entire document is editable. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/designMode) */ designMode: string; /** - * Sets or retrieves a value that indicates the reading order of the object. + * The **`Document.dir`** property is a string representing the directionality of the text of the document, whether left to right (default) or right to left. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/dir) */ dir: string; /** - * Gets an object representing the document type declaration associated with the current document. + * The **`doctype`** read-only property of the Document interface is a DocumentType object representing the Doctype associated with the current document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/doctype) */ readonly doctype: DocumentType | null; /** - * Gets a reference to the root node of the document. + * The **`documentElement`** read-only property of the Document interface returns the example, the html element for HTML documents). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/documentElement) */ readonly documentElement: HTMLElement; /** - * Returns document's URL. + * The **`documentURI`** read-only property of the A string. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/documentURI) */ readonly documentURI: string; /** - * Sets or gets the security domain of the document. + * The **`domain`** property of the Document interface gets/sets the domain portion of the origin of the current document, as used by the same-origin policy. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/domain) */ domain: string; /** - * Retrieves a collection of all embed objects in the document. + * The **`embeds`** read-only property of the An HTMLCollection. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/embeds) */ readonly embeds: HTMLCollectionOf; /** - * Sets or gets the foreground (text) color of the document. + * **`fgColor`** gets/sets the foreground color, or text color, of the current document. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/fgColor) */ fgColor: string; /** - * Retrieves a collection, in source order, of all form objects in the document. + * The **`forms`** read-only property of the Document interface returns an HTMLCollection listing all the form elements contained in the document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/forms) */ readonly forms: HTMLCollectionOf; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/fragmentDirective) */ + /** + * The **`fragmentDirective`** read-only property of the Document interface returns the FragmentDirective for the current document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/fragmentDirective) + */ readonly fragmentDirective: FragmentDirective; /** + * The obsolete Document interface's **`fullscreen`** read-only property reports whether or not the document is currently displaying content in fullscreen mode. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/fullscreen) */ readonly fullscreen: boolean; /** - * Returns true if document has the ability to display elements fullscreen and fullscreen is supported, or false otherwise. + * The read-only **`fullscreenEnabled`** property on the Document interface indicates whether or not fullscreen mode is available. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/fullscreenEnabled) */ readonly fullscreenEnabled: boolean; /** - * Returns the head element. + * The **`head`** read-only property of the Document interface returns the head element of the current document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/head) */ readonly head: HTMLHeadElement; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/hidden) */ + /** + * The **`Document.hidden`** read-only property returns a Boolean value indicating if the page is considered hidden or not. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/hidden) + */ readonly hidden: boolean; /** - * Retrieves a collection, in source order, of img objects in the document. + * The **`images`** read-only property of the Document interface returns a collection of the images in the current HTML document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/images) */ readonly images: HTMLCollectionOf; /** - * Gets the implementation object of the current document. + * The **`Document.implementation`** property returns a A DOMImplementation object. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/implementation) */ readonly implementation: DOMImplementation; /** - * Returns the character encoding used to create the webpage that is loaded into the document object. * @deprecated This is a legacy alias of `characterSet`. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/characterSet) */ readonly inputEncoding: string; /** - * Gets the date that the page was last modified, if the page supplies one. + * The **`lastModified`** property of the Document interface returns a string containing the date and local time on which the current document was last modified. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/lastModified) */ readonly lastModified: string; /** - * Sets or gets the color of the document links. + * The **`Document.linkColor`** property gets/sets the color of links within the document. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/linkColor) */ linkColor: string; /** - * Retrieves a collection of all a objects that specify the href property and all area objects in the document. + * The **`links`** read-only property of the Document interface returns a collection of all area elements and a elements in a document with a value for the href attribute. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/links) */ readonly links: HTMLCollectionOf; /** - * Contains information about the current URL. + * The **`Document.location`** read-only property returns a and provides methods for changing that URL and loading another URL. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/location) */ @@ -7566,124 +9975,140 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve onpointerlockchange: ((this: Document, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/pointerlockerror_event) */ onpointerlockerror: ((this: Document, ev: Event) => any) | null; - /** - * Fires when the state of the object has changed. - * @param ev The event - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/readystatechange_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/readystatechange_event) */ onreadystatechange: ((this: Document, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/visibilitychange_event) */ onvisibilitychange: ((this: Document, ev: Event) => any) | null; readonly ownerDocument: null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/pictureInPictureEnabled) */ + /** + * The read-only **`pictureInPictureEnabled`** property of the available. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/pictureInPictureEnabled) + */ readonly pictureInPictureEnabled: boolean; /** - * Return an HTMLCollection of the embed elements in the Document. + * The **`plugins`** read-only property of the containing one or more HTMLEmbedElements representing the An HTMLCollection. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/plugins) */ readonly plugins: HTMLCollectionOf; /** - * Retrieves a value that indicates the current state of the object. + * The **`Document.readyState`** property describes the loading state of the document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/readyState) */ readonly readyState: DocumentReadyState; /** - * Gets the URL of the location that referred the user to the current page. + * The **`Document.referrer`** property returns the URI of the page that linked to this page. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/referrer) */ readonly referrer: string; /** + * **`Document.rootElement`** returns the Element that is the root element of the document if it is an documents. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/rootElement) */ readonly rootElement: SVGSVGElement | null; /** - * Retrieves a collection of all script objects in the document. + * The **`scripts`** property of the Document interface returns a list of the script elements in the document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/scripts) */ readonly scripts: HTMLCollectionOf; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/scrollingElement) */ + /** + * The **`scrollingElement`** read-only property of the scrolls the document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/scrollingElement) + */ readonly scrollingElement: Element | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/timeline) */ + /** + * The `timeline` readonly property of the Document interface represents the default timeline of the current document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/timeline) + */ readonly timeline: DocumentTimeline; /** - * Contains the title of the document. + * The **`document.title`** property gets or sets the current title of the document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/title) */ title: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/visibilityState) */ + /** + * The **`Document.visibilityState`** read-only property returns the visibility of the document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/visibilityState) + */ readonly visibilityState: DocumentVisibilityState; /** - * Sets or gets the color of the links that the user has visited. + * The **`Document.vlinkColor`** property gets/sets the color of links that the user has visited in the document. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/vlinkColor) */ vlinkColor: string; /** - * Moves node from another document and returns it. - * - * If node is a document, throws a "NotSupportedError" DOMException or, if node is a shadow root, throws a "HierarchyRequestError" DOMException. + * **`Document.adoptNode()`** transfers a node/dom from another Document into the method's document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/adoptNode) */ adoptNode(node: T): T; /** @deprecated */ captureEvents(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/caretPositionFromPoint) */ + /** + * The **`caretPositionFromPoint()`** method of the Document interface returns a CaretPosition object, containing the DOM node, along with the caret and caret's character offset within that node. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/caretPositionFromPoint) + */ caretPositionFromPoint(x: number, y: number, options?: CaretPositionFromPointOptions): CaretPosition | null; /** @deprecated */ caretRangeFromPoint(x: number, y: number): Range | null; /** + * The **`Document.clear()`** method does nothing, but doesn't raise any error. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/clear) */ clear(): void; /** - * Closes an output stream and forces the sent data to display. + * The **`Document.close()`** method finishes writing to a document, opened with Document.open(). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/close) */ close(): void; /** - * Creates an attribute object with a specified name. - * @param name String that sets the attribute object's name. + * The **`Document.createAttribute()`** method creates a new attribute node, and returns it. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createAttribute) */ createAttribute(localName: string): Attr; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createAttributeNS) */ - createAttributeNS(namespace: string | null, qualifiedName: string): Attr; /** - * Returns a CDATASection node whose data is data. + * The **`Document.createAttributeNS()`** method creates a new attribute node with the specified namespace URI and qualified name, and returns it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createAttributeNS) + */ + createAttributeNS(namespace: string | null, qualifiedName: string): Attr; + /** + * **`createCDATASection()`** creates a new CDATA section node, and returns it. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createCDATASection) */ createCDATASection(data: string): CDATASection; /** - * Creates a comment object with the specified data. - * @param data Sets the comment object's data. + * **`createComment()`** creates a new comment node, and returns it. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createComment) */ createComment(data: string): Comment; /** - * Creates a new document. + * Creates a new empty DocumentFragment into which DOM nodes can be added to build an offscreen DOM tree. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createDocumentFragment) */ createDocumentFragment(): DocumentFragment; /** - * Creates an instance of the element for the specified tag. - * @param tagName The name of an element. + * In an HTML document, the **`document.createElement()`** method creates the HTML element specified by `localName`, or an HTMLUnknownElement if `localName` isn't recognized. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createElement) */ @@ -7692,19 +10117,7 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve createElement(tagName: K, options?: ElementCreationOptions): HTMLElementDeprecatedTagNameMap[K]; createElement(tagName: string, options?: ElementCreationOptions): HTMLElement; /** - * Returns an element with namespace namespace. Its namespace prefix will be everything before ":" (U+003E) in qualifiedName or null. Its local name will be everything after ":" (U+003E) in qualifiedName or qualifiedName. - * - * If localName does not match the Name production an "InvalidCharacterError" DOMException will be thrown. - * - * If one of the following conditions is true a "NamespaceError" DOMException will be thrown: - * - * localName does not match the QName production. - * Namespace prefix is not null and namespace is the empty string. - * Namespace prefix is "xml" and namespace is not the XML namespace. - * qualifiedName or namespace prefix is "xmlns" and namespace is not the XMLNS namespace. - * namespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is "xmlns". - * - * When supplied, options's is can be used to create a customized built-in element. + * Creates an element with the specified namespace URI and qualified name. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createElementNS) */ @@ -7716,6 +10129,7 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve createElementNS(namespaceURI: string | null, qualifiedName: string, options?: ElementCreationOptions): Element; createElementNS(namespace: string | null, qualifiedName: string, options?: string | ElementCreationOptions): Element; /** + * Creates an event of the type specified. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createEvent) @@ -7729,6 +10143,7 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve createEvent(eventInterface: "CloseEvent"): CloseEvent; createEvent(eventInterface: "CompositionEvent"): CompositionEvent; createEvent(eventInterface: "ContentVisibilityAutoStateChangeEvent"): ContentVisibilityAutoStateChangeEvent; + createEvent(eventInterface: "CookieChangeEvent"): CookieChangeEvent; createEvent(eventInterface: "CustomEvent"): CustomEvent; createEvent(eventInterface: "DeviceMotionEvent"): DeviceMotionEvent; createEvent(eventInterface: "DeviceOrientationEvent"): DeviceOrientationEvent; @@ -7786,83 +10201,75 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve createEvent(eventInterface: "WheelEvent"): WheelEvent; createEvent(eventInterface: string): Event; /** - * Creates a NodeIterator object that you can use to traverse filtered lists of nodes or elements in a document. - * @param root The root element or node to start traversing on. - * @param whatToShow The type of nodes or elements to appear in the node list - * @param filter A custom NodeFilter function to use. For more information, see filter. Use null for no filter. + * The **`Document.createNodeIterator()`** method returns a new `NodeIterator` object. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createNodeIterator) */ createNodeIterator(root: Node, whatToShow?: number, filter?: NodeFilter | null): NodeIterator; /** - * Returns a ProcessingInstruction node whose target is target and data is data. If target does not match the Name production an "InvalidCharacterError" DOMException will be thrown. If data contains "?>" an "InvalidCharacterError" DOMException will be thrown. + * `createProcessingInstruction()` generates a new processing instruction node and returns it. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createProcessingInstruction) */ createProcessingInstruction(target: string, data: string): ProcessingInstruction; /** - * Returns an empty range object that has both of its boundary points positioned at the beginning of the document. + * The **`Document.createRange()`** method returns a new ```js-nolint createRange() ``` None. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createRange) */ createRange(): Range; /** - * Creates a text string from the specified value. - * @param data String that specifies the nodeValue property of the text node. + * Creates a new Text node. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createTextNode) */ createTextNode(data: string): Text; /** - * Creates a TreeWalker object that you can use to traverse filtered lists of nodes or elements in a document. - * @param root The root element or node to start traversing on. - * @param whatToShow The type of nodes or elements to appear in the node list. For more information, see whatToShow. - * @param filter A custom NodeFilter function to use. + * The **`Document.createTreeWalker()`** creator method returns a newly created TreeWalker object. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/createTreeWalker) */ createTreeWalker(root: Node, whatToShow?: number, filter?: NodeFilter | null): TreeWalker; /** - * Executes a command on the current document, current selection, or the given range. - * @param commandId String that specifies the command to execute. This command can be any of the command identifiers that can be executed in script. - * @param showUI Display the user interface, defaults to false. - * @param value Value to assign. + * The **`execCommand`** method implements multiple different commands. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/execCommand) */ execCommand(commandId: string, showUI?: boolean, value?: string): boolean; /** - * Stops document's fullscreen element from being displayed fullscreen and resolves promise when done. + * The Document method **`exitFullscreen()`** requests that the element on this document which is currently being presented in fullscreen mode be taken out of fullscreen mode, restoring the previous state of the screen. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/exitFullscreen) */ exitFullscreen(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/exitPictureInPicture) */ + /** + * The **`exitPictureInPicture()`** method of the Document interface requests that a video contained in this document, which is currently floating, be taken out of picture-in-picture mode, restoring the previous state of the screen. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/exitPictureInPicture) + */ exitPictureInPicture(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/exitPointerLock) */ - exitPointerLock(): void; /** - * Returns a reference to the first object with the specified value of the ID attribute. - * @param elementId String that specifies the ID value. + * The **`exitPointerLock()`** method of the Document interface asynchronously releases a pointer lock previously requested through Element.requestPointerLock. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/exitPointerLock) */ + exitPointerLock(): void; getElementById(elementId: string): HTMLElement | null; /** - * Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes. + * The **`getElementsByClassName`** method of of all child elements which have all of the given class name(s). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/getElementsByClassName) */ getElementsByClassName(classNames: string): HTMLCollectionOf; /** - * Gets a collection of objects based on the value of the NAME or ID attribute. - * @param elementName Gets a collection of objects based on the value of the NAME or ID attribute. + * The **`getElementsByName()`** method of the Document object returns a NodeList Collection of elements with a given `name` attribute in the document. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/getElementsByName) */ getElementsByName(elementName: string): NodeListOf; /** - * Retrieves a collection of objects based on the specified element name. - * @param name Specifies the name of an element. + * The **`getElementsByTagName`** method of The complete document is searched, including the root node. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/getElementsByTagName) */ @@ -7873,13 +10280,7 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: string): HTMLCollectionOf; /** - * If namespace and localName are "*" returns a HTMLCollection of all descendant elements. - * - * If only namespace is "*" returns a HTMLCollection of all descendant elements whose local name is localName. - * - * If only localName is "*" returns a HTMLCollection of all descendant elements whose namespace is namespace. - * - * Otherwise, returns a HTMLCollection of all descendant elements whose namespace is namespace and local name is localName. + * Returns a list of elements with the given tag name belonging to the given namespace. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/getElementsByTagNameNS) */ @@ -7888,95 +10289,90 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve getElementsByTagNameNS(namespaceURI: "http://www.w3.org/1998/Math/MathML", localName: string): HTMLCollectionOf; getElementsByTagNameNS(namespace: string | null, localName: string): HTMLCollectionOf; /** - * Returns an object representing the current selection of the document that is loaded into the object displaying a webpage. + * The **`getSelection()`** method of the Document interface returns the Selection object associated with this document, representing the range of text selected by the user, or the current position of the caret. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/getSelection) */ getSelection(): Selection | null; /** - * Gets a value indicating whether the object currently has focus. + * The **`hasFocus()`** method of the Document interface returns a boolean value indicating whether the document or any element inside the document has focus. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/hasFocus) */ hasFocus(): boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/hasStorageAccess) */ - hasStorageAccess(): Promise; /** - * Returns a copy of node. If deep is true, the copy also includes the node's descendants. + * The **`hasStorageAccess()`** method of the Document interface returns a Promise that resolves with a boolean value indicating whether the document has access to third-party, unpartitioned cookies. * - * If node is a document or a shadow root, throws a "NotSupportedError" DOMException. + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/hasStorageAccess) + */ + hasStorageAccess(): Promise; + /** + * The Document object's **`importNode()`** method creates a copy of a inserted into the current document later. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/importNode) */ - importNode(node: T, subtree?: boolean): T; + importNode(node: T, options?: boolean | ImportNodeOptions): T; /** - * Opens a new window and loads a document specified by a given URL. Also, opens a new window that uses the url parameter and the name parameter to collect the output of the write method and the writeln method. - * @param url Specifies a MIME type for the document. - * @param name Specifies the name of the window. This name is used as the value for the TARGET attribute on a form or an anchor element. - * @param features Contains a list of items separated by commas. Each item consists of an option and a value, separated by an equals sign (for example, "fullscreen=yes, toolbar=yes"). The following values are supported. - * @param replace Specifies whether the existing entry for the document is replaced in the history list. + * The **`Document.open()`** method opens a document for This does come with some side effects. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/open) */ open(unused1?: string, unused2?: string): Document; open(url: string | URL, name: string, features: string): WindowProxy | null; /** - * Returns a Boolean value that indicates whether a specified command can be successfully executed using execCommand, given the current state of the document. - * @param commandId Specifies a command identifier. + * The **`Document.queryCommandEnabled()`** method reports whether or not the specified editor command is enabled by the browser. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/queryCommandEnabled) */ queryCommandEnabled(commandId: string): boolean; - /** - * Returns a Boolean value that indicates whether the specified command is in the indeterminate state. - * @param commandId String that specifies a command identifier. - * @deprecated - */ + /** @deprecated */ queryCommandIndeterm(commandId: string): boolean; /** - * Returns a Boolean value that indicates the current state of the command. - * @param commandId String that specifies a command identifier. + * The **`queryCommandState()`** method will tell you if the current selection has a certain Document.execCommand() command applied. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/queryCommandState) */ queryCommandState(commandId: string): boolean; /** - * Returns a Boolean value that indicates whether the current command is supported on the current range. - * @param commandId Specifies a command identifier. + * The **`Document.queryCommandSupported()`** method reports whether or not the specified editor command is supported by the browser. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/queryCommandSupported) */ queryCommandSupported(commandId: string): boolean; - /** - * Returns the current value of the document, range, or current selection for the given command. - * @param commandId String that specifies a command identifier. - * @deprecated - */ + /** @deprecated */ queryCommandValue(commandId: string): string; /** @deprecated */ releaseEvents(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/requestStorageAccess) */ + /** + * The **`requestStorageAccess()`** method of the Document interface allows content loaded in a third-party context (i.e., embedded in an iframe) to request access to third-party cookies and unpartitioned state. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/requestStorageAccess) + */ requestStorageAccess(): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/startViewTransition) */ - startViewTransition(callbackOptions?: ViewTransitionUpdateCallback): ViewTransition; /** - * Writes one or more HTML expressions to a document in the specified window. - * @param content Specifies the text and HTML tags to write. + * The **`startViewTransition()`** method of the Document interface starts a new same-document (SPA) view transition and returns a ViewTransition object to represent it. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/startViewTransition) + */ + startViewTransition(callbackOptions?: ViewTransitionUpdateCallback | StartViewTransitionOptions): ViewTransition; + /** + * The **`write()`** method of the Document interface writes text in one or more TrustedHTML or string parameters to a document stream opened by document.open(). * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/write) */ write(...text: string[]): void; /** - * Writes one or more HTML expressions, followed by a carriage return, to a document in the specified window. - * @param content The text and HTML tags to write. + * The **`writeln()`** method of the Document interface writes text in one or more TrustedHTML or string parameters to a document stream opened by document.open(), followed by a newline character. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/writeln) */ writeln(...text: string[]): void; + /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) */ + get textContent(): null; addEventListener(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; removeEventListener(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void; @@ -7986,18 +10382,25 @@ interface Document extends Node, DocumentOrShadowRoot, FontFaceSource, GlobalEve declare var Document: { prototype: Document; new(): Document; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/parseHTMLUnsafe_static) */ + /** + * The **`parseHTMLUnsafe()`** static method of the Document object is used to parse an HTML input, optionally filtering unwanted HTML elements and attributes, in order to create a new Document instance. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/parseHTMLUnsafe_static) + */ parseHTMLUnsafe(html: string): Document; }; /** - * A minimal document object that has no parent. It is used as a lightweight version of Document that stores a segment of a document structure comprised of nodes just like a standard document. The key difference is that because the document fragment isn't part of the active document tree structure, changes made to the fragment don't affect the document, cause reflow, or incur any performance impact that can occur when changes are made. + * The **`DocumentFragment`** interface represents a minimal document object that has no parent. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentFragment) */ interface DocumentFragment extends Node, NonElementParentNode, ParentNode { readonly ownerDocument: Document; getElementById(elementId: string): HTMLElement | null; + /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) */ + get textContent(): string; + set textContent(value: string | null); } declare var DocumentFragment: { @@ -8028,24 +10431,19 @@ interface DocumentOrShadowRoot { readonly pictureInPictureElement: Element | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/pointerLockElement) */ readonly pointerLockElement: Element | null; - /** - * Retrieves a collection of styleSheet objects representing the style sheets that correspond to each instance of a link or style object in the document. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/styleSheets) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/styleSheets) */ readonly styleSheets: StyleSheetList; - /** - * Returns the element for the specified x coordinate and the specified y coordinate. - * @param x The x-offset - * @param y The y-offset - */ elementFromPoint(x: number, y: number): Element | null; elementsFromPoint(x: number, y: number): Element[]; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/getAnimations) */ getAnimations(): Animation[]; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentTimeline) */ +/** + * The **`DocumentTimeline`** interface of the Web Animations API represents animation timelines, including the default document timeline (accessed via Document.timeline). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentTimeline) + */ interface DocumentTimeline extends AnimationTimeline { } @@ -8055,18 +10453,32 @@ declare var DocumentTimeline: { }; /** - * A Node containing a doctype. + * The **`DocumentType`** interface represents a Node containing a doctype. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentType) */ interface DocumentType extends Node, ChildNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentType/name) */ + /** + * The read-only **`name`** property of the DocumentType returns the type of the document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentType/name) + */ readonly name: string; readonly ownerDocument: Document; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentType/publicId) */ + /** + * The read-only **`publicId`** property of the DocumentType returns a formal identifier of the document. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentType/publicId) + */ readonly publicId: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentType/systemId) */ + /** + * The read-only **`systemId`** property of the DocumentType returns the URL of the associated DTD. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DocumentType/systemId) + */ readonly systemId: string; + /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) */ + get textContent(): null; } declare var DocumentType: { @@ -8075,13 +10487,13 @@ declare var DocumentType: { }; /** - * A DOM event that represents a drag and drop interaction. The user initiates a drag by placing a pointer device (such as a mouse) on the touch surface and then dragging the pointer to a new location (such as another DOM element). Applications are free to interpret a drag and drop interaction in an application-specific way. + * The **`DragEvent`** interface is a DOM event that represents a drag and drop interaction. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DragEvent) */ interface DragEvent extends MouseEvent { /** - * Returns the DataTransfer object for the event. + * The **`DragEvent.dataTransfer`** read-only property holds the drag operation's data (as a DataTransfer object). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DragEvent/dataTransfer) */ @@ -8094,22 +10506,46 @@ declare var DragEvent: { }; /** - * Inherits properties from its parent, AudioNode. + * The `DynamicsCompressorNode` interface provides a compression effect, which lowers the volume of the loudest parts of the signal in order to help prevent clipping and distortion that can occur when multiple sounds are played and multiplexed together at once. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode) */ interface DynamicsCompressorNode extends AudioNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/attack) */ + /** + * The `attack` property of the DynamicsCompressorNode interface is a k-rate AudioParam representing the amount of time, in seconds, required to reduce the gain by 10 dB. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/attack) + */ readonly attack: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/knee) */ + /** + * The `knee` property of the DynamicsCompressorNode interface is a k-rate AudioParam containing a decibel value representing the range above the threshold where the curve smoothly transitions to the compressed portion. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/knee) + */ readonly knee: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/ratio) */ + /** + * The `ratio` property of the DynamicsCompressorNode interface Is a k-rate AudioParam representing the amount of change, in dB, needed in the input for a 1 dB change in the output. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/ratio) + */ readonly ratio: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/reduction) */ + /** + * The **`reduction`** read-only property of the DynamicsCompressorNode interface is a float representing the amount of gain reduction currently applied by the compressor to the signal. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/reduction) + */ readonly reduction: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/release) */ + /** + * The `release` property of the DynamicsCompressorNode interface Is a k-rate AudioParam representing the amount of time, in seconds, required to increase the gain by 10 dB. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/release) + */ readonly release: AudioParam; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/threshold) */ + /** + * The `threshold` property of the DynamicsCompressorNode interface is a k-rate AudioParam representing the decibel value above which the compression will start taking effect. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/DynamicsCompressorNode/threshold) + */ readonly threshold: AudioParam; } @@ -8118,17 +10554,29 @@ declare var DynamicsCompressorNode: { new(context: BaseAudioContext, options?: DynamicsCompressorOptions): DynamicsCompressorNode; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_blend_minmax) */ +/** + * The **`EXT_blend_minmax`** extension is part of the WebGL API and extends blending capabilities by adding two new blend equations: the minimum or maximum color components of the source and destination colors. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_blend_minmax) + */ interface EXT_blend_minmax { readonly MIN_EXT: 0x8007; readonly MAX_EXT: 0x8008; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_color_buffer_float) */ +/** + * The **`EXT_color_buffer_float`** extension is part of WebGL and adds the ability to render a variety of floating point formats. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_color_buffer_float) + */ interface EXT_color_buffer_float { } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_color_buffer_half_float) */ +/** + * The **`EXT_color_buffer_half_float`** extension is part of the WebGL API and adds the ability to render to 16-bit floating-point color buffers. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_color_buffer_half_float) + */ interface EXT_color_buffer_half_float { readonly RGBA16F_EXT: 0x881A; readonly RGB16F_EXT: 0x881B; @@ -8136,19 +10584,27 @@ interface EXT_color_buffer_half_float { readonly UNSIGNED_NORMALIZED_EXT: 0x8C17; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_float_blend) */ +/** + * The WebGL API's `EXT_float_blend` extension allows blending and draw buffers with 32-bit floating-point components. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_float_blend) + */ interface EXT_float_blend { } /** - * The EXT_frag_depth extension is part of the WebGL API and enables to set a depth value of a fragment from within the fragment shader. + * The **`EXT_frag_depth`** extension is part of the WebGL API and enables to set a depth value of a fragment from within the fragment shader. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_frag_depth) */ interface EXT_frag_depth { } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_sRGB) */ +/** + * The **`EXT_sRGB`** extension is part of the WebGL API and adds sRGB support to textures and framebuffer objects. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_sRGB) + */ interface EXT_sRGB { readonly SRGB_EXT: 0x8C40; readonly SRGB_ALPHA_EXT: 0x8C42; @@ -8156,11 +10612,19 @@ interface EXT_sRGB { readonly FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING_EXT: 0x8210; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_shader_texture_lod) */ +/** + * The **`EXT_shader_texture_lod`** extension is part of the WebGL API and adds additional texture functions to the OpenGL ES Shading Language which provide the shader writer with explicit control of LOD (Level of detail). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_shader_texture_lod) + */ interface EXT_shader_texture_lod { } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_texture_compression_bptc) */ +/** + * The `EXT_texture_compression_bptc` extension is part of the WebGL API and exposes 4 BPTC compressed texture formats. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_texture_compression_bptc) + */ interface EXT_texture_compression_bptc { readonly COMPRESSED_RGBA_BPTC_UNORM_EXT: 0x8E8C; readonly COMPRESSED_SRGB_ALPHA_BPTC_UNORM_EXT: 0x8E8D; @@ -8168,7 +10632,11 @@ interface EXT_texture_compression_bptc { readonly COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT_EXT: 0x8E8F; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_texture_compression_rgtc) */ +/** + * The `EXT_texture_compression_rgtc` extension is part of the WebGL API and exposes 4 RGTC compressed texture formats. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_texture_compression_rgtc) + */ interface EXT_texture_compression_rgtc { readonly COMPRESSED_RED_RGTC1_EXT: 0x8DBB; readonly COMPRESSED_SIGNED_RED_RGTC1_EXT: 0x8DBC; @@ -8177,7 +10645,7 @@ interface EXT_texture_compression_rgtc { } /** - * The EXT_texture_filter_anisotropic extension is part of the WebGL API and exposes two constants for anisotropic filtering (AF). + * The **`EXT_texture_filter_anisotropic`** extension is part of the WebGL API and exposes two constants for anisotropic filtering (AF). * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_texture_filter_anisotropic) */ @@ -8186,7 +10654,11 @@ interface EXT_texture_filter_anisotropic { readonly MAX_TEXTURE_MAX_ANISOTROPY_EXT: 0x84FF; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_texture_norm16) */ +/** + * The **`EXT_texture_norm16`** extension is part of the WebGL API and provides a set of new 16-bit signed normalized and unsigned normalized formats (fixed-point texture, renderbuffer and texture buffer). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EXT_texture_norm16) + */ interface EXT_texture_norm16 { readonly R16_EXT: 0x822A; readonly RG16_EXT: 0x822C; @@ -8204,52 +10676,80 @@ interface ElementEventMap { } /** - * Element is the most general base class from which all objects in a Document inherit. It only has methods and properties common to all kinds of elements. More specific classes inherit from Element. + * **`Element`** is the most general base class from which all element objects (i.e., objects that represent elements) in a Document inherit. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element) */ interface Element extends Node, ARIAMixin, Animatable, ChildNode, NonDocumentTypeChildNode, ParentNode, Slottable { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/attributes) */ + /** + * The **`Element.attributes`** property returns a live collection of all attribute nodes registered to the specified node. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/attributes) + */ readonly attributes: NamedNodeMap; /** - * Allows for manipulation of element's class content attribute as a set of whitespace-separated tokens through a DOMTokenList object. + * The **`Element.classList`** is a read-only property that returns a live DOMTokenList collection of the `class` attributes of the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/classList) */ get classList(): DOMTokenList; set classList(value: string); /** - * Returns the value of element's class content attribute. Can be set to change it. + * The **`className`** property of the of the specified element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/className) */ className: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientHeight) */ + /** + * The **`clientHeight`** read-only property of the Element interface is zero for elements with no CSS or inline layout boxes; otherwise, it's the inner height of an element in pixels. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientHeight) + */ readonly clientHeight: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientLeft) */ + /** + * The **`clientLeft`** read-only property of the Element interface returns the width of the left border of an element in pixels. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientLeft) + */ readonly clientLeft: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientTop) */ + /** + * The **`clientTop`** read-only property of the Element interface returns the width of the top border of an element in pixels. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientTop) + */ readonly clientTop: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientWidth) */ + /** + * The **`clientWidth`** read-only property of the Element interface is zero for inline elements and elements with no CSS; otherwise, it's the inner width of an element in pixels. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/clientWidth) + */ readonly clientWidth: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/currentCSSZoom) */ + /** + * The **`currentCSSZoom`** read-only property of the Element interface provides the 'effective' CSS `zoom` of an element, taking into account the zoom applied to the element and all its parent elements. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/currentCSSZoom) + */ readonly currentCSSZoom: number; /** - * Returns the value of element's id content attribute. Can be set to change it. + * The **`id`** property of the Element interface represents the element's identifier, reflecting the **`id`** global attribute. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/id) */ id: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/innerHTML) */ + /** + * The **`innerHTML`** property of the Element interface gets or sets the HTML or XML markup contained within the element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/innerHTML) + */ innerHTML: string; /** - * Returns the local name. + * The **`Element.localName`** read-only property returns the local part of the qualified name of an element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/localName) */ readonly localName: string; /** - * Returns the namespace. + * The **`Element.namespaceURI`** read-only property returns the namespace URI of the element, or `null` if the element is not in a namespace. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/namespaceURI) */ @@ -8258,54 +10758,82 @@ interface Element extends Node, ARIAMixin, Animatable, ChildNode, NonDocumentTyp onfullscreenchange: ((this: Element, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/fullscreenerror_event) */ onfullscreenerror: ((this: Element, ev: Event) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/outerHTML) */ + /** + * The **`outerHTML`** attribute of the Element DOM interface gets the serialized HTML fragment describing the element including its descendants. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/outerHTML) + */ outerHTML: string; readonly ownerDocument: Document; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/part) */ + /** + * The **`part`** property of the Element interface represents the part identifier(s) of the element (i.e., set using the `part` attribute), returned as a DOMTokenList. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/part) + */ get part(): DOMTokenList; set part(value: string); /** - * Returns the namespace prefix. + * The **`Element.prefix`** read-only property returns the namespace prefix of the specified element, or `null` if no prefix is specified. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/prefix) */ readonly prefix: string | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollHeight) */ + /** + * The **`scrollHeight`** read-only property of the Element interface is a measurement of the height of an element's content, including content not visible on the screen due to overflow. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollHeight) + */ readonly scrollHeight: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollLeft) */ + /** + * The **`scrollLeft`** property of the Element interface gets or sets the number of pixels by which an element's content is scrolled from its left edge. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollLeft) + */ scrollLeft: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollTop) */ + /** + * The **`scrollTop`** property of the Element interface gets or sets the number of pixels by which an element's content is scrolled from its top edge. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollTop) + */ scrollTop: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollWidth) */ + /** + * The **`scrollWidth`** read-only property of the Element interface is a measurement of the width of an element's content, including content not visible on the screen due to overflow. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollWidth) + */ readonly scrollWidth: number; /** - * Returns element's shadow root, if any, and if shadow root's mode is "open", and null otherwise. + * The `Element.shadowRoot` read-only property represents the shadow root hosted by the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/shadowRoot) */ readonly shadowRoot: ShadowRoot | null; /** - * Returns the value of element's slot content attribute. Can be set to change it. + * The **`slot`** property of the Element interface returns the name of the shadow DOM slot the element is inserted in. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/slot) */ slot: string; /** - * Returns the HTML-uppercased qualified name. + * The **`tagName`** read-only property of the Element interface returns the tag name of the element on which it's called. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/tagName) */ readonly tagName: string; /** - * Creates a shadow root for element and returns it. + * The **`Element.attachShadow()`** method attaches a shadow DOM tree to the specified element and returns a reference to its ShadowRoot. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/attachShadow) */ attachShadow(init: ShadowRootInit): ShadowRoot; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/checkVisibility) */ + /** + * The **`checkVisibility()`** method of the Element interface checks whether the element is visible. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/checkVisibility) + */ checkVisibility(options?: CheckVisibilityOptions): boolean; /** - * Returns the first (starting at element) inclusive ancestor that matches selectors, and null otherwise. + * The **`closest()`** method of the Element interface traverses the element and its parents (heading toward the document root) until it finds a node that matches the specified CSS selector. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/closest) */ @@ -8313,147 +10841,235 @@ interface Element extends Node, ARIAMixin, Animatable, ChildNode, NonDocumentTyp closest(selector: K): SVGElementTagNameMap[K] | null; closest(selector: K): MathMLElementTagNameMap[K] | null; closest(selectors: string): E | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/computedStyleMap) */ + /** + * The **`computedStyleMap()`** method of the Element interface returns a StylePropertyMapReadOnly interface which provides a read-only representation of a CSS declaration block that is an alternative to CSSStyleDeclaration. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/computedStyleMap) + */ computedStyleMap(): StylePropertyMapReadOnly; /** - * Returns element's first attribute whose qualified name is qualifiedName, and null if there is no such attribute otherwise. + * The **`getAttribute()`** method of the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAttribute) */ getAttribute(qualifiedName: string): string | null; /** - * Returns element's attribute whose namespace is namespace and local name is localName, and null if there is no such attribute otherwise. + * The **`getAttributeNS()`** method of the Element interface returns the string value of the attribute with the specified namespace and name. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAttributeNS) */ getAttributeNS(namespace: string | null, localName: string): string | null; /** - * Returns the qualified names of all element's attributes. Can contain duplicates. + * The **`getAttributeNames()`** method of the array. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAttributeNames) */ getAttributeNames(): string[]; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAttributeNode) */ + /** + * Returns the specified attribute of the specified element, as an Attr node. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAttributeNode) + */ getAttributeNode(qualifiedName: string): Attr | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAttributeNodeNS) */ + /** + * The **`getAttributeNodeNS()`** method of the Element interface returns the namespaced Attr node of an element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getAttributeNodeNS) + */ getAttributeNodeNS(namespace: string | null, localName: string): Attr | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getBoundingClientRect) */ + /** + * The **`Element.getBoundingClientRect()`** method returns a position relative to the viewport. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getBoundingClientRect) + */ getBoundingClientRect(): DOMRect; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getClientRects) */ + /** + * The **`getClientRects()`** method of the Element interface returns a collection of DOMRect objects that indicate the bounding rectangles for each CSS border box in a client. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getClientRects) + */ getClientRects(): DOMRectList; /** - * Returns a HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes. + * The Element method **`getElementsByClassName()`** returns a live specified class name or names. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getElementsByClassName) */ getElementsByClassName(classNames: string): HTMLCollectionOf; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getElementsByTagName) */ + /** + * The **`Element.getElementsByTagName()`** method returns a live All descendants of the specified element are searched, but not the element itself. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getElementsByTagName) + */ getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: K): HTMLCollectionOf; /** @deprecated */ getElementsByTagName(qualifiedName: K): HTMLCollectionOf; getElementsByTagName(qualifiedName: string): HTMLCollectionOf; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getElementsByTagNameNS) */ + /** + * The **`Element.getElementsByTagNameNS()`** method returns a live HTMLCollection of elements with the given tag name belonging to the given namespace. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getElementsByTagNameNS) + */ getElementsByTagNameNS(namespaceURI: "http://www.w3.org/1999/xhtml", localName: string): HTMLCollectionOf; getElementsByTagNameNS(namespaceURI: "http://www.w3.org/2000/svg", localName: string): HTMLCollectionOf; getElementsByTagNameNS(namespaceURI: "http://www.w3.org/1998/Math/MathML", localName: string): HTMLCollectionOf; getElementsByTagNameNS(namespace: string | null, localName: string): HTMLCollectionOf; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getHTML) */ + /** + * The **`getHTML()`** method of the Element interface is used to serialize an element's DOM to an HTML string. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/getHTML) + */ getHTML(options?: GetHTMLOptions): string; /** - * Returns true if element has an attribute whose qualified name is qualifiedName, and false otherwise. + * The **`Element.hasAttribute()`** method returns a **Boolean** value indicating whether the specified element has the specified attribute or not. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/hasAttribute) */ hasAttribute(qualifiedName: string): boolean; /** - * Returns true if element has an attribute whose namespace is namespace and local name is localName. + * The **`hasAttributeNS()`** method of the Element interface returns a boolean value indicating whether the current element has the specified attribute with the specified namespace. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/hasAttributeNS) */ hasAttributeNS(namespace: string | null, localName: string): boolean; /** - * Returns true if element has attributes, and false otherwise. + * The **`hasAttributes()`** method of the Element interface returns a boolean value indicating whether the current element has any attributes or not. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/hasAttributes) */ hasAttributes(): boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/hasPointerCapture) */ + /** + * The **`hasPointerCapture()`** method of the pointer capture for the pointer identified by the given pointer ID. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/hasPointerCapture) + */ hasPointerCapture(pointerId: number): boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/insertAdjacentElement) */ + /** + * The **`insertAdjacentElement()`** method of the relative to the element it is invoked upon. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/insertAdjacentElement) + */ insertAdjacentElement(where: InsertPosition, element: Element): Element | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/insertAdjacentHTML) */ + /** + * The **`insertAdjacentHTML()`** method of the the resulting nodes into the DOM tree at a specified position. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/insertAdjacentHTML) + */ insertAdjacentHTML(position: InsertPosition, string: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/insertAdjacentText) */ + /** + * The **`insertAdjacentText()`** method of the Element interface, given a relative position and a string, inserts a new text node at the given position relative to the element it is called from. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/insertAdjacentText) + */ insertAdjacentText(where: InsertPosition, data: string): void; /** - * Returns true if matching selectors against element's root yields element, and false otherwise. + * The **`matches()`** method of the Element interface tests whether the element would be selected by the specified CSS selector. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/matches) */ matches(selectors: string): boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/releasePointerCapture) */ + /** + * The **`releasePointerCapture()`** method of the previously set for a specific (PointerEvent) _pointer_. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/releasePointerCapture) + */ releasePointerCapture(pointerId: number): void; /** - * Removes element's first attribute whose qualified name is qualifiedName. + * The Element method **`removeAttribute()`** removes the attribute with the specified name from the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/removeAttribute) */ removeAttribute(qualifiedName: string): void; /** - * Removes element's attribute whose namespace is namespace and local name is localName. + * The **`removeAttributeNS()`** method of the If you are working with HTML and you don't need to specify the requested attribute as being part of a specific namespace, use the Element.removeAttribute() method instead. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/removeAttributeNS) */ removeAttributeNS(namespace: string | null, localName: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/removeAttributeNode) */ - removeAttributeNode(attr: Attr): Attr; /** - * Displays element fullscreen and resolves promise when done. + * The **`removeAttributeNode()`** method of the Element interface removes the specified Attr node from the element. * - * When supplied, options's navigationUI member indicates whether showing navigation UI while in fullscreen is preferred or not. If set to "show", navigation simplicity is preferred over screen space, and if set to "hide", more screen space is preferred. User agents are always free to honor user preference over the application's. The default value "auto" indicates no application preference. + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/removeAttributeNode) + */ + removeAttributeNode(attr: Attr): Attr; + /** + * The **`Element.requestFullscreen()`** method issues an asynchronous request to make the element be displayed in fullscreen mode. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/requestFullscreen) */ requestFullscreen(options?: FullscreenOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/requestPointerLock) */ + /** + * The **`requestPointerLock()`** method of the Element interface lets you asynchronously ask for the pointer to be locked on the given element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/requestPointerLock) + */ requestPointerLock(options?: PointerLockOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scroll) */ + /** + * The **`scroll()`** method of the Element interface scrolls the element to a particular set of coordinates inside a given element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scroll) + */ scroll(options?: ScrollToOptions): void; scroll(x: number, y: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollBy) */ + /** + * The **`scrollBy()`** method of the Element interface scrolls an element by the given amount. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollBy) + */ scrollBy(options?: ScrollToOptions): void; scrollBy(x: number, y: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollIntoView) */ + /** + * The Element interface's **`scrollIntoView()`** method scrolls the element's ancestor containers such that the element on which `scrollIntoView()` is called is visible to the user. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollIntoView) + */ scrollIntoView(arg?: boolean | ScrollIntoViewOptions): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollTo) */ + /** + * The **`scrollTo()`** method of the Element interface scrolls to a particular set of coordinates inside a given element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/scrollTo) + */ scrollTo(options?: ScrollToOptions): void; scrollTo(x: number, y: number): void; /** - * Sets the value of element's first attribute whose qualified name is qualifiedName to value. + * The **`setAttribute()`** method of the Element interface sets the value of an attribute on the specified element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setAttribute) */ setAttribute(qualifiedName: string, value: string): void; /** - * Sets the value of element's attribute whose namespace is namespace and local name is localName to value. + * `setAttributeNS` adds a new attribute or changes the value of an attribute with the given namespace and name. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setAttributeNS) */ setAttributeNS(namespace: string | null, qualifiedName: string, value: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setAttributeNode) */ + /** + * The **`setAttributeNode()`** method of the Element interface adds a new Attr node to the specified element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setAttributeNode) + */ setAttributeNode(attr: Attr): Attr | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setAttributeNodeNS) */ + /** + * The **`setAttributeNodeNS()`** method of the Element interface adds a new namespaced Attr node to an element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setAttributeNodeNS) + */ setAttributeNodeNS(attr: Attr): Attr | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setHTMLUnsafe) */ + /** + * The **`setHTMLUnsafe()`** method of the Element interface is used to parse a string of HTML into a DocumentFragment, optionally filtering out unwanted elements and attributes, and those that don't belong in the context, and then using it to replace the element's subtree in the DOM. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setHTMLUnsafe) + */ setHTMLUnsafe(html: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setPointerCapture) */ - setPointerCapture(pointerId: number): void; /** - * If force is not given, "toggles" qualifiedName, removing it if it is present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName. + * The **`setPointerCapture()`** method of the _capture target_ of future pointer events. * - * Returns true if qualifiedName is now present, and false otherwise. + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/setPointerCapture) + */ + setPointerCapture(pointerId: number): void; + /** + * The **`toggleAttribute()`** method of the present and adding it if it is not present) on the given element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/toggleAttribute) */ @@ -8464,6 +11080,9 @@ interface Element extends Node, ARIAMixin, Animatable, ChildNode, NonDocumentTyp * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/matches) */ webkitMatchesSelector(selectors: string): boolean; + /** [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) */ + get textContent(): string; + set textContent(value: string | null); addEventListener(type: K, listener: (this: Element, ev: ElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; removeEventListener(type: K, listener: (this: Element, ev: ElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void; @@ -8494,68 +11113,74 @@ interface ElementContentEditable { readonly isContentEditable: boolean; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals) */ +/** + * The **`ElementInternals`** interface of the Document Object Model gives web developers a way to allow custom elements to fully participate in HTML forms. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals) + */ interface ElementInternals extends ARIAMixin { /** - * Returns the form owner of internals's target element. + * The **`form`** read-only property of the ElementInternals interface returns the HTMLFormElement associated with this element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/form) */ readonly form: HTMLFormElement | null; /** - * Returns a NodeList of all the label elements that internals's target element is associated with. + * The **`labels`** read-only property of the ElementInternals interface returns the labels associated with the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/labels) */ readonly labels: NodeList; /** - * Returns the ShadowRoot for internals's target element, if the target element is a shadow host, or null otherwise. + * The **`shadowRoot`** read-only property of the ElementInternals interface returns the ShadowRoot for this element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/shadowRoot) */ readonly shadowRoot: ShadowRoot | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/states) */ + /** + * The **`states`** read-only property of the ElementInternals interface returns a CustomStateSet representing the possible states of the custom element. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/states) + */ readonly states: CustomStateSet; /** - * Returns the error message that would be shown to the user if internals's target element was to be checked for validity. + * The **`validationMessage`** read-only property of the ElementInternals interface returns the validation message for the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/validationMessage) */ readonly validationMessage: string; /** - * Returns the ValidityState object for internals's target element. + * The **`validity`** read-only property of the ElementInternals interface returns a ValidityState object which represents the different validity states the element can be in, with respect to constraint validation. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/validity) */ readonly validity: ValidityState; /** - * Returns true if internals's target element will be validated when the form is submitted; false otherwise. + * The **`willValidate`** read-only property of the ElementInternals interface returns `true` if the element is a submittable element that is a candidate for constraint validation. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/willValidate) */ readonly willValidate: boolean; /** - * Returns true if internals's target element has no validity problems; false otherwise. Fires an invalid event at the element in the latter case. + * The **`checkValidity()`** method of the ElementInternals interface checks if the element meets any constraint validation rules applied to it. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/checkValidity) */ checkValidity(): boolean; /** - * Returns true if internals's target element has no validity problems; otherwise, returns false, fires an invalid event at the element, and (if the event isn't canceled) reports the problem to the user. + * The **`reportValidity()`** method of the ElementInternals interface checks if the element meets any constraint validation rules applied to it. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/reportValidity) */ reportValidity(): boolean; /** - * Sets both the state and submission value of internals's target element to value. - * - * If value is null, the element won't participate in form submission. + * The **`setFormValue()`** method of the ElementInternals interface sets the element's submission value and state, communicating these to the user agent. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/setFormValue) */ setFormValue(value: File | string | FormData | null, state?: File | string | FormData | null): void; /** - * Marks internals's target element as suffering from the constraints indicated by the flags argument, and sets the element's validation message to message. If anchor is specified, the user agent might use it to indicate problems with the constraints of internals's target element when the form owner is validated interactively or reportValidity() is called. + * The **`setValidity()`** method of the ElementInternals interface sets the validity of the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ElementInternals/setValidity) */ @@ -8567,17 +11192,41 @@ declare var ElementInternals: { new(): ElementInternals; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk) */ +/** + * The **`EncodedAudioChunk`** interface of the WebCodecs API represents a chunk of encoded audio data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk) + */ interface EncodedAudioChunk { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/byteLength) */ + /** + * The **`byteLength`** read-only property of the EncodedAudioChunk interface returns the length in bytes of the encoded audio data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/byteLength) + */ readonly byteLength: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/duration) */ + /** + * The **`duration`** read-only property of the EncodedAudioChunk interface returns an integer indicating the duration of the audio in microseconds. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/duration) + */ readonly duration: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/timestamp) */ + /** + * The **`timestamp`** read-only property of the EncodedAudioChunk interface returns an integer indicating the timestamp of the audio in microseconds. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/timestamp) + */ readonly timestamp: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/type) */ + /** + * The **`type`** read-only property of the EncodedAudioChunk interface returns a value indicating whether the audio chunk is a key chunk, which does not relying on other frames for decoding. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/type) + */ readonly type: EncodedAudioChunkType; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/copyTo) */ + /** + * The **`copyTo()`** method of the EncodedAudioChunk interface copies the encoded chunk of audio data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedAudioChunk/copyTo) + */ copyTo(destination: AllowSharedBufferSource): void; } @@ -8586,17 +11235,41 @@ declare var EncodedAudioChunk: { new(init: EncodedAudioChunkInit): EncodedAudioChunk; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk) */ +/** + * The **`EncodedVideoChunk`** interface of the WebCodecs API represents a chunk of encoded video data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk) + */ interface EncodedVideoChunk { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/byteLength) */ + /** + * The **`byteLength`** read-only property of the EncodedVideoChunk interface returns the length in bytes of the encoded video data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/byteLength) + */ readonly byteLength: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/duration) */ + /** + * The **`duration`** read-only property of the EncodedVideoChunk interface returns an integer indicating the duration of the video in microseconds. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/duration) + */ readonly duration: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/timestamp) */ + /** + * The **`timestamp`** read-only property of the EncodedVideoChunk interface returns an integer indicating the timestamp of the video in microseconds. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/timestamp) + */ readonly timestamp: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/type) */ + /** + * The **`type`** read-only property of the EncodedVideoChunk interface returns a value indicating whether the video chunk is a key chunk, which does not rely on other frames for decoding. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/type) + */ readonly type: EncodedVideoChunkType; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/copyTo) */ + /** + * The **`copyTo()`** method of the EncodedVideoChunk interface copies the encoded chunk of video data. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EncodedVideoChunk/copyTo) + */ copyTo(destination: AllowSharedBufferSource): void; } @@ -8606,20 +11279,40 @@ declare var EncodedVideoChunk: { }; /** - * Events providing information related to errors in scripts or in files. + * The **`ErrorEvent`** interface represents events providing information related to errors in scripts or in files. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent) */ interface ErrorEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/colno) */ + /** + * The **`colno`** read-only property of the ErrorEvent interface returns an integer containing the column number of the script file on which the error occurred. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/colno) + */ readonly colno: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/error) */ + /** + * The **`error`** read-only property of the ErrorEvent interface returns a JavaScript value, such as an Error or DOMException, representing the error associated with this event. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/error) + */ readonly error: any; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/filename) */ + /** + * The **`filename`** read-only property of the ErrorEvent interface returns a string containing the name of the script file in which the error occurred. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/filename) + */ readonly filename: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/lineno) */ + /** + * The **`lineno`** read-only property of the ErrorEvent interface returns an integer containing the line number of the script file on which the error occurred. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/lineno) + */ readonly lineno: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/message) */ + /** + * The **`message`** read-only property of the ErrorEvent interface returns a string containing a human-readable error message describing the problem. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/ErrorEvent/message) + */ readonly message: string; } @@ -8629,115 +11322,119 @@ declare var ErrorEvent: { }; /** - * An event which takes place in the DOM. + * The **`Event`** interface represents an event which takes place on an `EventTarget`. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event) */ interface Event { /** - * Returns true or false depending on how event was initialized. True if event goes through its target's ancestors in reverse tree order, and false otherwise. + * The **`bubbles`** read-only property of the Event interface indicates whether the event bubbles up through the DOM tree or not. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/bubbles) */ readonly bubbles: boolean; /** + * The **`cancelBubble`** property of the Event interface is deprecated. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelBubble) */ cancelBubble: boolean; /** - * Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method. + * The **`cancelable`** read-only property of the Event interface indicates whether the event can be canceled, and therefore prevented as if the event never happened. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/cancelable) */ readonly cancelable: boolean; /** - * Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target, and false otherwise. + * The read-only **`composed`** property of the or not the event will propagate across the shadow DOM boundary into the standard DOM. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/composed) */ readonly composed: boolean; /** - * Returns the object whose event listener's callback is currently being invoked. + * The **`currentTarget`** read-only property of the Event interface identifies the element to which the event handler has been attached. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/currentTarget) */ readonly currentTarget: EventTarget | null; /** - * Returns true if preventDefault() was invoked successfully to indicate cancelation, and false otherwise. + * The **`defaultPrevented`** read-only property of the Event interface returns a boolean value indicating whether or not the call to Event.preventDefault() canceled the event. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/defaultPrevented) */ readonly defaultPrevented: boolean; /** - * Returns the event's phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE. + * The **`eventPhase`** read-only property of the being evaluated. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/eventPhase) */ readonly eventPhase: number; /** - * Returns true if event was dispatched by the user agent, and false otherwise. + * The **`isTrusted`** read-only property of the when the event was generated by the user agent (including via user actions and programmatic methods such as HTMLElement.focus()), and `false` when the event was dispatched via The only exception is the `click` event, which initializes the `isTrusted` property to `false` in user agents. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/isTrusted) */ readonly isTrusted: boolean; /** + * The Event property **`returnValue`** indicates whether the default action for this event has been prevented or not. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/returnValue) */ returnValue: boolean; /** + * The deprecated **`Event.srcElement`** is an alias for the Event.target property. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/srcElement) */ readonly srcElement: EventTarget | null; /** - * Returns the object to which event is dispatched (its target). + * The read-only **`target`** property of the dispatched. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/target) */ readonly target: EventTarget | null; /** - * Returns the event's timestamp as the number of milliseconds measured relative to the time origin. + * The **`timeStamp`** read-only property of the Event interface returns the time (in milliseconds) at which the event was created. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/timeStamp) */ readonly timeStamp: DOMHighResTimeStamp; /** - * Returns the type of event, e.g. "click", "hashchange", or "submit". + * The **`type`** read-only property of the Event interface returns a string containing the event's type. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/type) */ readonly type: string; /** - * Returns the invocation target objects of event's path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root's mode is "closed" that are not reachable from event's currentTarget. + * The **`composedPath()`** method of the Event interface returns the event's path which is an array of the objects on which listeners will be invoked. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/composedPath) */ composedPath(): EventTarget[]; /** + * The **`Event.initEvent()`** method is used to initialize the value of an event created using Document.createEvent(). * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/initEvent) */ initEvent(type: string, bubbles?: boolean, cancelable?: boolean): void; /** - * If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled. + * The **`preventDefault()`** method of the Event interface tells the user agent that if the event does not get explicitly handled, its default action should not be taken as it normally would be. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/preventDefault) */ preventDefault(): void; /** - * Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects. + * The **`stopImmediatePropagation()`** method of the If several listeners are attached to the same element for the same event type, they are called in the order in which they were added. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/stopImmediatePropagation) */ stopImmediatePropagation(): void; /** - * When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object. + * The **`stopPropagation()`** method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Event/stopPropagation) */ @@ -8757,7 +11454,11 @@ declare var Event: { readonly BUBBLING_PHASE: 3; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventCounts) */ +/** + * The **`EventCounts`** interface of the Performance API provides the number of events that have been dispatched for each event type. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventCounts) + */ interface EventCounts { forEach(callbackfn: (value: number, key: string, parent: EventCounts) => void, thisArg?: any): void; } @@ -8781,7 +11482,11 @@ interface EventSourceEventMap { "open": Event; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource) */ +/** + * The **`EventSource`** interface is web content's interface to server-sent events. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource) + */ interface EventSource extends EventTarget { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/error_event) */ onerror: ((this: EventSource, ev: Event) => any) | null; @@ -8790,25 +11495,25 @@ interface EventSource extends EventTarget { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/open_event) */ onopen: ((this: EventSource, ev: Event) => any) | null; /** - * Returns the state of this EventSource object's connection. It can have the values described below. + * The **`readyState`** read-only property of the connection. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/readyState) */ readonly readyState: number; /** - * Returns the URL providing the event stream. + * The **`url`** read-only property of the URL of the source. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/url) */ readonly url: string; /** - * Returns true if the credentials mode for connection requests to the URL providing the event stream is set to "include", and false otherwise. + * The **`withCredentials`** read-only property of the the `EventSource` object was instantiated with CORS credentials set. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/withCredentials) */ readonly withCredentials: boolean; /** - * Aborts any instances of the fetch algorithm started for this EventSource object, and sets the readyState attribute to CLOSED. + * The **`close()`** method of the EventSource interface closes the connection, if one is made, and sets the ```js-nolint close() ``` None. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventSource/close) */ @@ -8833,37 +11538,25 @@ declare var EventSource: { }; /** - * EventTarget is a DOM interface implemented by objects that can receive events and may have listeners for them. + * The **`EventTarget`** interface is implemented by objects that can receive events and may have listeners for them. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget) */ interface EventTarget { /** - * Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched. - * - * The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture. - * - * When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET. - * - * When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners. - * - * When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed. - * - * If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted. - * - * The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture. + * The **`addEventListener()`** method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener) */ addEventListener(type: string, callback: EventListenerOrEventListenerObject | null, options?: AddEventListenerOptions | boolean): void; /** - * Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise. + * The **`dispatchEvent()`** method of the EventTarget sends an Event to the object, (synchronously) invoking the affected event listeners in the appropriate order. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/dispatchEvent) */ dispatchEvent(event: Event): boolean; /** - * Removes the event listener in target's event listener list with the same type, callback, and options. + * The **`removeEventListener()`** method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/EventTarget/removeEventListener) */ @@ -8890,16 +11583,28 @@ declare var External: { }; /** - * Provides information about files and allows JavaScript in a web page to access their content. + * The **`File`** interface provides information about files and allows JavaScript in a web page to access their content. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File) */ interface File extends Blob { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified) */ + /** + * The **`lastModified`** read-only property of the File interface provides the last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/lastModified) + */ readonly lastModified: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name) */ + /** + * The **`name`** read-only property of the File interface returns the name of the file represented by a File object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/name) + */ readonly name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/webkitRelativePath) */ + /** + * The **`webkitRelativePath`** read-only property of the File interface contains a string which specifies the file's path relative to the directory selected by the user in an input element with its `webkitdirectory` attribute set. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/File/webkitRelativePath) + */ readonly webkitRelativePath: string; } @@ -8909,14 +11614,22 @@ declare var File: { }; /** - * An object of this type is returned by the files property of the HTML element; this lets you access the list of files selected with the element. It's also used for a list of files dropped into web content when using the drag and drop API; see the DataTransfer object for details on this usage. + * The **`FileList`** interface represents an object of this type returned by the `files` property of the HTML input element; this lets you access the list of files selected with the `` element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileList) */ interface FileList { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileList/length) */ + /** + * The **`length`** read-only property of the FileList interface returns the number of files in the `FileList`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileList/length) + */ readonly length: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileList/item) */ + /** + * The **`item()`** method of the FileList interface returns a File object representing the file at the specified index in the file list. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileList/item) + */ item(index: number): File | null; [index: number]: File; } @@ -8936,12 +11649,16 @@ interface FileReaderEventMap { } /** - * Lets web applications asynchronously read the contents of files (or raw data buffers) stored on the user's computer, using File or Blob objects to specify the file or data to read. + * The **`FileReader`** interface lets web applications asynchronously read the contents of files (or raw data buffers) stored on the user's computer, using File or Blob objects to specify the file or data to read. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader) */ interface FileReader extends EventTarget { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/error) */ + /** + * The **`error`** read-only property of the FileReader interface returns the error that occurred while reading the file. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/error) + */ readonly error: DOMException | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/abort_event) */ onabort: ((this: FileReader, ev: ProgressEvent) => any) | null; @@ -8955,23 +11672,48 @@ interface FileReader extends EventTarget { onloadstart: ((this: FileReader, ev: ProgressEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/progress_event) */ onprogress: ((this: FileReader, ev: ProgressEvent) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readyState) */ + /** + * The **`readyState`** read-only property of the FileReader interface provides the current state of the reading operation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readyState) + */ readonly readyState: typeof FileReader.EMPTY | typeof FileReader.LOADING | typeof FileReader.DONE; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/result) */ + /** + * The **`result`** read-only property of the FileReader interface returns the file's contents. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/result) + */ readonly result: string | ArrayBuffer | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/abort) */ + /** + * The **`abort()`** method of the FileReader interface aborts the read operation. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/abort) + */ abort(): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readAsArrayBuffer) */ + /** + * The **`readAsArrayBuffer()`** method of the FileReader interface is used to start reading the contents of a specified Blob or File. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readAsArrayBuffer) + */ readAsArrayBuffer(blob: Blob): void; /** + * The **`readAsBinaryString()`** method of the FileReader interface is used to start reading the contents of the specified Blob or File. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readAsBinaryString) */ readAsBinaryString(blob: Blob): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readAsDataURL) */ + /** + * The **`readAsDataURL()`** method of the FileReader interface is used to read the contents of the specified file's data as a base64 encoded string. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readAsDataURL) + */ readAsDataURL(blob: Blob): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readAsText) */ + /** + * The **`readAsText()`** method of the FileReader interface is used to read the contents of the specified Blob or File. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileReader/readAsText) + */ readAsText(blob: Blob, encoding?: string): void; readonly EMPTY: 0; readonly LOADING: 1; @@ -8990,11 +11732,23 @@ declare var FileReader: { readonly DONE: 2; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystem) */ +/** + * The File and Directory Entries API interface **`FileSystem`** is used to represent a file system. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystem) + */ interface FileSystem { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystem/name) */ + /** + * The read-only **`name`** property of the string is unique among all file systems currently exposed by the File and Directory Entries API. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystem/name) + */ readonly name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystem/root) */ + /** + * The read-only **`root`** property of the object representing the root directory of the file system, for use with the File and Directory Entries API. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystem/root) + */ readonly root: FileSystemDirectoryEntry; } @@ -9003,13 +11757,29 @@ declare var FileSystem: { new(): FileSystem; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry) */ +/** + * The **`FileSystemDirectoryEntry`** interface of the File and Directory Entries API represents a directory in a file system. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry) + */ interface FileSystemDirectoryEntry extends FileSystemEntry { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry/createReader) */ + /** + * The FileSystemDirectoryEntry interface's method **`createReader()`** returns a the directory. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry/createReader) + */ createReader(): FileSystemDirectoryReader; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry/getDirectory) */ + /** + * The FileSystemDirectoryEntry interface's method **`getDirectory()`** returns a somewhere within the directory subtree rooted at the directory on which it's called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry/getDirectory) + */ getDirectory(path?: string | null, options?: FileSystemFlags, successCallback?: FileSystemEntryCallback, errorCallback?: ErrorCallback): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry/getFile) */ + /** + * The FileSystemDirectoryEntry interface's method **`getFile()`** returns a within the directory subtree rooted at the directory on which it's called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryEntry/getFile) + */ getFile(path?: string | null, options?: FileSystemFlags, successCallback?: FileSystemEntryCallback, errorCallback?: ErrorCallback): void; } @@ -9019,19 +11789,36 @@ declare var FileSystemDirectoryEntry: { }; /** + * The **`FileSystemDirectoryHandle`** interface of the File System API provides a handle to a file system directory. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle) */ interface FileSystemDirectoryHandle extends FileSystemHandle { readonly kind: "directory"; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/getDirectoryHandle) */ + /** + * The **`getDirectoryHandle()`** method of the within the directory handle on which the method is called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/getDirectoryHandle) + */ getDirectoryHandle(name: string, options?: FileSystemGetDirectoryOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/getFileHandle) */ + /** + * The **`getFileHandle()`** method of the directory the method is called. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/getFileHandle) + */ getFileHandle(name: string, options?: FileSystemGetFileOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/removeEntry) */ + /** + * The **`removeEntry()`** method of the directory handle contains a file or directory called the name specified. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/removeEntry) + */ removeEntry(name: string, options?: FileSystemRemoveOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/resolve) */ + /** + * The **`resolve()`** method of the directory names from the parent handle to the specified child entry, with the name of the child entry as the last array item. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryHandle/resolve) + */ resolve(possibleDescendant: FileSystemHandle): Promise; } @@ -9040,9 +11827,17 @@ declare var FileSystemDirectoryHandle: { new(): FileSystemDirectoryHandle; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryReader) */ +/** + * The `FileSystemDirectoryReader` interface of the File and Directory Entries API lets you access the FileSystemFileEntry-based objects (generally FileSystemFileEntry or FileSystemDirectoryEntry) representing each entry in a directory. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryReader) + */ interface FileSystemDirectoryReader { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryReader/readEntries) */ + /** + * The FileSystemDirectoryReader interface's **`readEntries()`** method retrieves the directory entries within the directory being read and delivers them in an array to a provided callback function. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemDirectoryReader/readEntries) + */ readEntries(successCallback: FileSystemEntriesCallback, errorCallback?: ErrorCallback): void; } @@ -9051,19 +11846,47 @@ declare var FileSystemDirectoryReader: { new(): FileSystemDirectoryReader; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry) */ +/** + * The **`FileSystemEntry`** interface of the File and Directory Entries API represents a single entry in a file system. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry) + */ interface FileSystemEntry { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/filesystem) */ + /** + * The read-only **`filesystem`** property of the FileSystemEntry interface contains a resides. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/filesystem) + */ readonly filesystem: FileSystem; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/fullPath) */ + /** + * The read-only **`fullPath`** property of the FileSystemEntry interface returns a string specifying the full, absolute path from the file system's root to the file represented by the entry. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/fullPath) + */ readonly fullPath: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/isDirectory) */ + /** + * The read-only **`isDirectory`** property of the FileSystemEntry interface is `true` if the entry represents a directory (meaning it's a FileSystemDirectoryEntry) and `false` if it's not. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/isDirectory) + */ readonly isDirectory: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/isFile) */ + /** + * The read-only **`isFile`** property of the FileSystemEntry interface is `true` if the entry represents a file (meaning it's a FileSystemFileEntry) and `false` if it's not. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/isFile) + */ readonly isFile: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/name) */ + /** + * The read-only **`name`** property of the FileSystemEntry interface returns a string specifying the entry's name; this is the entry within its parent directory (the last component of the path as indicated by the FileSystemEntry.fullPath property). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/name) + */ readonly name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/getParent) */ + /** + * The FileSystemEntry interface's method **`getParent()`** obtains a ```js-nolint getParent(successCallback, errorCallback) getParent(successCallback) ``` - `successCallback` - : A function which is called when the parent directory entry has been retrieved. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemEntry/getParent) + */ getParent(successCallback?: FileSystemEntryCallback, errorCallback?: ErrorCallback): void; } @@ -9072,9 +11895,17 @@ declare var FileSystemEntry: { new(): FileSystemEntry; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileEntry) */ +/** + * The **`FileSystemFileEntry`** interface of the File and Directory Entries API represents a file in a file system. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileEntry) + */ interface FileSystemFileEntry extends FileSystemEntry { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileEntry/file) */ + /** + * The FileSystemFileEntry interface's method **`file()`** returns a the directory entry. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileEntry/file) + */ file(successCallback: FileCallback, errorCallback?: ErrorCallback): void; } @@ -9084,15 +11915,24 @@ declare var FileSystemFileEntry: { }; /** + * The **`FileSystemFileHandle`** interface of the File System API represents a handle to a file system entry. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileHandle) */ interface FileSystemFileHandle extends FileSystemHandle { readonly kind: "file"; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileHandle/createWritable) */ + /** + * The **`createWritable()`** method of the FileSystemFileHandle interface creates a FileSystemWritableFileStream that can be used to write to a file. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileHandle/createWritable) + */ createWritable(options?: FileSystemCreateWritableOptions): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileHandle/getFile) */ + /** + * The **`getFile()`** method of the If the file on disk changes or is removed after this method is called, the returned ```js-nolint getFile() ``` None. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemFileHandle/getFile) + */ getFile(): Promise; } @@ -9102,16 +11942,29 @@ declare var FileSystemFileHandle: { }; /** + * The **`FileSystemHandle`** interface of the File System API is an object which represents a file or directory entry. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemHandle) */ interface FileSystemHandle { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemHandle/kind) */ + /** + * The **`kind`** read-only property of the `'file'` if the associated entry is a file or `'directory'`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemHandle/kind) + */ readonly kind: FileSystemHandleKind; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemHandle/name) */ + /** + * The **`name`** read-only property of the handle. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemHandle/name) + */ readonly name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemHandle/isSameEntry) */ + /** + * The **`isSameEntry()`** method of the ```js-nolint isSameEntry(fileSystemHandle) ``` - FileSystemHandle - : The `FileSystemHandle` to match against the handle on which the method is invoked. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemHandle/isSameEntry) + */ isSameEntry(other: FileSystemHandle): Promise; } @@ -9121,16 +11974,29 @@ declare var FileSystemHandle: { }; /** + * The **`FileSystemWritableFileStream`** interface of the File System API is a WritableStream object with additional convenience methods, which operates on a single file on disk. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemWritableFileStream) */ interface FileSystemWritableFileStream extends WritableStream { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemWritableFileStream/seek) */ + /** + * The **`seek()`** method of the FileSystemWritableFileStream interface updates the current file cursor offset to the position (in bytes) specified when calling the method. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemWritableFileStream/seek) + */ seek(position: number): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemWritableFileStream/truncate) */ + /** + * The **`truncate()`** method of the FileSystemWritableFileStream interface resizes the file associated with the stream to the specified size in bytes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemWritableFileStream/truncate) + */ truncate(size: number): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemWritableFileStream/write) */ + /** + * The **`write()`** method of the FileSystemWritableFileStream interface writes content into the file the method is called on, at the current file cursor offset. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FileSystemWritableFileStream/write) + */ write(data: FileSystemWriteChunkType): Promise; } @@ -9140,12 +12006,16 @@ declare var FileSystemWritableFileStream: { }; /** - * Focus-related events like focus, blur, focusin, or focusout. + * The **`FocusEvent`** interface represents focus-related events, including Element/focus_event, Element/blur_event, Element/focusin_event, and Element/focusout_event. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FocusEvent) */ interface FocusEvent extends UIEvent { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FocusEvent/relatedTarget) */ + /** + * The **`relatedTarget`** read-only property of the FocusEvent interface is the secondary target, depending on the type of event:
Event name target relatedTarget
Element/blur_event The EventTarget losing focus The EventTarget receiving focus (if any).
Element/focus_event The EventTarget receiving focus The EventTarget losing focus (if any)
Element/focusin_event The EventTarget receiving focus The EventTarget losing focus (if any)
Element/focusout_event The EventTarget losing focus The EventTarget receiving focus (if any)
Note that many elements can't have focus, which is a common reason for `relatedTarget` to be `null`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FocusEvent/relatedTarget) + */ readonly relatedTarget: EventTarget | null; } @@ -9154,33 +12024,89 @@ declare var FocusEvent: { new(type: string, eventInitDict?: FocusEventInit): FocusEvent; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace) */ +/** + * The **`FontFace`** interface of the CSS Font Loading API represents a single usable font face. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace) + */ interface FontFace { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/ascentOverride) */ + /** + * The **`ascentOverride`** property of the FontFace interface returns and sets the ascent metric for the font, the height above the baseline that CSS uses to lay out line boxes in an inline formatting context. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/ascentOverride) + */ ascentOverride: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/descentOverride) */ + /** + * The **`descentOverride`** property of the FontFace interface returns and sets the value of the @font-face/descent-override descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/descentOverride) + */ descentOverride: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/display) */ + /** + * The **`display`** property of the FontFace interface determines how a font face is displayed based on whether and when it is downloaded and ready to use. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/display) + */ display: FontDisplay; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/family) */ + /** + * The **`FontFace.family`** property allows the author to get or set the font family of a FontFace object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/family) + */ family: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/featureSettings) */ + /** + * The **`featureSettings`** property of the FontFace interface retrieves or sets infrequently used font features that are not available from a font's variant properties. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/featureSettings) + */ featureSettings: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/lineGapOverride) */ + /** + * The **`lineGapOverride`** property of the FontFace interface returns and sets the value of the @font-face/line-gap-override descriptor. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/lineGapOverride) + */ lineGapOverride: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/loaded) */ + /** + * The **`loaded`** read-only property of the FontFace interface returns a Promise that resolves with the current `FontFace` object when the font specified in the object's constructor is done loading or rejects with a `SyntaxError`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/loaded) + */ readonly loaded: Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/status) */ + /** + * The **`status`** read-only property of the FontFace interface returns an enumerated value indicating the status of the font, one of `'unloaded'`, `'loading'`, `'loaded'`, or `'error'`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/status) + */ readonly status: FontFaceLoadStatus; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/stretch) */ + /** + * The **`stretch`** property of the FontFace interface retrieves or sets how the font stretches. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/stretch) + */ stretch: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/style) */ + /** + * The **`style`** property of the FontFace interface retrieves or sets the font's style. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/style) + */ style: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/unicodeRange) */ + /** + * The **`unicodeRange`** property of the FontFace interface retrieves or sets the range of unicode code points encompassing the font. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/unicodeRange) + */ unicodeRange: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/weight) */ + /** + * The **`weight`** property of the FontFace interface retrieves or sets the weight of the font. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/weight) + */ weight: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/load) */ + /** + * The **`load()`** method of the FontFace interface requests and loads a font whose `source` was specified as a URL. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFace/load) + */ load(): Promise; } @@ -9195,7 +12121,11 @@ interface FontFaceSetEventMap { "loadingerror": FontFaceSetLoadEvent; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet) */ +/** + * The **`FontFaceSet`** interface of the CSS Font Loading API manages the loading of font-faces and querying of their download status. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet) + */ interface FontFaceSet extends EventTarget { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/loading_event) */ onloading: ((this: FontFaceSet, ev: FontFaceSetLoadEvent) => any) | null; @@ -9203,13 +12133,29 @@ interface FontFaceSet extends EventTarget { onloadingdone: ((this: FontFaceSet, ev: FontFaceSetLoadEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/loadingerror_event) */ onloadingerror: ((this: FontFaceSet, ev: FontFaceSetLoadEvent) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/ready) */ + /** + * The `ready` read-only property of the FontFaceSet interface returns a Promise that resolves to the given FontFaceSet. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/ready) + */ readonly ready: Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/status) */ + /** + * The **`status`** read-only property of the FontFaceSet interface returns the loading state of the fonts in the set. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/status) + */ readonly status: FontFaceSetLoadStatus; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/check) */ + /** + * The `check()` method of the FontFaceSet returns `true` if you can render some text using the given font specification without attempting to use any fonts in this `FontFaceSet` that are not yet fully loaded. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/check) + */ check(font: string, text?: string): boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/load) */ + /** + * The `load()` method of the FontFaceSet forces all the fonts given in parameters to be loaded. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSet/load) + */ load(font: string, text?: string): Promise; forEach(callbackfn: (value: FontFace, key: FontFace, parent: FontFaceSet) => void, thisArg?: any): void; addEventListener(type: K, listener: (this: FontFaceSet, ev: FontFaceSetEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; @@ -9223,9 +12169,17 @@ declare var FontFaceSet: { new(): FontFaceSet; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSetLoadEvent) */ +/** + * The **`FontFaceSetLoadEvent`** interface of the CSS Font Loading API represents events fired at a FontFaceSet after it starts loading font faces. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSetLoadEvent) + */ interface FontFaceSetLoadEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSetLoadEvent/fontfaces) */ + /** + * The **`fontfaces`** read-only property of the An array of FontFace instance. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FontFaceSetLoadEvent/fontfaces) + */ readonly fontfaces: ReadonlyArray; } @@ -9240,24 +12194,48 @@ interface FontFaceSource { } /** - * Provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using the XMLHttpRequest.send() method. It uses the same format a form would use if the encoding type were set to "multipart/form-data". + * The **`FormData`** interface provides a way to construct a set of key/value pairs representing form fields and their values, which can be sent using the Window/fetch, XMLHttpRequest.send() or navigator.sendBeacon() methods. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData) */ interface FormData { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append) */ + /** + * The **`append()`** method of the FormData interface appends a new value onto an existing key inside a `FormData` object, or adds the key if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/append) + */ append(name: string, value: string | Blob): void; append(name: string, value: string): void; append(name: string, blobValue: Blob, filename?: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/delete) */ + /** + * The **`delete()`** method of the FormData interface deletes a key and its value(s) from a `FormData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/delete) + */ delete(name: string): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/get) */ + /** + * The **`get()`** method of the FormData interface returns the first value associated with a given key from within a `FormData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/get) + */ get(name: string): FormDataEntryValue | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/getAll) */ + /** + * The **`getAll()`** method of the FormData interface returns all the values associated with a given key from within a `FormData` object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/getAll) + */ getAll(name: string): FormDataEntryValue[]; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/has) */ + /** + * The **`has()`** method of the FormData interface returns whether a `FormData` object contains a certain key. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/has) + */ has(name: string): boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/set) */ + /** + * The **`set()`** method of the FormData interface sets a new value for an existing key inside a `FormData` object, or adds the key/value if it does not already exist. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormData/set) + */ set(name: string, value: string | Blob): void; set(name: string, value: string): void; set(name: string, blobValue: Blob, filename?: string): void; @@ -9269,10 +12247,14 @@ declare var FormData: { new(form?: HTMLFormElement, submitter?: HTMLElement | null): FormData; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormDataEvent) */ +/** + * The **`FormDataEvent`** interface represents a `formdata` event — such an event is fired on an HTMLFormElement object after the entry list representing the form's data is constructed. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormDataEvent) + */ interface FormDataEvent extends Event { /** - * Returns a FormData object representing names and values of elements associated to the target form. Operations on the FormData object will affect form data to be submitted. + * The `formData` read-only property of the FormDataEvent interface contains the FormData object representing the data contained in the form when the event was fired. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FormDataEvent/formData) */ @@ -9284,7 +12266,11 @@ declare var FormDataEvent: { new(type: string, eventInitDict: FormDataEventInit): FormDataEvent; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/FragmentDirective) */ +/** + * The **`FragmentDirective`** interface is an object exposed to allow code to check whether or not a browser supports text fragments. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/FragmentDirective) + */ interface FragmentDirective { } @@ -9294,22 +12280,31 @@ declare var FragmentDirective: { }; /** + * The **`GPUError`** interface of the WebGPU API is the base interface for errors surfaced by GPUDevice.popErrorScope and the GPUDevice.uncapturederror_event event. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GPUError) */ interface GPUError { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GPUError/message) */ + /** + * The **`message`** read-only property of the A string. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GPUError/message) + */ readonly message: string; } /** - * A change in volume. It is an AudioNode audio-processing module that causes a given gain to be applied to the input data before its propagation to the output. A GainNode always has exactly one input and one output, both with the same number of channels. + * The `GainNode` interface represents a change in volume. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GainNode) */ interface GainNode extends AudioNode { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GainNode/gain) */ + /** + * The `gain` property of the GainNode interface is an a-rate AudioParam representing the amount of gain to apply. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GainNode/gain) + */ readonly gain: AudioParam; } @@ -9319,26 +12314,58 @@ declare var GainNode: { }; /** - * This Gamepad API interface defines an individual gamepad or other controller, allowing access to information such as button presses, axis positions, and id. + * The **`Gamepad`** interface of the Gamepad API defines an individual gamepad or other controller, allowing access to information such as button presses, axis positions, and id. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad) */ interface Gamepad { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/axes) */ + /** + * The **`Gamepad.axes`** property of the Gamepad interface returns an array representing the controls with axes present on the device (e.g., analog thumb sticks). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/axes) + */ readonly axes: ReadonlyArray; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/buttons) */ + /** + * The **`buttons`** property of the Gamepad interface returns an array of GamepadButton objects representing the buttons present on the device. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/buttons) + */ readonly buttons: ReadonlyArray; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/connected) */ - readonly connected: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/id) */ + /** + * The **`Gamepad.connected`** property of the still connected to the system. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/connected) + */ + readonly connected: boolean; + /** + * The **`Gamepad.id`** property of the Gamepad interface returns a string containing some information about the controller. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/id) + */ readonly id: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/index) */ + /** + * The **`Gamepad.index`** property of the Gamepad interface returns an integer that is auto-incremented to be unique for each device currently connected to the system. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/index) + */ readonly index: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/mapping) */ + /** + * The **`Gamepad.mapping`** property of the remapped the controls on the device to a known layout. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/mapping) + */ readonly mapping: GamepadMappingType; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/timestamp) */ + /** + * The **`Gamepad.timestamp`** property of the representing the last time the data for this gamepad was updated. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/timestamp) + */ readonly timestamp: DOMHighResTimeStamp; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/vibrationActuator) */ + /** + * The **`vibrationActuator`** read-only property of the Gamepad interface returns a GamepadHapticActuator object, which represents haptic feedback hardware available on the controller. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Gamepad/vibrationActuator) + */ readonly vibrationActuator: GamepadHapticActuator; } @@ -9348,16 +12375,28 @@ declare var Gamepad: { }; /** - * An individual button of a gamepad or other controller, allowing access to the current state of different types of buttons available on the control device. + * The **`GamepadButton`** interface defines an individual button of a gamepad or other controller, allowing access to the current state of different types of buttons available on the control device. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadButton) */ interface GamepadButton { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadButton/pressed) */ + /** + * The **`GamepadButton.pressed`** property of the the button is currently pressed (`true`) or unpressed (`false`). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadButton/pressed) + */ readonly pressed: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadButton/touched) */ + /** + * The **`touched`** property of the a button capable of detecting touch is currently touched (`true`) or not touched (`false`). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadButton/touched) + */ readonly touched: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadButton/value) */ + /** + * The **`GamepadButton.value`** property of the current state of analog buttons on many modern gamepads, such as the triggers. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadButton/value) + */ readonly value: number; } @@ -9367,12 +12406,16 @@ declare var GamepadButton: { }; /** - * This Gamepad API interface contains references to gamepads connected to the system, which is what the gamepad events Window.gamepadconnected and Window.gamepaddisconnected are fired in response to. + * The GamepadEvent interface of the Gamepad API contains references to gamepads connected to the system, which is what the gamepad events Window.gamepadconnected_event and Window.gamepaddisconnected_event are fired in response to. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadEvent) */ interface GamepadEvent extends Event { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadEvent/gamepad) */ + /** + * The **`GamepadEvent.gamepad`** property of the **GamepadEvent interface** returns a Gamepad object, providing access to the associated gamepad data for fired A Gamepad object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadEvent/gamepad) + */ readonly gamepad: Gamepad; } @@ -9382,14 +12425,22 @@ declare var GamepadEvent: { }; /** - * This Gamepad API interface represents hardware in the controller designed to provide haptic feedback to the user (if available), most commonly vibration hardware. + * The **`GamepadHapticActuator`** interface of the Gamepad API represents hardware in the controller designed to provide haptic feedback to the user (if available), most commonly vibration hardware. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadHapticActuator) */ interface GamepadHapticActuator { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadHapticActuator/playEffect) */ + /** + * The **`playEffect()`** method of the GamepadHapticActuator interface causes the hardware to play a specific vibration effect. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadHapticActuator/playEffect) + */ playEffect(type: GamepadHapticEffectType, params?: GamepadEffectParameters): Promise; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadHapticActuator/reset) */ + /** + * The **`reset()`** method of the GamepadHapticActuator interface stops the hardware from playing an active vibration effect. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GamepadHapticActuator/reset) + */ reset(): Promise; } @@ -9406,16 +12457,28 @@ interface GenericTransformStream { } /** - * An object able to programmatically obtain the position of the device. It gives Web content access to the location of the device. This allows a Web site or app to offer customized results based on the user's location. + * The **`Geolocation`** interface represents an object able to obtain the position of the device programmatically. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Geolocation) */ interface Geolocation { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Geolocation/clearWatch) */ + /** + * The **`clearWatch()`** method of the Geolocation interface is used to unregister location/error monitoring handlers previously installed using Geolocation.watchPosition(). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Geolocation/clearWatch) + */ clearWatch(watchId: number): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Geolocation/getCurrentPosition) */ + /** + * The **`getCurrentPosition()`** method of the Geolocation interface is used to get the current position of the device. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Geolocation/getCurrentPosition) + */ getCurrentPosition(successCallback: PositionCallback, errorCallback?: PositionErrorCallback | null, options?: PositionOptions): void; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Geolocation/watchPosition) */ + /** + * The **`watchPosition()`** method of the Geolocation interface is used to register a handler function that will be called automatically each time the position of the device changes. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Geolocation/watchPosition) + */ watchPosition(successCallback: PositionCallback, errorCallback?: PositionErrorCallback | null, options?: PositionOptions): number; } @@ -9425,26 +12488,59 @@ declare var Geolocation: { }; /** + * The **`GeolocationCoordinates`** interface represents the position and altitude of the device on Earth, as well as the accuracy with which these properties are calculated. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates) */ interface GeolocationCoordinates { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/accuracy) */ + /** + * The **`accuracy`** read-only property of the GeolocationCoordinates interface is a strictly positive `double` representing the accuracy, with a 95% confidence level, of the GeolocationCoordinates.latitude and GeolocationCoordinates.longitude properties expressed in meters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/accuracy) + */ readonly accuracy: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/altitude) */ + /** + * The **`altitude`** read-only property of the GeolocationCoordinates interface is a `double` representing the altitude of the position in meters above the WGS84 ellipsoid (which defines the nominal sea level surface). + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/altitude) + */ readonly altitude: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/altitudeAccuracy) */ + /** + * The **`altitudeAccuracy`** read-only property of the GeolocationCoordinates interface is a strictly positive `double` representing the accuracy, with a 95% confidence level, of the `altitude` expressed in meters. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/altitudeAccuracy) + */ readonly altitudeAccuracy: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/heading) */ + /** + * The **`heading`** read-only property of the GeolocationCoordinates interface is a `double` representing the direction in which the device is traveling. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/heading) + */ readonly heading: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/latitude) */ + /** + * The **`latitude`** read-only property of the GeolocationCoordinates interface is a `double` representing the latitude of the position in decimal degrees. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/latitude) + */ readonly latitude: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/longitude) */ + /** + * The **`longitude`** read-only property of the GeolocationCoordinates interface is a number which represents the longitude of a geographical position, specified in decimal degrees. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/longitude) + */ readonly longitude: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/speed) */ + /** + * The **`speed`** read-only property of the GeolocationCoordinates interface is a `double` representing the velocity of the device in meters per second. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/speed) + */ readonly speed: number | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/toJSON) */ + /** + * The **`toJSON()`** method of the GeolocationCoordinates interface is a Serialization; it returns a JSON representation of the GeolocationCoordinates object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationCoordinates/toJSON) + */ toJSON(): any; } @@ -9454,16 +12550,29 @@ declare var GeolocationCoordinates: { }; /** + * The **`GeolocationPosition`** interface represents the position of the concerned device at a given time. * Available only in secure contexts. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPosition) */ interface GeolocationPosition { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPosition/coords) */ + /** + * The **`coords`** read-only property of the GeolocationPosition interface returns a GeolocationCoordinates object representing a geographic position. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPosition/coords) + */ readonly coords: GeolocationCoordinates; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPosition/timestamp) */ + /** + * The **`timestamp`** read-only property of the GeolocationPosition interface represents the date and time that the position was acquired by the device. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPosition/timestamp) + */ readonly timestamp: EpochTimeStamp; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPosition/toJSON) */ + /** + * The **`toJSON()`** method of the GeolocationPosition interface is a Serialization; it returns a JSON representation of the GeolocationPosition object. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPosition/toJSON) + */ toJSON(): any; } @@ -9472,11 +12581,23 @@ declare var GeolocationPosition: { new(): GeolocationPosition; }; -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPositionError) */ +/** + * The **`GeolocationPositionError`** interface represents the reason of an error occurring when using the geolocating device. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPositionError) + */ interface GeolocationPositionError { - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPositionError/code) */ + /** + * The **`code`** read-only property of the GeolocationPositionError interface is an `unsigned short` representing the error code. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPositionError/code) + */ readonly code: number; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPositionError/message) */ + /** + * The **`message`** read-only property of the GeolocationPositionError interface returns a human-readable string describing the details of the error. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/GeolocationPositionError/message) + */ readonly message: string; readonly PERMISSION_DENIED: 1; readonly POSITION_UNAVAILABLE: 2; @@ -9497,21 +12618,22 @@ interface GlobalEventHandlersEventMap { "animationend": AnimationEvent; "animationiteration": AnimationEvent; "animationstart": AnimationEvent; - "auxclick": MouseEvent; + "auxclick": PointerEvent; "beforeinput": InputEvent; - "beforetoggle": Event; + "beforematch": Event; + "beforetoggle": ToggleEvent; "blur": FocusEvent; "cancel": Event; "canplay": Event; "canplaythrough": Event; "change": Event; - "click": MouseEvent; + "click": PointerEvent; "close": Event; "compositionend": CompositionEvent; "compositionstart": CompositionEvent; "compositionupdate": CompositionEvent; "contextlost": Event; - "contextmenu": MouseEvent; + "contextmenu": PointerEvent; "contextrestored": Event; "copy": ClipboardEvent; "cuechange": Event; @@ -9561,6 +12683,7 @@ interface GlobalEventHandlersEventMap { "pointermove": PointerEvent; "pointerout": PointerEvent; "pointerover": PointerEvent; + "pointerrawupdate": Event; "pointerup": PointerEvent; "progress": ProgressEvent; "ratechange": Event; @@ -9579,7 +12702,7 @@ interface GlobalEventHandlersEventMap { "submit": SubmitEvent; "suspend": Event; "timeupdate": Event; - "toggle": Event; + "toggle": ToggleEvent; "touchcancel": TouchEvent; "touchend": TouchEvent; "touchmove": TouchEvent; @@ -9598,12 +12721,7 @@ interface GlobalEventHandlersEventMap { } interface GlobalEventHandlers { - /** - * Fires when the user aborts the download. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/abort_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/abort_event) */ onabort: ((this: GlobalEventHandlers, ev: UIEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/animationcancel_event) */ onanimationcancel: ((this: GlobalEventHandlers, ev: AnimationEvent) => any) | null; @@ -9614,54 +12732,31 @@ interface GlobalEventHandlers { /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/animationstart_event) */ onanimationstart: ((this: GlobalEventHandlers, ev: AnimationEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/auxclick_event) */ - onauxclick: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; + onauxclick: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/beforeinput_event) */ onbeforeinput: ((this: GlobalEventHandlers, ev: InputEvent) => any) | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/beforematch_event) */ + onbeforematch: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/beforetoggle_event) */ - onbeforetoggle: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when the object loses the input focus. - * @param ev The focus event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/blur_event) - */ + onbeforetoggle: ((this: GlobalEventHandlers, ev: ToggleEvent) => any) | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/blur_event) */ onblur: ((this: GlobalEventHandlers, ev: FocusEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLDialogElement/cancel_event) */ oncancel: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when playback is possible, but would require further buffering. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/canplay_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/canplay_event) */ oncanplay: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/canplaythrough_event) */ oncanplaythrough: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when the contents of the object or selection have changed. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/change_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/change_event) */ onchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when the user clicks the left mouse button on the object - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/click_event) - */ - onclick: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/click_event) */ + onclick: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLDialogElement/close_event) */ onclose: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement/contextlost_event) */ oncontextlost: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when the user clicks the right mouse button in the client area, opening the context menu. - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/contextmenu_event) - */ - oncontextmenu: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/contextmenu_event) */ + oncontextmenu: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement/contextrestored_event) */ oncontextrestored: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/copy_event) */ @@ -9670,91 +12765,31 @@ interface GlobalEventHandlers { oncuechange: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/cut_event) */ oncut: ((this: GlobalEventHandlers, ev: ClipboardEvent) => any) | null; - /** - * Fires when the user double-clicks the object. - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/dblclick_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/dblclick_event) */ ondblclick: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; - /** - * Fires on the source object continuously during a drag operation. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/drag_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/drag_event) */ ondrag: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; - /** - * Fires on the source object when the user releases the mouse at the close of a drag operation. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragend_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragend_event) */ ondragend: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; - /** - * Fires on the target element when the user drags the object to a valid drop target. - * @param ev The drag event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragenter_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragenter_event) */ ondragenter: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; - /** - * Fires on the target object when the user moves the mouse out of a valid drop target during a drag operation. - * @param ev The drag event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragleave_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragleave_event) */ ondragleave: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; - /** - * Fires on the target element continuously while the user drags the object over a valid drop target. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragover_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragover_event) */ ondragover: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; - /** - * Fires on the source object when the user starts to drag a text selection or selected object. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragstart_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/dragstart_event) */ ondragstart: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/drop_event) */ ondrop: ((this: GlobalEventHandlers, ev: DragEvent) => any) | null; - /** - * Occurs when the duration attribute is updated. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/durationchange_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/durationchange_event) */ ondurationchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when the media element is reset to its initial state. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/emptied_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/emptied_event) */ onemptied: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when the end of playback is reached. - * @param ev The event - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/ended_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/ended_event) */ onended: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when an error occurs during object loading. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/error_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/error_event) */ onerror: OnErrorEventHandler; - /** - * Fires when the object receives focus. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/focus_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/focus_event) */ onfocus: ((this: GlobalEventHandlers, ev: FocusEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLFormElement/formdata_event) */ onformdata: ((this: GlobalEventHandlers, ev: FormDataEvent) => any) | null; @@ -9764,119 +12799,47 @@ interface GlobalEventHandlers { oninput: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLInputElement/invalid_event) */ oninvalid: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when the user presses a key. - * @param ev The keyboard event - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/keydown_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/keydown_event) */ onkeydown: ((this: GlobalEventHandlers, ev: KeyboardEvent) => any) | null; /** - * Fires when the user presses an alphanumeric key. - * @param ev The event. * @deprecated * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/keypress_event) */ onkeypress: ((this: GlobalEventHandlers, ev: KeyboardEvent) => any) | null; - /** - * Fires when the user releases a key. - * @param ev The keyboard event - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/keyup_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/keyup_event) */ onkeyup: ((this: GlobalEventHandlers, ev: KeyboardEvent) => any) | null; - /** - * Fires immediately after the browser loads the object. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/SVGElement/load_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/load_event) */ onload: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when media data is loaded at the current playback position. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/loadeddata_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/loadeddata_event) */ onloadeddata: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when the duration and dimensions of the media have been determined. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/loadedmetadata_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/loadedmetadata_event) */ onloadedmetadata: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when Internet Explorer begins looking for media data. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/loadstart_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/loadstart_event) */ onloadstart: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/lostpointercapture_event) */ onlostpointercapture: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; - /** - * Fires when the user clicks the object with either mouse button. - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mousedown_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mousedown_event) */ onmousedown: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseenter_event) */ onmouseenter: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseleave_event) */ onmouseleave: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; - /** - * Fires when the user moves the mouse over the object. - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mousemove_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mousemove_event) */ onmousemove: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; - /** - * Fires when the user moves the mouse pointer outside the boundaries of the object. - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseout_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseout_event) */ onmouseout: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; - /** - * Fires when the user moves the mouse pointer into the object. - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseover_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseover_event) */ onmouseover: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; - /** - * Fires when the user releases a mouse button while the mouse is over the object. - * @param ev The mouse event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseup_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/mouseup_event) */ onmouseup: ((this: GlobalEventHandlers, ev: MouseEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/paste_event) */ onpaste: ((this: GlobalEventHandlers, ev: ClipboardEvent) => any) | null; - /** - * Occurs when playback is paused. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/pause_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/pause_event) */ onpause: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when the play method is requested. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/play_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/play_event) */ onplay: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when the audio or video has started playing. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/playing_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/playing_event) */ onplaying: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/pointercancel_event) */ onpointercancel: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; @@ -9892,62 +12855,33 @@ interface GlobalEventHandlers { onpointerout: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/pointerover_event) */ onpointerover: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/pointerup_event) */ - onpointerup: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; /** - * Occurs to indicate progress while downloading media data. - * @param ev The event. + * Available only in secure contexts. * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/progress_event) + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/pointerrawupdate_event) */ + onpointerrawupdate: ((this: GlobalEventHandlers, ev: Event) => any) | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/pointerup_event) */ + onpointerup: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null; + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/progress_event) */ onprogress: ((this: GlobalEventHandlers, ev: ProgressEvent) => any) | null; - /** - * Occurs when the playback rate is increased or decreased. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/ratechange_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/ratechange_event) */ onratechange: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when the user resets a form. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLFormElement/reset_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLFormElement/reset_event) */ onreset: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLVideoElement/resize_event) */ onresize: ((this: GlobalEventHandlers, ev: UIEvent) => any) | null; - /** - * Fires when the user repositions the scroll box in the scroll bar on the object. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/scroll_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/scroll_event) */ onscroll: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/scrollend_event) */ onscrollend: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/securitypolicyviolation_event) */ onsecuritypolicyviolation: ((this: GlobalEventHandlers, ev: SecurityPolicyViolationEvent) => any) | null; - /** - * Occurs when the seek operation ends. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/seeked_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/seeked_event) */ onseeked: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when the current playback position is moved. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/seeking_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/seeking_event) */ onseeking: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Fires when the current selection changes. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLInputElement/select_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLInputElement/select_event) */ onselect: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Document/selectionchange_event) */ onselectionchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; @@ -9955,31 +12889,16 @@ interface GlobalEventHandlers { onselectstart: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLSlotElement/slotchange_event) */ onslotchange: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when the download has stopped. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/stalled_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/stalled_event) */ onstalled: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLFormElement/submit_event) */ onsubmit: ((this: GlobalEventHandlers, ev: SubmitEvent) => any) | null; - /** - * Occurs if the load operation has been intentionally halted. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/suspend_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/suspend_event) */ onsuspend: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs to indicate the current playback position. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/timeupdate_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/timeupdate_event) */ ontimeupdate: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLElement/toggle_event) */ - ontoggle: ((this: GlobalEventHandlers, ev: Event) => any) | null; + ontoggle: ((this: GlobalEventHandlers, ev: ToggleEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/touchcancel_event) */ ontouchcancel?: ((this: GlobalEventHandlers, ev: TouchEvent) => any) | null | undefined; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/touchend_event) */ @@ -9996,19 +12915,9 @@ interface GlobalEventHandlers { ontransitionrun: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null; /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/Element/transitionstart_event) */ ontransitionstart: ((this: GlobalEventHandlers, ev: TransitionEvent) => any) | null; - /** - * Occurs when the volume is changed, or playback is muted or unmuted. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/volumechange_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/volumechange_event) */ onvolumechange: ((this: GlobalEventHandlers, ev: Event) => any) | null; - /** - * Occurs when playback stops because the next frame of a video resource is not available. - * @param ev The event. - * - * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/waiting_event) - */ + /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLMediaElement/waiting_event) */ onwaiting: ((this: GlobalEventHandlers, ev: Event) => any) | null; /** * @deprecated This is a legacy alias of `onanimationend`. @@ -10042,26 +12951,26 @@ interface GlobalEventHandlers { removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void; } -/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAllCollection) */ +/** + * The **`HTMLAllCollection`** interface represents a collection of _all_ of the document's elements, accessible by index (like an array) and by the element's `id`. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAllCollection) + */ interface HTMLAllCollection { /** - * Returns the number of elements in the collection. + * The **`HTMLAllCollection.length`** property returns the number of items in this HTMLAllCollection. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAllCollection/length) */ readonly length: number; /** - * Returns the item with index index from the collection (determined by tree order). + * The **`item()`** method of the HTMLAllCollection interface returns the element located at the specified offset into the collection, or the element with the specified value for its `id` or `name` attribute. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAllCollection/item) */ item(nameOrIndex?: string): HTMLCollection | Element | null; /** - * Returns the item with ID or name name from the collection. - * - * If there are multiple matching items, then an HTMLCollection object containing all those elements is returned. - * - * Only button, form, iframe, input, map, meta, object, select, and textarea elements can have a name for the purpose of this method; their name is given by the value of their name attribute. + * The **`namedItem()`** method of the HTMLAllCollection interface returns the first Element in the collection whose `id` or `name` attribute matches the specified name, or `null` if no element matches. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAllCollection/namedItem) */ @@ -10075,71 +12984,76 @@ declare var HTMLAllCollection: { }; /** - * Hyperlink elements and provides special properties and methods (beyond those of the regular HTMLElement object interface that they inherit from) for manipulating the layout and presentation of such elements. + * The **`HTMLAnchorElement`** interface represents hyperlink elements and provides special properties and methods (beyond those of the regular HTMLElement object interface that they inherit from) for manipulating the layout and presentation of such elements. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement) */ interface HTMLAnchorElement extends HTMLElement, HTMLHyperlinkElementUtils { - /** - * Sets or retrieves the character set used to encode the object. - * @deprecated - */ + /** @deprecated */ charset: string; + /** @deprecated */ + coords: string; /** - * Sets or retrieves the coordinates of the object. - * @deprecated + * The **`HTMLAnchorElement.download`** property is a string indicating that the linked resource is intended to be downloaded rather than displayed in the browser. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/download) */ - coords: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/download) */ download: string; /** - * Sets or retrieves the language code of the object. + * The **`hreflang`** property of the HTMLAnchorElement interface is a string that is the language of the linked resource. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/hreflang) */ hreflang: string; + /** @deprecated */ + name: string; /** - * Sets or retrieves the shape of the object. - * @deprecated + * The **`ping`** property of the HTMLAnchorElement interface is a space-separated list of URLs. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/ping) */ - name: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/ping) */ ping: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/referrerPolicy) */ + /** + * The **`HTMLAnchorElement.referrerPolicy`** property reflect the HTML `referrerpolicy` attribute of the A string; one of the following: - `no-referrer` - : The Referer header will be omitted entirely. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/referrerPolicy) + */ referrerPolicy: string; /** - * Sets or retrieves the relationship between the object and the destination of the link. + * The **`HTMLAnchorElement.rel`** property reflects the `rel` attribute. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/rel) */ rel: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/relList) */ - get relList(): DOMTokenList; - set relList(value: string); /** - * Sets or retrieves the relationship between the object and the destination of the link. - * @deprecated + * The **`HTMLAnchorElement.relList`** read-only property reflects the `rel` attribute. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/relList) */ + get relList(): DOMTokenList; + set relList(value: string); + /** @deprecated */ rev: string; - /** - * Sets or retrieves the shape of the object. - * @deprecated - */ + /** @deprecated */ shape: string; /** - * Sets or retrieves the window or frame at which to target content. + * The **`target`** property of the HTMLAnchorElement interface is a string that indicates where to display the linked resource. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/target) */ target: string; /** - * Retrieves or sets the text of the object as a string. + * The **`text`** property of the HTMLAnchorElement represents the text inside the element. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/text) */ text: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/type) */ - type: string; + /** + * The **`type`** property of the HTMLAnchorElement interface is a string that indicates the MIME type of the linked resource. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAnchorElement/type) + */ + type: string; addEventListener(type: K, listener: (this: HTMLAnchorElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void; addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void; removeEventListener(type: K, listener: (this: HTMLAnchorElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void; @@ -10152,47 +13066,64 @@ declare var HTMLAnchorElement: { }; /** - * Provides special properties and methods (beyond those of the regular object HTMLElement interface it also has available to it by inheritance) for manipulating the layout and presentation of elements. + * The **`HTMLAreaElement`** interface provides special properties and methods (beyond those of the regular object HTMLElement interface it also has available to it by inheritance) for manipulating the layout and presentation of area elements. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement) */ interface HTMLAreaElement extends HTMLElement, HTMLHyperlinkElementUtils { /** - * Sets or retrieves a text alternative to the graphic. + * The **`alt`** property of the HTMLAreaElement interface specifies the text of the hyperlink, defining the textual label for an image map's link. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/alt) */ alt: string; /** - * Sets or retrieves the coordinates of the object. + * The **`coords`** property of the HTMLAreaElement interface specifies the coordinates of the element's shape as a list of floating-point numbers. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/coords) */ coords: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/download) */ - download: string; /** - * Sets or gets whether clicks in this region cause action. - * @deprecated + * The **`download`** property of the HTMLAreaElement interface is a string indicating that the linked resource is intended to be downloaded rather than displayed in the browser. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/download) */ + download: string; + /** @deprecated */ noHref: boolean; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/ping) */ + /** + * The **`ping`** property of the HTMLAreaElement interface is a space-separated list of URLs. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/ping) + */ ping: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/referrerPolicy) */ + /** + * The **`HTMLAreaElement.referrerPolicy`** property reflect the HTML `referrerpolicy` attribute of the resource. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/referrerPolicy) + */ referrerPolicy: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/rel) */ + /** + * The **`HTMLAreaElement.rel`** property reflects the `rel` attribute. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/rel) + */ rel: string; - /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/relList) */ + /** + * The **`HTMLAreaElement.relList`** read-only property reflects the `rel` attribute. + * + * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/relList) + */ get relList(): DOMTokenList; set relList(value: string); /** - * Sets or retrieves the shape of the object. + * The **`shape`** property of the HTMLAreaElement interface specifies the shape of an image map area. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/shape) */ shape: string; /** - * Sets or retrieves the window or frame at which to target content. + * The **`target`** property of the HTMLAreaElement interface is a string that indicates where to display the linked resource. * * [MDN Reference](https://developer.mozilla.org/docs/Web/API/HTMLAreaElement/target) */ @@ -10209,7 +13140,7 @@ declare var HTMLAreaElement: { }; /** - * Provides access to the properties of