@equinor/聚变-进口

用于导入和传输 TypeScript、 JavaScript 和 JSON 配置文件的工具 节点.js 运行时间 使用 兴建。 。 。 .

[大 此软件包与 文件路径,而不是 URL 。 它用于在运行时在Node.js CLI工具中加载配置脚本并构建管道.

安装

pnpm add @equinor/fusion-imports

何时使用

快开始

import { importConfig } from '@equinor/fusion-imports';

interface AppSettings {
  name: string;
  port: number;
}

// Resolves app.config.ts → app.config.js → app.config.json
const { config, path } = await importConfig<AppSettings>('app.config');
console.log(`Loaded ${path}:`, config);

API 密码

importConfig<C>(basename, options?)

通过碱名解析配置文件,按顺序检测扩展名( S).ts, (中文(简体) ), .mjs, (中文(简体) ), .js, (中文(简体) ), .json). JSON文件直接解析;脚本文件被捆绑并被动态导入.

import { importConfig } from '@equinor/fusion-imports';

interface MyConfig {
  name: string;
  bar: { foobar: number };
}

interface ScriptModule {
  generateConfig: (options: { env: string }) => MyConfig;
}

const { config } = await importConfig<MyConfig, ScriptModule>('my-config', {
  script: {
    resolve: (module) => module.generateConfig({ env: 'production' }),
  },
});

默认为模块 default 导出为配置值。 提供 script.resolve 以提取不同的导出或调用工厂函数.

选项

importScript<M>(entryPoint, options?)

用 esbuilt(ESM,外接包)并动态地导入输出 。 自动包含两个内置的 esbuilt 插件 :

• importMetaResolvePlugin - 决心 import.meta.resolve() 要求建立时的相对路径.
• rawMarkdownPlugin ——支持 ?raw 进口商品 .md 编号 : .mdx 文档.

import { importScript } from '@equinor/fusion-imports';

interface Greeting { greet(name: string): string }
const mod = await importScript<Greeting>('./greet.ts');
console.log(mod.greet('World'));

构建自定义

ImportScriptOptions 继承全部 esbuild.BuildOptions 除外 entryPoints, (中文(简体) ), bundle,以及 format。您可以通过自定义插件,定义化名,或者更改输出目录 :

import { importScript } from '@equinor/fusion-imports';
import alias from 'esbuild-plugin-alias';

const mod = await importScript('./entry.ts', {
  plugins: [alias({ '@app': './src' })],
  outfile: '/tmp/bundle.js',
});

importJSON<T>(filePath, encoding?)

从磁盘读取一个 JSON 文件并返回解析的内容。 随原出错投出为 cause 如果文件无法读取或包含无效的JSON.

import { importJSON } from '@equinor/fusion-imports';

interface Manifest { name: string; version: string }
const manifest = await importJSON<Manifest>('./package.json');

resolveConfigFile(baseName, options?)

返回第一个可访问配置文件的绝对路径,与给定的基准名和扩展名列表相匹配。 需要路径而不导入文件时有用 .

import { resolveConfigFile } from '@equinor/fusion-imports';

const configPath = await resolveConfigFile('app.config', {
  baseDir: '/project',
  extensions: ['.ts', '.json'],
});

插件

rawMarkdownPlugin(options?)

拦截的 Esbuild 插件 ?raw 用于标记下的文件和返回的导入 作为默认导出字符串的内容。 自动包含 importScript。 。 。 .

// In a file bundled by importScript:
import readme from '../../README.md?raw';
console.log(readme); // raw markdown string

createImportMetaResolvePlugin()

替换的 Esbuild 插件 import.meta.resolve('./relative') 电话 已解决 file:// 构建时的 URL 。 自动包含 importScript。 。 。 .

处理错误

软件包为文件系统故障提供了两个错误类别:

两者均延长 Error 并附加原节点.js错误为 cause数字 :

import { importConfig, FileNotFoundError } from '@equinor/fusion-imports';

try {
  await importConfig('missing');
} catch (error) {
  if (error instanceof FileNotFoundError) {
    console.error('Config not found:', error.message);
  }
}