TypeScript types for new JavaScript

Common errors

• Cannot find name 'FileSystemFileHandle'.

  cause The type definitions for `new-javascript` are not correctly included in your project, or `tsconfig.json` is missing the necessary configuration.
  fix Ensure `new-javascript` is installed as a dev dependency (`npm i -D new-javascript`) and add `"new-javascript"` to the `compilerOptions.types` array in your `tsconfig.json`. Alternatively, add `/// <reference types="new-javascript" />` to the top of your TypeScript files.

• Property 'startViewTransition' does not exist on type 'Document'.

  cause TypeScript's default DOM library (e.g., `lib.dom.d.ts`) does not yet include this specific Web API, and `new-javascript`'s types are not being loaded or are not correctly configured.
  fix Verify that `new-javascript` is included in your `tsconfig.json`'s `compilerOptions.types` array. Also, ensure your `compilerOptions.lib` includes `"dom"` and potentially `"dom.iterable"` and `"esnext"` to cover a broad range of browser APIs and modern JavaScript features.

• Duplicate identifier 'CompressionStream'.

  cause This error occurs when `CompressionStream` (or another type provided by `new-javascript`) is defined in multiple places, most commonly by both `new-javascript` and a newer version of TypeScript's built-in `dom` library.
  fix Check your TypeScript version; if it's recently updated, it might natively include the type. You may need to remove `new-javascript` if the official types are sufficient, or find a way to exclude the specific conflicting type definition from `new-javascript` (e.g., via `tsconfig.json` `files` or `exclude` if granular enough, or wait for an `new-javascript` update that defers to native types).

Warnings

• gotcha As this package provides type definitions for experimental or rapidly evolving Web APIs, there is a significant potential for future type conflicts or duplications once official definitions are integrated into TypeScript's standard `dom` library or other `@types` packages. This can lead to `Duplicate identifier` errors during compilation.
  Fix: Regularly review TypeScript release notes and official `@types` packages for updates to the Web API landscape. If conflicts occur, you may need to selectively exclude conflicting files from `new-javascript` or remove the package entirely if official types suffice. Consider pinning `new-javascript` to a specific version to control updates.
• gotcha This package includes type definitions for worker-exclusive interfaces (e.g., `FileReaderSync`, `FileSystemSyncAccessHandle`) by default. If your project is exclusively for the main thread, these types may incorrectly suggest the availability of APIs not present in that context, potentially leading to runtime errors if used.
  Fix: Currently, `new-javascript` does not offer an option to disable the inclusion of worker-exclusive types. Developers should be mindful of the context in which they are building and avoid using these types outside of actual Web Worker environments. For other worker types (Service Worker, Shared Worker), refer to the `Better-TypeScript` package.
• gotcha The APIs type-declared in `new-javascript` are often from WICG or other draft specifications, meaning their interfaces and behaviors are subject to change. This can lead to breaking type changes in future minor versions of `new-javascript` as it strives to align with the latest drafts, potentially requiring code adjustments without a major version bump of the package.
  Fix: Always review the changelog before updating `new-javascript`. Consider pinning the package to exact versions or using a tool that flags updates for manual review. Stay informed about the status of the upstream Web API specifications you are using.

Install

• npm install new-javascript npm
• yarn add new-javascript yarn
• pnpm add new-javascript pnpm

Imports

• Global Web API types (e.g., FileSystemHandle)
  wrong:

  import type { FileSystemHandle } from 'new-javascript';

  correct:

  /// <reference types="new-javascript" />

  This package primarily provides global type augmentations, not runtime values. Types are typically included via reference directives in TypeScript files or by listing 'new-javascript' in the `compilerOptions.types` array in `tsconfig.json`.
• AudioWorklet Global Types
  wrong:

  import type { AudioWorkletGlobalScope } from 'new-javascript/worklet/audio';

  correct:

  /// <reference types="new-javascript/worklet/audio" />

  Specific worklet environments like AudioWorklets require their own dedicated reference paths to ensure correct global type augmentation for those contexts. Direct `import type` statements are not the intended mechanism for these global augmentations.
• PaintWorklet Global Types
  wrong:

  import type { PaintWorkletGlobalScope } from 'new-javascript/worklet/paint';

  correct:

  /// <reference types="new-javascript/worklet/paint" />

  Similar to AudioWorklets, PaintWorklet types are provided via a specific reference path. Using the correct `/// <reference>` directive ensures the browser's global scope is correctly augmented for PaintWorklet development.

Quickstart

Demonstrates how to install and configure `new-javascript` types via `tsconfig.json` and a reference directive, then utilizes types from the File System Access API and View Transitions API in a runnable TypeScript example.

npm i -D new-javascript@latest

// tsconfig.json
// {
//   "compilerOptions": {
//     "types": ["new-javascript"],
//     "lib": ["dom", "dom.iterable", "esnext"]
//   }
// }

// Example TypeScript file (e.g., src/main.ts)
/// <reference types="new-javascript" />

async function demonstrateNewApiUsage() {
  // Using File System Access API types, like FileSystemFileHandle
  if ('showOpenFilePicker' in window) {
    try {
      const [fileHandle] = await window.showOpenFilePicker();
      console.log('File picked:', fileHandle.name);
      const file = await fileHandle.getFile();
      console.log('File size:', file.size, 'bytes');
      // Additional operations with fileHandle or file
    } catch (error) {
      if (error instanceof DOMException && error.name === 'AbortError') {
        console.log('File picker was dismissed.');
      } else {
        console.error('Error with File System Access API:', error);
      }
    }
  } else {
    console.warn('File System Access API not supported by this browser.');
  }

  // Using View Transitions API types, like document.startViewTransition
  if (document.startViewTransition) {
    console.log('View Transitions API is supported. Starting a transition.');
    const transition = document.startViewTransition(() => {
      // Perform DOM updates that trigger the transition
      const contentDiv = document.getElementById('content-area');
      if (contentDiv) {
        contentDiv.innerHTML = `<h2>Content updated at ${new Date().toLocaleTimeString()}</h2><p>This is new content.</p>`;
      }
      return Promise.resolve();
    });

    try {
      await transition.finished;
      console.log('View transition completed successfully.');
    } catch (error) {
      console.error('View transition failed:', error);
    }
  } else {
    console.warn('View Transitions API not supported by this browser.');
  }
}

demonstrateNewApiUsage();