{"id":11391,"library":"new-javascript","title":"TypeScript types for new JavaScript","description":"This package, `new-javascript`, provides TypeScript type definitions for cutting-edge and experimental Web APIs and JavaScript features that are not yet incorporated into TypeScript's standard `dom` library or `@types/web`. As of version 0.4.7, it covers a wide range of specifications from groups like WICG, including the File System Access API, View Transitions, and Compression Streams. The project's release cadence is driven by the evolution of these web standards and TypeScript's integration schedule. A key differentiator is its proactive approach to providing types for early-stage APIs, using automated WebIDL-to-TypeScript conversion with manual refinement. It also uniquely includes worker-exclusive interfaces by default and offers specific type declarations for various worklet types through distinct import paths, helping developers target specific environments.","status":"active","version":"0.4.7","language":"javascript","source_language":"en","source_url":"https://github.com/BenjaminAster/TypeScript-types-for-new-JavaScript","tags":["javascript"],"install":[{"cmd":"npm install new-javascript","lang":"bash","label":"npm"},{"cmd":"yarn add new-javascript","lang":"bash","label":"yarn"},{"cmd":"pnpm add new-javascript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"import type { FileSystemHandle } from 'new-javascript';","symbol":"Global Web API types (e.g., FileSystemHandle)","correct":"/// <reference types=\"new-javascript\" />"},{"note":"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.","wrong":"import type { AudioWorkletGlobalScope } from 'new-javascript/worklet/audio';","symbol":"AudioWorklet Global Types","correct":"/// <reference types=\"new-javascript/worklet/audio\" />"},{"note":"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.","wrong":"import type { PaintWorkletGlobalScope } from 'new-javascript/worklet/paint';","symbol":"PaintWorklet Global Types","correct":"/// <reference types=\"new-javascript/worklet/paint\" />"}],"quickstart":{"code":"npm i -D new-javascript@latest\n\n// tsconfig.json\n// {\n//   \"compilerOptions\": {\n//     \"types\": [\"new-javascript\"],\n//     \"lib\": [\"dom\", \"dom.iterable\", \"esnext\"]\n//   }\n// }\n\n// Example TypeScript file (e.g., src/main.ts)\n/// <reference types=\"new-javascript\" />\n\nasync function demonstrateNewApiUsage() {\n  // Using File System Access API types, like FileSystemFileHandle\n  if ('showOpenFilePicker' in window) {\n    try {\n      const [fileHandle] = await window.showOpenFilePicker();\n      console.log('File picked:', fileHandle.name);\n      const file = await fileHandle.getFile();\n      console.log('File size:', file.size, 'bytes');\n      // Additional operations with fileHandle or file\n    } catch (error) {\n      if (error instanceof DOMException && error.name === 'AbortError') {\n        console.log('File picker was dismissed.');\n      } else {\n        console.error('Error with File System Access API:', error);\n      }\n    }\n  } else {\n    console.warn('File System Access API not supported by this browser.');\n  }\n\n  // Using View Transitions API types, like document.startViewTransition\n  if (document.startViewTransition) {\n    console.log('View Transitions API is supported. Starting a transition.');\n    const transition = document.startViewTransition(() => {\n      // Perform DOM updates that trigger the transition\n      const contentDiv = document.getElementById('content-area');\n      if (contentDiv) {\n        contentDiv.innerHTML = `<h2>Content updated at ${new Date().toLocaleTimeString()}</h2><p>This is new content.</p>`;\n      }\n      return Promise.resolve();\n    });\n\n    try {\n      await transition.finished;\n      console.log('View transition completed successfully.');\n    } catch (error) {\n      console.error('View transition failed:', error);\n    }\n  } else {\n    console.warn('View Transitions API not supported by this browser.');\n  }\n}\n\ndemonstrateNewApiUsage();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The type definitions for `new-javascript` are not correctly included in your project, or `tsconfig.json` is missing the necessary configuration.","error":"Cannot find name 'FileSystemFileHandle'."},{"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.","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.","error":"Property 'startViewTransition' does not exist on type 'Document'."},{"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).","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.","error":"Duplicate identifier 'CompressionStream'."}],"ecosystem":"npm"}