@powerlines/plugin-nodejs 0.1.0 → 0.1.1

package/dist/powerlines/src/types/context.d.cts

@@ -0,0 +1,414 @@
+import { ResolveOptions, VirtualFile, VirtualFileSystemInterface, WriteOptions } from "./fs.cjs";
+import { ParsedTypeScriptConfig } from "./tsconfig.cjs";
+import { InlineConfig, LogFn, UserConfig, WorkspaceConfig } from "./config.cjs";
+import { EnvironmentResolvedConfig, ResolvedConfig, ResolvedEntryTypeDefinition } from "./resolved.cjs";
+import { NonUndefined } from "@stryke/types/base";
+import { EnvPaths } from "@stryke/env/get-env-paths";
+import { FetchRequestOptions } from "@stryke/http/fetch";
+import { PackageJson } from "@stryke/types/package-json";
+import { Jiti } from "jiti";
+import { SourceMap } from "magic-string";
+import { ParseResult, ParserOptions } from "oxc-parser";
+import { Range } from "semver";
+import { Project } from "ts-morph";
+import { RequestInfo, Response } from "undici";
+import { ExternalIdResult, UnpluginBuildContext, UnpluginContext, UnpluginMessage } from "unplugin";
+
+//#region ../powerlines/src/types/context.d.ts
+
+/**
+ * The severity level of a {@link LogRecord}.
+ */
+type LogLevel = "debug" | "info" | "warning" | "error" | "fatal";
+declare const LogLevel: {
+  DEBUG: LogLevel;
+  INFO: LogLevel;
+  WARNING: LogLevel;
+  ERROR: LogLevel;
+  FATAL: LogLevel;
+};
+interface MetaInfo {
+  /**
+   * The checksum generated from the resolved options
+   */
+  checksum: string;
+  /**
+   * The build id
+   */
+  buildId: string;
+  /**
+   * The release id
+   */
+  releaseId: string;
+  /**
+   * The build timestamp
+   */
+  timestamp: number;
+  /**
+   * A hash that represents the path to the project root directory
+   */
+  projectRootHash: string;
+  /**
+   * A hash that represents the path to the project root directory
+   */
+  configHash: string;
+}
+interface Resolver extends Jiti {
+  plugin: Jiti;
+}
+interface TransformResult$1 {
+  code: string;
+  map: SourceMap | null;
+}
+/**
+ * Options for initializing or updating the context with new configuration values
+ */
+interface InitContextOptions {
+  /**
+   * If false, the plugin will be loaded after all other plugins.
+   *
+   * @defaultValue true
+   */
+  isHighPriority: boolean;
+}
+/**
+ * Options for fetch requests made via the context's {@link Context.fetch} method
+ */
+interface FetchOptions extends FetchRequestOptions {
+  /**
+   * An indicator specifying that the request should bypass any caching
+   */
+  skipCache?: boolean;
+}
+/**
+ * Options for parsing code using [Oxc-Parser](https://github.com/oxc/oxc)
+ */
+interface ParseOptions extends ParserOptions {
+  /**
+   * When true this allows return statements to be outside functions to e.g. support parsing CommonJS code.
+   */
+  allowReturnOutsideFunction?: boolean;
+}
+interface EmitOptions extends WriteOptions {
+  /**
+   * If true, will emit the file using {@link UnpluginBuildContext.emitFile | the bundler's emit function}.
+   */
+  emitWithBundler?: boolean;
+  needsCodeReference?: Parameters<UnpluginBuildContext["emitFile"]>[0]["needsCodeReference"];
+  originalFileName?: Parameters<UnpluginBuildContext["emitFile"]>[0]["originalFileName"];
+}
+/**
+ * Options for emitting entry virtual files
+ */
+type EmitEntryOptions = EmitOptions & Omit<ResolvedEntryTypeDefinition, "file">;
+/**
+ * The unresolved Powerlines context.
+ *
+ * @remarks
+ * This context is used before the user configuration has been fully resolved after the `config`.
+ */
+interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> {
+  /**
+   * The Storm workspace configuration
+   */
+  workspaceConfig: WorkspaceConfig;
+  /**
+   * An object containing the options provided to Powerlines
+   */
+  config: Omit<TResolvedConfig["userConfig"], "build" | "output"> & Required<Pick<TResolvedConfig["userConfig"], "build" | "output">> & {
+    projectRoot: NonUndefined<TResolvedConfig["userConfig"]["root"]>;
+    sourceRoot: NonUndefined<TResolvedConfig["userConfig"]["sourceRoot"]>;
+    output: TResolvedConfig["output"];
+  };
+  /**
+   * A logging function for the Powerlines engine
+   */
+  log: LogFn;
+  /**
+   * A logging function for fatal messages
+   */
+  fatal: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for error messages
+   */
+  error: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for warning messages
+   */
+  warn: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for informational messages
+   */
+  info: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for debug messages
+   */
+  debug: (message: string | UnpluginMessage) => void;
+  /**
+   * A logging function for trace messages
+   */
+  trace: (message: string | UnpluginMessage) => void;
+  /**
+   * The metadata information
+   */
+  meta: MetaInfo;
+  /**
+   * The metadata information currently written to disk
+   */
+  persistedMeta?: MetaInfo;
+  /**
+   * The Powerlines artifacts directory
+   */
+  artifactsPath: string;
+  /**
+   * The path to the Powerlines builtin runtime modules directory
+   */
+  builtinsPath: string;
+  /**
+   * The path to the Powerlines entry modules directory
+   */
+  entryPath: string;
+  /**
+   * The path to the Powerlines TypeScript declaration files directory
+   */
+  dtsPath: string;
+  /**
+   * The path to a directory where the reflection data buffers (used by the build processes) are stored
+   */
+  dataPath: string;
+  /**
+   * The path to a directory where the project cache (used by the build processes) is stored
+   */
+  cachePath: string;
+  /**
+   * The Powerlines environment paths
+   */
+  envPaths: EnvPaths;
+  /**
+   * The file system path to the Powerlines package installation
+   */
+  powerlinesPath: string;
+  /**
+   * The relative path to the Powerlines workspace root directory
+   */
+  relativeToWorkspaceRoot: string;
+  /**
+   * The project's `package.json` file content
+   */
+  packageJson: PackageJson & Record<string, any>;
+  /**
+   * The project's `project.json` file content
+   */
+  projectJson?: Record<string, any>;
+  /**
+   * The dependency installations required by the project
+   */
+  dependencies: Record<string, string | Range>;
+  /**
+   * The development dependency installations required by the project
+   */
+  devDependencies: Record<string, string | Range>;
+  /**
+   * The parsed TypeScript configuration from the `tsconfig.json` file
+   */
+  tsconfig: ParsedTypeScriptConfig;
+  /**
+   * The entry points of the source code
+   */
+  entry: ResolvedEntryTypeDefinition[];
+  /**
+   * The virtual file system manager used during the build process to reference generated runtime files
+   */
+  fs: VirtualFileSystemInterface;
+  /**
+   * The Jiti module resolver
+   */
+  resolver: Resolver;
+  /**
+   * The builtin module id that exist in the Powerlines virtual file system
+   */
+  builtins: string[];
+  /**
+   * The {@link Project} instance used for type reflection and module manipulation
+   *
+   * @see https://ts-morph.com/
+   *
+   * @remarks
+   * This instance is created lazily on first access.
+   */
+  program: Project;
+  /**
+   * A function to perform HTTP fetch requests
+   *
+   * @remarks
+   * This function uses a caching layer to avoid duplicate requests during the Powerlines process.
+   *
+   * @example
+   * ```ts
+   * const response = await context.fetch("https://api.example.com/data");
+   * const data = await response.json();
+   * ```
+   *
+   * @see https://github.com/nodejs/undici
+   *
+   * @param input - The URL to fetch.
+   * @param options - The fetch request options.
+   * @returns A promise that resolves to a response returned by the fetch.
+   */
+  fetch: (input: RequestInfo, options?: FetchOptions) => Promise<Response>;
+  /**
+   * Parse code using [Oxc-Parser](https://github.com/oxc/oxc) into an (ESTree-compatible)[https://github.com/estree/estree] AST object.
+   *
+   * @remarks
+   * This function can be used to parse TypeScript code into an AST for further analysis or transformation.
+   *
+   * @example
+   * ```ts
+   * const ast = context.parse("const x: number = 42;");
+   * ```
+   *
+   * @see https://rollupjs.org/plugin-development/#this-parse
+   * @see https://github.com/oxc/oxc
+   *
+   * @param code - The source code to parse.
+   * @param options - The options to pass to the parser.
+   * @returns An (ESTree-compatible)[https://github.com/estree/estree] AST object.
+   */
+  parse: (code: string, options?: ParseOptions) => Promise<ParseResult>;
+  /**
+   * A helper function to resolve modules using the Jiti resolver
+   *
+   * @remarks
+   * This function can be used to resolve modules relative to the project root directory.
+   *
+   * @example
+   * ```ts
+   * const resolvedPath = await context.resolve("some-module", "/path/to/importer");
+   * ```
+   *
+   * @param id - The module to resolve.
+   * @param importer - An optional path to the importer module.
+   * @param options - Additional resolution options.
+   * @returns A promise that resolves to the resolved module path.
+   */
+  resolve: (id: string, importer?: string, options?: ResolveOptions) => Promise<ExternalIdResult | undefined>;
+  /**
+   * A helper function to load modules using the Jiti resolver
+   *
+   * @remarks
+   * This function can be used to load modules relative to the project root directory.
+   *
+   * @example
+   * ```ts
+   * const module = await context.load("some-module", "/path/to/importer");
+   * ```
+   *
+   * @param id - The module to load.
+   * @returns A promise that resolves to the loaded module.
+   */
+  load: (id: string) => Promise<TransformResult$1 | undefined>;
+  /**
+   * The Powerlines builtin virtual files
+   */
+  getBuiltins: () => Promise<VirtualFile[]>;
+  /**
+   * Resolves a file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the file
+   * @param path - The path to write the file to
+   * @param options - Additional options for writing the file
+   */
+  emit: (code: string, path: string, options?: EmitOptions) => Promise<void>;
+  /**
+   * Synchronously resolves a file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the file
+   * @param path - The path to write the file to
+   * @param options - Additional options for writing the file
+   */
+  emitSync: (code: string, path: string, options?: EmitOptions) => void;
+  /**
+   * Resolves a builtin virtual file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the builtin file
+   * @param id - The unique identifier of the builtin file
+   * @param path - An optional path to write the builtin file to
+   * @param options - Additional options for writing the builtin file
+   */
+  emitBuiltin: (code: string, id: string, path?: string, options?: EmitOptions) => Promise<void>;
+  /**
+   * Synchronously resolves a builtin virtual file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the builtin file
+   * @param id - The unique identifier of the builtin file
+   * @param path - An optional path to write the builtin file to
+   * @param options - Additional options for writing the builtin file
+   */
+  emitBuiltinSync: (code: string, id: string, path?: string, options?: EmitOptions) => void;
+  /**
+   * Resolves a entry virtual file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the entry file
+   * @param path - An optional path to write the entry file to
+   * @param options - Additional options for writing the entry file
+   */
+  emitEntry: (code: string, path: string, options?: EmitEntryOptions) => Promise<void>;
+  /**
+   * Synchronously resolves a entry virtual file and writes it to the VFS if it does not already exist
+   *
+   * @param code - The source code of the entry file
+   * @param path - An optional path to write the entry file to
+   * @param options - Additional options for writing the entry file
+   */
+  emitEntrySync: (code: string, path: string, options?: EmitEntryOptions) => void;
+  /**
+   * A function to update the context fields using a new user configuration options
+   */
+  withUserConfig: (userConfig: UserConfig, options?: InitContextOptions) => Promise<void>;
+  /**
+   * A function to update the context fields using inline configuration options
+   */
+  withInlineConfig: (inlineConfig: InlineConfig, options?: InitContextOptions) => Promise<void>;
+  /**
+   * Create a new logger instance
+   *
+   * @param name - The name to use for the logger instance
+   * @returns A logger function
+   */
+  createLog: (name: string | null) => LogFn;
+  /**
+   * Extend the current logger instance with a new name
+   *
+   * @param name - The name to use for the extended logger instance
+   * @returns A logger function
+   */
+  extendLog: (name: string) => LogFn;
+  /**
+   * Generates a checksum representing the current context state
+   *
+   * @returns A promise that resolves to a string representing the checksum
+   */
+  generateChecksum: () => Promise<string>;
+}
+type Context<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = Omit<UnresolvedContext<TResolvedConfig>, "config"> & {
+  /**
+   * The fully resolved Powerlines configuration
+   */
+  config: TResolvedConfig;
+};
+interface PluginContext<out TResolvedConfig extends ResolvedConfig = ResolvedConfig> extends Context<TResolvedConfig>, UnpluginContext {
+  /**
+   * The environment specific resolved configuration
+   */
+  environment: EnvironmentResolvedConfig;
+  /**
+   * An alternative property name for the {@link log} property
+   *
+   * @remarks
+   * This is provided for compatibility with other logging libraries that expect a `logger` property.
+   */
+  logger: LogFn;
+}
+type BuildPluginContext<TResolvedConfig extends ResolvedConfig = ResolvedConfig> = UnpluginBuildContext & PluginContext<TResolvedConfig>;
+//#endregion
+export { BuildPluginContext, Context, LogLevel, PluginContext, UnresolvedContext };