{"id":19584781,"url":"https://github.com/flex-development/esm-types","last_synced_at":"2026-04-24T20:03:25.004Z","repository":{"id":109438708,"uuid":"609400030","full_name":"flex-development/esm-types","owner":"flex-development","description":"TypeScript definitions for ECMAScript modules","archived":false,"fork":false,"pushed_at":"2024-04-23T01:54:35.000Z","size":1534,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-25T09:59:44.233Z","etag":null,"topics":["esm","esmodules","loader-hooks","node","node-loader","nodejs","typescript","typescript-definitions"],"latest_commit_sha":null,"homepage":"https://github.com/flex-development/esm-types","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flex-development.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/funding.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["flex-development"]}},"created_at":"2023-03-04T03:58:24.000Z","updated_at":"2023-07-26T03:33:30.000Z","dependencies_parsed_at":"2024-04-19T02:29:51.088Z","dependency_job_id":"383d8dae-40ba-4237-b123-40897991eda5","html_url":"https://github.com/flex-development/esm-types","commit_stats":{"total_commits":51,"total_committers":2,"mean_commits":25.5,"dds":0.3137254901960784,"last_synced_commit":"196ba4ca2eb438eab3b2e86a2a67b31fdfa5057f"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/flex-development/esm-types","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fesm-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fesm-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fesm-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fesm-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flex-development","download_url":"https://codeload.github.com/flex-development/esm-types/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fesm-types/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32238748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esm","esmodules","loader-hooks","node","node-loader","nodejs","typescript","typescript-definitions"],"created_at":"2024-11-11T07:49:43.058Z","updated_at":"2026-04-24T20:03:24.983Z","avatar_url":"https://github.com/flex-development.png","language":"TypeScript","funding_links":["https://github.com/sponsors/flex-development"],"categories":[],"sub_categories":[],"readme":"# esm-types\n\n[![github release](https://img.shields.io/github/v/release/flex-development/esm-types.svg?include_prereleases\u0026sort=semver)](https://github.com/flex-development/esm-types/releases/latest)\n[![npm](https://img.shields.io/npm/v/@flex-development/esm-types.svg)](https://npmjs.com/package/@flex-development/esm-types)\n[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)\n[![license](https://img.shields.io/github/license/flex-development/esm-types.svg)](LICENSE.md)\n[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\u0026logoColor=ffffff)](https://conventionalcommits.org/)\n[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\u0026logoColor=ffffff)](https://typescriptlang.org/)\n[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\u0026logo=vitest\u0026logoColor=ffffff)](https://vitest.dev/)\n[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\u0026logo=yarn\u0026logoColor=ffffff)](https://yarnpkg.com/)\n\n[TypeScript][1] definitions for [ECMAScript modules][2]\n\n## Contents\n\n- [What is this?](#what-is-this)\n- [Install](#install)\n- [Use](#use)\n- [API](#api)\n  - [Enums](#enums)\n  - [Hooks](#hooks)\n  - [Interfaces](#interfaces)\n  - [Type Definitions](#type-definitions)\n- [Related](#related)\n- [Contribute](#contribute)\n\n## What is this?\n\nThis package contains [TypeScript][1] definitions for [ECMAScript module][2] utilities and loader hooks.\n\n## Install\n\nThis package is [ESM only][3].\n\n```sh\nyarn add @flex-development/esm-types\nyarn add -D @types/node\n```\n\nFrom Git:\n\n```sh\nyarn add @flex-development/esm-types@flex-development/esm-types\nyarn add -D @types/node\n```\n\n\u003cblockquote\u003e\n  \u003csmall\u003e\n    See \u003ca href='https://yarnpkg.com/features/protocols#git'\u003eGit - Protocols | Yarn\u003c/a\u003e\n    \u0026nbsp;for details on requesting a specific branch, commit, or tag.\n  \u003c/small\u003e\n\u003c/blockquote\u003e\n\n## Use\n\n```sh\ntouch loader.mjs\n```\n\n```js\n/**\n * @file Custom Loader Hooks\n * @module loader\n * @see https://nodejs.org/api/esm.html#loaders\n */\n\nimport { DECORATOR_REGEX } from '@flex-development/decorator-regex'\nimport * as esm from '@flex-development/esm-types'\nimport * as mlly from '@flex-development/mlly'\nimport * as pathe from '@flex-development/pathe'\nimport * as tscu from '@flex-development/tsconfig-utils'\nimport * as tutils from '@flex-development/tutils'\nimport * as esbuild from 'esbuild'\nimport { URL, fileURLToPath, pathToFileURL } from 'node:url'\nimport ts from 'typescript'\n\n// add support for extensionless files in \"bin\" scripts\n// https://github.com/nodejs/modules/issues/488\nmlly.EXTENSION_FORMAT_MAP.set('', esm.Format.COMMONJS)\n\n/**\n * {@linkcode URL} of tsconfig file.\n *\n * @type {URL}\n * @const tsconfig\n */\nconst tsconfig = mlly.toURL('tsconfig.json')\n\n/**\n * TypeScript compiler options.\n *\n * @type {tscu.CompilerOptions}\n * @const compilerOptions\n */\nconst compilerOptions = tscu.loadCompilerOptions(tsconfig)\n\n/**\n * Determines how the given module `url` should be interpreted, retrieved, and\n * parsed.\n *\n * @see {@linkcode esm.LoadHookContext}\n * @see {@linkcode esm.LoadHookResult}\n * @see {@linkcode esm.LoadHook}\n * @see {@linkcode esm.ResolvedModuleUrl}\n * @see https://nodejs.org/api/esm.html#loadurl-context-nextload\n *\n * @async\n *\n * @param {esm.ResolvedModuleUrl} url - Resolved module URL\n * @param {esm.LoadHookContext} context - Hook context\n * @return {Promise\u003cesm.LoadHookResult\u003e} Hook result\n */\nexport const load = async (url, context) =\u003e {\n  // get module format\n  context.format = context.format ?? (await mlly.getFormat(url))\n\n  // validate import assertions\n  mlly.validateAssertions(url, context.format, context.importAssertions)\n\n  /**\n   * File extension of {@linkcode url}.\n   *\n   * @type {pathe.Ext | tutils.EmptyString}\n   * @const ext\n   */\n  const ext = pathe.extname(url)\n\n  /**\n   * Module source code.\n   *\n   * @type {esm.Source\u003cUint8Array | string\u003e | undefined}\n   * @var source\n   */\n  let source = await mlly.getSource(url, { format: context.format })\n\n  // transform typescript files\n  if (/^\\.(?:cts|mts|tsx?)$/.test(ext) \u0026\u0026 !/\\.d\\.(?:cts|mts|ts)$/.test(url)) {\n    // push require condition for .cts files and update format\n    if (ext === '.cts') {\n      context.conditions = context.conditions ?? []\n      context.conditions.unshift('require', 'node')\n      context.format = esm.Format.MODULE\n    }\n\n    // resolve path aliases\n    source = await tscu.resolvePaths(source, {\n      conditions: context.conditions,\n      ext: '',\n      parent: url,\n      tsconfig\n    })\n\n    // resolve modules\n    source = await mlly.resolveModules(source, {\n      conditions: context.conditions,\n      parent: url\n    })\n\n    // emit decorator metadata\n    if (DECORATOR_REGEX.test(source)) {\n      const { outputText } = ts.transpileModule(source, {\n        compilerOptions: { ...compilerOptions, sourceMap: false },\n        fileName: url\n      })\n\n      source = outputText\n    }\n\n    // transpile source code\n    const { code } = await esbuild.transform(source, {\n      format: 'esm',\n      loader: ext.slice(/^\\.[cm]/.test(ext) ? 2 : 1),\n      minify: false,\n      sourcefile: fileURLToPath(url),\n      sourcemap: 'inline',\n      target: `node${process.versions.node}`,\n      tsconfigRaw: { compilerOptions }\n    })\n\n    // set source code to transpiled source\n    source = code\n  }\n\n  return { format: context.format, shortCircuit: true, source }\n}\n\n/**\n * Resolves the given module `specifier`, and its module format as a hint to the\n * {@linkcode load} hook.\n *\n * Adds supports for:\n *\n * - Path alias resolution\n * - Extensionless file and directory index resolution\n *\n * @see {@linkcode esm.ResolveHookContext}\n * @see {@linkcode esm.ResolveHookResult}\n * @see {@linkcode esm.ResolveHook}\n * @see https://nodejs.org/api/esm.html#resolvespecifier-context-nextresolve\n *\n * @async\n *\n * @param {string} specifier - Module specifier\n * @param {esm.ResolveHookContext} context - Hook context\n * @return {Promise\u003cesm.ResolveHookResult\u003e} Hook result\n */\nexport const resolve = async (specifier, context) =\u003e {\n  const { conditions, parentURL: parent } = context\n\n  // resolve path alias\n  specifier = await mlly.resolveAlias(specifier, {\n    aliases: compilerOptions.paths,\n    conditions,\n    cwd: pathToFileURL(compilerOptions.baseUrl),\n    parent\n  })\n\n  /**\n   * Resolved module {@linkcode URL}.\n   *\n   * @type {URL}\n   * @const url\n   */\n  const url = await mlly.resolveModule(specifier, {\n    conditions,\n    parent: parent?.startsWith('file:') ? parent : specifier\n  })\n\n  return {\n    format: await mlly.getFormat(url),\n    shortCircuit: true,\n    url: url.href\n  }\n}\n```\n\n## API\n\nThis package exports the identifiers listed below.\n\nThere is no default export.\n\n### Enums\n\n- [`AssertType`](src/enums/assert-type.ts)\n- [`Format`](src/enums/format.ts)\n\n### Hooks\n\n- [`GetFormatHookContext`](src/hooks/get-format-context.ts)\n- [`GetFormatHookResult`](src/hooks/get-format-result.ts)\n- [`GetFormatHook`](src/hooks/get-format.ts)\n- [`GetSourceHookContext`](src/hooks/get-source-context.ts)\n- [`GetSourceHook`](src/hooks/get-source.ts)\n- [`GlobalPreloadHookContext`](src/hooks/global-preload-context.ts)\n- [`GlobalPreloadHook`](src/hooks/global-preload.ts)\n- [`LoadHookContext`](src/hooks/load-context.ts)\n- [`LoadHookResult`](src/hooks/load-result.ts)\n- [`LoadHook`](src/hooks/load.ts)\n- [`ResolveHookContext`](src/hooks/resolve-context.ts)\n- [`ResolveHookResult`](src/hooks/resolve-result.ts)\n- [`ResolveHook`](src/hooks/resolve.ts)\n- [`SourceHookResult`](src/hooks/source-result.ts)\n- [`TransformSourceHookContext`](src/hooks/transform-source-context.ts)\n- [`TransformSourceHook`](src/hooks/transform-source.ts)\n\n### Interfaces\n\n- [`ImportAssertions`](src/interfaces/import-assertions.ts)\n\n### Type Definitions\n\n- [`FileUrl`](src/types/url-file.ts)\n- [`ResolvedModuleUrl`](src/types/url-resolved-module.ts)\n- [`Source`](src/types/source.ts)\n\n## Related\n\n- [pkg-types][4] \u0026mdash; [TypeScript][1] definitions for `package.json`\n\n## Contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n[1]: https://www.typescriptlang.org\n[2]: https://nodejs.org/api/esm.html\n[3]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n[4]: https://github.com/flex-development/pkg-types\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fesm-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflex-development%2Fesm-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fesm-types/lists"}