powerlines 0.24.8 → 0.25.0

package/dist/plugin-utils/{context-BITGF5LZ.d.cts → context-PtfEjz3_.d.cts}

@@ -1,5 +1,5 @@
 import { EnvPaths } from '@stryke/env/get-env-paths';
-import { NonUndefined, MaybePromise, FunctionLike, DeepPartial as DeepPartial$1 } from '@stryke/types/base';
+import { MaybePromise, NonUndefined, FunctionLike, DeepPartial as DeepPartial$1 } from '@stryke/types/base';
 import { PackageJson } from '@stryke/types/package-json';
 import { Jiti } from 'jiti';
 import { SourceMap } from 'magic-string';
@@ -13,7 +13,6 @@ import { TypeDefinition, TypeDefinitionParameter } from '@stryke/types/configura
 import { AssetGlob } from '@stryke/types/file';
 import { ResolvedPreviewOptions, PreviewOptions } from 'vite';
 import { ResolveOptions as ResolveOptions$1 } from '@stryke/fs/resolve';
-import { StatSyncOptions, Stats, RmDirOptions, RmOptions, Mode, MakeDirectoryOptions as MakeDirectoryOptions$1, WriteFileOptions as WriteFileOptions$1 } from 'node:fs';
 import { TsConfigJson, CompilerOptions } from '@stryke/types/tsconfig';
 import ts from 'typescript';
 import { ArrayValues } from '@stryke/types/array';
@@ -155,9 +154,107 @@ interface BuildConfig {
 }
 type BuildResolvedConfig = Omit<BuildConfig, "override">;
 
-declare const __VFS_PATCH__ = "__VFS_PATCH__";
-declare const __VFS_REVERT__ = "__VFS_REVERT__";
-type OutputModeType = "fs" | "virtual";
+declare enum StoragePreset {
+    VIRTUAL = "virtual",
+    FS = "fs"
+}
+/**
+ * Interface defining the methods and properties for a storage adapter.
+ */
+interface StorageAdapter {
+    /**
+     * A name identifying the storage adapter type.
+     */
+    name: string;
+    /**
+     * Checks if a key exists in the storage.
+     *
+     * @param key - The key to check for existence.
+     * @returns A promise that resolves to `true` if the key exists, otherwise `false`.
+     */
+    exists: (key: string) => Promise<boolean>;
+    /**
+     * Synchronously checks if a key exists in the storage.
+     *
+     * @param key - The key to check for existence.
+     * @returns Returns `true` if the key exists, otherwise `false`.
+     */
+    existsSync: (key: string) => boolean;
+    /**
+     * Read a value associated with a key from the storage.
+     *
+     * @param key - The key to read the value for.
+     * @returns A promise that resolves to the value if found, otherwise `null`.
+     */
+    get: (key: string) => Promise<string | null>;
+    /**
+     * Synchronously reads the value associated with a key from the storage.
+     *
+     * @param key - The key to read the value for.
+     * @returns The value if found, otherwise `null`.
+     */
+    getSync: (key: string) => string | null;
+    /**
+     * Writes a value to the storage for the given key.
+     *
+     * @param key - The key to associate the value with.
+     * @param value - The value to store.
+     */
+    set: (key: string, value: string) => Promise<void>;
+    /**
+     * Synchronously writes a value to the storage for the given key.
+     *
+     * @param key - The key to associate the value with.
+     * @param value - The value to store.
+     */
+    setSync: (key: string, value: string) => void;
+    /**
+     * Removes a value from the storage.
+     *
+     * @param key - The key whose value should be removed.
+     */
+    remove: (key: string) => Promise<void>;
+    /**
+     * Synchronously removes a value from the storage.
+     *
+     * @param key - The key whose value should be removed.
+     */
+    removeSync: (key: string) => void;
+    /**
+     * Remove all entries from the storage that match the provided base path.
+     *
+     * @param base - The base path or prefix to clear entries from.
+     */
+    clear: (base?: string) => Promise<void>;
+    /**
+     * Synchronously remove all entries from the storage that match the provided base path.
+     *
+     * @param base - The base path or prefix to clear entries from.
+     */
+    clearSync: (base?: string) => void;
+    /**
+     * Lists all keys under the provided base path.
+     *
+     * @param base - The base path or prefix to list keys from.
+     * @returns A promise resolving to the list of keys.
+     */
+    list: (base?: string) => Promise<string[]>;
+    /**
+     * Synchronously lists all keys under the provided base path.
+     *
+     * @param base - The base path or prefix to list keys from.
+     * @returns The list of keys.
+     */
+    listSync: (base?: string) => string[];
+    /**
+     * Releases any resources held by the storage adapter.
+     */
+    dispose: () => MaybePromise<void>;
+}
+/**
+ * A mapping of file paths to storage adapter names and their corresponding {@link StorageAdapter} instances.
+ */
+type StoragePort = Record<string, StorageAdapter>;
 interface VirtualFileMetadata {
     /**
      * The identifier for the file data.
@@ -177,10 +274,6 @@ interface VirtualFileMetadata {
      * - `normal`: Indicates that the file is a standard file without any special role.
      */
     type: string;
-    /**
-     * The output mode of the file.
-     */
-    mode: string;
     /**
      * Additional metadata associated with the file.
      */
@@ -202,16 +295,9 @@ interface VirtualFileData {
      * This string represents the purpose/function of the file in the virtual file system. A potential list of variants includes:
      * - `builtin`: Indicates that the file is a built-in module provided by the system.
      * - `entry`: Indicates that the file is an entry point for execution.
-     * - `chunk`: Indicates that the file is a code chunk, typically used in code-splitting scenarios.
-     * - `prebuilt-chunk`: Indicates that the file is a prebuilt code chunk.
-     * - `asset`: Indicates that the file is a static asset, such as an image or stylesheet.
      * - `normal`: Indicates that the file is a standard file without any special role.
      */
     type?: string;
-    /**
-     * The output mode of the file.
-     */
-    mode?: string;
     /**
      * Additional metadata associated with the file.
      */
@@ -227,21 +313,18 @@ interface VirtualFile extends Required<VirtualFileData>, VirtualFileMetadata {
      */
     timestamp: number;
 }
-interface ResolveFSOptions {
-    mode?: OutputModeType;
-}
-type MakeDirectoryOptions = (Mode | MakeDirectoryOptions$1) & ResolveFSOptions;
-interface PowerlinesWriteFileOptions extends ResolveFSOptions {
+interface WriteOptions {
     /**
      * Should the file skip formatting before being written?
      *
      * @defaultValue false
      */
     skipFormat?: boolean;
+    /**
+     * Additional metadata for the file.
+     */
+    meta?: VirtualFileMetadata;
 }
-type NodeWriteFileOptions = WriteFileOptions$1;
-type WriteFileOptions = NodeWriteFileOptions | PowerlinesWriteFileOptions;
-type WriteFileData = string | NodeJS.ArrayBufferView | VirtualFileData;
 interface ResolveOptions extends ResolveOptions$1 {
     /**
      * If true, the module is being resolved as an entry point.
@@ -265,14 +348,6 @@ interface ResolveOptions extends ResolveOptions$1 {
     skipNodeModulesBundle?: boolean;
 }
 interface VirtualFileSystemInterface {
-    /**
-     * Patches the File System to include the virtual file system (VFS) contents.
-     */
-    [__VFS_PATCH__]: () => void;
-    /**
-     * Reverts the virtual file system (VFS) to its previous state.
-     */
-    [__VFS_REVERT__]: () => void;
     /**
      * The underlying file metadata.
      */
@@ -285,208 +360,92 @@ interface VirtualFileSystemInterface {
      * A map of module ids to their file paths.
      */
     paths: Readonly<Record<string, string>>;
-    /**
-     * Check if a path or id corresponds to a virtual file **(does not actually exists on disk)**.
-     *
-     * @param pathOrId - The path or id to check.
-     * @param importer - The importer path, if any.
-     * @param options - Optional parameters for resolving the path.
-     * @returns Whether the path or id corresponds to a virtual file **(does not actually exists on disk)**.
-     */
-    isVirtual: (pathOrId: string, importer?: string, options?: ResolveOptions) => boolean;
-    /**
-     * Check if a path or id corresponds to a file written to the file system **(actually exists on disk)**.
-     *
-     * @param pathOrId - The path or id to check.
-     * @param importer - The importer path, if any.
-     * @param options - Optional parameters for resolving the path.
-     * @returns Whether the path or id corresponds to a file written to the file system **(actually exists on disk)**.
-     */
-    isPhysical: (pathOrId: string, importer?: string, options?: ResolveOptions) => boolean;
     /**
      * Checks if a file exists in the virtual file system (VFS).
      *
-     * @param path - The path of the file to check.
+     * @param path - The path or id of the file.
      * @returns `true` if the file exists, otherwise `false`.
      */
-    isFile: (path: string) => boolean;
+    exists: (path: string) => Promise<boolean>;
     /**
-     * Checks if a directory exists in the virtual file system (VFS).
+     * Synchronously Checks if a file exists in the virtual file system (VFS).
      *
-     * @param path - The path of the directory to check.
-     * @returns `true` if the directory exists, otherwise `false`.
+     * @param path - The path or id of the file.
+     * @returns `true` if the file exists, otherwise `false`.
      */
-    isDirectory: (path: string) => boolean;
+    existsSync: (path: string) => boolean;
     /**
-     * Checks if a file exists in the virtual file system (VFS).
+     * Checks if a file is virtual in the virtual file system (VFS).
      *
-     * @param pathOrId - The path or id of the file.
-     * @returns `true` if the file exists, otherwise `false`.
+     * @param path - The path or id of the file.
+     * @returns `true` if the file is virtual, otherwise `false`.
      */
-    existsSync: (pathOrId: string) => boolean;
+    isVirtual: (path: string) => boolean;
     /**
      * Gets the metadata of a file in the virtual file system (VFS).
      *
-     * @param pathOrId - The path or id of the file.
+     * @param path - The path or id of the file.
      * @returns The metadata of the file if it exists, otherwise undefined.
      */
-    getMetadata: (pathOrId: string) => VirtualFileMetadata | undefined;
-    /**
-     * Gets the stats of a file in the virtual file system (VFS).
-     *
-     * @param pathOrId - The path or id of the file.
-     * @param options - Optional parameters for getting the stats.
-     * @returns The stats of the file if it exists, otherwise undefined.
-     */
-    lstat: (pathOrId: string, options?: StatSyncOptions & {
-        bigint?: false | undefined;
-        throwIfNoEntry: false;
-    }) => Promise<Stats>;
-    /**
-     * Gets the stats of a file in the virtual file system (VFS).
-     *
-     * @param pathOrId - The path or id of the file.
-     * @param options - Optional parameters for getting the stats.
-     * @returns The stats of the file if it exists, otherwise undefined.
-     */
-    lstatSync: (pathOrId: string, options?: StatSyncOptions & {
-        bigint?: false | undefined;
-        throwIfNoEntry: false;
-    }) => Stats | undefined;
-    /**
-     * Gets the stats of a file in the virtual file system (VFS).
-     *
-     * @param pathOrId - The path or id of the file.
-     * @returns The stats of the file if it exists, otherwise false.
-     */
-    stat: (pathOrId: string, options?: StatSyncOptions & {
-        bigint?: false | undefined;
-        throwIfNoEntry: false;
-    }) => Promise<Stats>;
-    /**
-     * Gets the stats of a file in the virtual file system (VFS).
-     *
-     * @param pathOrId - The path or id of the file.
-     * @returns The stats of the file if it exists, otherwise false.
-     */
-    statSync: (pathOrId: string, options?: StatSyncOptions & {
-        bigint?: false | undefined;
-        throwIfNoEntry: false;
-    }) => Stats | undefined;
+    getMetadata: (path: string) => VirtualFileMetadata | undefined;
     /**
      * Lists files in a given path.
      *
      * @param path - The path to list files from.
-     * @param options - Options for listing files, such as encoding and recursion.
      * @returns An array of file names in the specified path.
      */
-    readdirSync: (path: string, options?: {
-        encoding: BufferEncoding | null;
-        withFileTypes?: false | undefined;
-        recursive?: boolean | undefined;
-    } | BufferEncoding) => string[];
+    listSync: (path: string) => string[];
     /**
      * Lists files in a given path.
      *
      * @param path - The path to list files from.
-     * @param options - Options for listing files, such as encoding and recursion.
      * @returns An array of file names in the specified path.
      */
-    readdir: (path: string, options?: {
-        encoding: BufferEncoding | null;
-        withFileTypes?: false | undefined;
-        recursive?: boolean | undefined;
-    } | BufferEncoding) => Promise<string[]>;
+    list: (path: string) => Promise<string[]>;
     /**
      * Removes a file or symbolic link in the virtual file system (VFS).
      *
      * @param path - The path to the file to remove.
      * @returns A promise that resolves when the file is removed.
      */
-    unlinkSync: (path: string, options?: ResolveFSOptions) => void;
+    removeSync: (path: string) => void;
     /**
      * Asynchronously removes a file or symbolic link in the virtual file system (VFS).
      *
      * @param path - The path to the file to remove.
      * @returns A promise that resolves when the file is removed.
      */
-    unlink: (path: string, options?: ResolveFSOptions) => Promise<void>;
-    /**
-     * Removes a directory in the virtual file system (VFS).
-     *
-     * @param path - The path to create the directory at.
-     * @param options - Options for creating the directory.
-     */
-    rmdirSync: (path: string, options?: RmDirOptions & ResolveFSOptions) => any;
-    /**
-     * Removes a directory in the virtual file system (VFS).
-     *
-     * @param path - The path to create the directory at.
-     * @param options - Options for creating the directory.
-     * @returns A promise that resolves to the path of the created directory, or undefined if the directory could not be created.
-     */
-    rmdir: (path: string, options?: RmDirOptions & ResolveFSOptions) => Promise<void>;
-    /**
-     * Removes a file or directory in the virtual file system (VFS).
-     *
-     * @param path - The path to the file or directory to remove.
-     * @param options - Options for removing the file or directory.
-     * @returns A promise that resolves when the file or directory is removed.
-     */
-    rm: (path: string, options?: RmOptions & ResolveFSOptions) => Promise<void>;
-    /**
-     * Synchronously removes a file or directory in the virtual file system (VFS).
-     *
-     * @param path - The path to the file or directory to remove.
-     * @param options - Options for removing the file or directory.
-     */
-    rmSync: (path: string, options?: RmOptions & ResolveFSOptions) => void;
-    /**
-     * Creates a directory in the virtual file system (VFS).
-     *
-     * @param path - The path to create the directory at.
-     * @param options - Options for creating the directory.
-     * @returns A promise that resolves to the path of the created directory, or undefined if the directory could not be created.
-     */
-    mkdirSync: (path: string, options?: MakeDirectoryOptions) => string | undefined;
-    /**
-     * Creates a directory in the virtual file system (VFS).
-     *
-     * @param path - The path to create the directory at.
-     * @param options - Options for creating the directory.
-     * @returns A promise that resolves to the path of the created directory, or undefined if the directory could not be created.
-     */
-    mkdir: (path: string, options?: MakeDirectoryOptions) => Promise<string | undefined>;
+    remove: (path: string) => Promise<void>;
     /**
      * Reads a file from the virtual file system (VFS).
      *
-     * @param pathOrId - The path or id of the file.
+     * @param path - The path or id of the file.
      * @returns The contents of the file if it exists, otherwise undefined.
      */
-    readFile: (pathOrId: string) => Promise<string | undefined>;
+    read: (path: string) => Promise<string | undefined>;
     /**
      * Reads a file from the virtual file system (VFS).
      *
-     * @param pathOrId - The path or id of the file.
+     * @param path - The path or id of the file.
      */
-    readFileSync: (pathOrId: string) => string | undefined;
+    readSync: (path: string) => string | undefined;
     /**
      * Writes a file to the virtual file system (VFS).
      *
      * @param path - The path to the file.
      * @param data - The contents of the file.
-     * @param options - Optional parameters for writing the file.
+     * @param options - Options for writing the file.
      * @returns A promise that resolves when the file is written.
      */
-    writeFile: (path: string, data?: WriteFileData, options?: WriteFileOptions) => Promise<void>;
+    write: (path: string, data: string, options?: WriteOptions) => Promise<void>;
     /**
      * Writes a file to the virtual file system (VFS).
      *
      * @param path - The path to the file.
      * @param data - The contents of the file.
-     * @param options - Optional parameters for writing the file.
+     * @param options - Options for writing the file.
      */
-    writeFileSync: (path: string, data?: WriteFileData, options?: WriteFileOptions) => void;
+    writeSync: (path: string, data: string, options?: WriteOptions) => void;
     /**
      * Moves a file from one path to another in the virtual file system (VFS).
      *
@@ -529,13 +488,6 @@ interface VirtualFileSystemInterface {
      * @returns An array of file paths matching the provided pattern(s)
      */
     globSync: (pattern: string | string[]) => string[];
-    /**
-     * Resolves a path or id to a file path in the virtual file system.
-     *
-     * @param pathOrId - The path or id of the file to resolve.
-     * @returns The resolved path of the file if it exists, otherwise false.
-     */
-    realpathSync: (pathOrId: string) => string;
     /**
      * A helper function to resolve modules using the Jiti resolver
      *
@@ -589,7 +541,7 @@ interface ResolvedEntryTypeDefinition extends TypeDefinition {
      */
     output?: string;
 }
-type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "ssr" | "preview"> & Required<Pick<EnvironmentConfig, "consumer" | "mode" | "ssr">> & {
+type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "ssr" | "preview"> & Required<Pick<EnvironmentConfig, "consumer" | "ssr">> & {
     /**
      * The name of the environment
      */
@@ -600,9 +552,9 @@ type EnvironmentResolvedConfig = Omit<EnvironmentConfig, "consumer" | "mode" | "
     preview?: ResolvedPreviewOptions;
 };
 type ResolvedAssetGlob = AssetGlob & Required<Pick<AssetGlob, "input">>;
-type OutputResolvedConfig = Required<Omit<OutputConfig, "assets"> & {
+type OutputResolvedConfig = Required<Omit<OutputConfig, "assets" | "storage"> & {
     assets: ResolvedAssetGlob[];
-}>;
+}> & Pick<OutputConfig, "storage">;
 /**
  * The resolved options for the Powerlines project configuration.
  */
@@ -997,13 +949,16 @@ interface OutputConfig {
      *
      * @defaultValue "\{projectRoot\}/dist"
      */
-    distPath?: string;
+    buildPath?: string;
     /**
-     * The format of the output files
+     * The folder where the generated runtime artifacts will be located
      *
-     * @defaultValue "virtual"
+     * @remarks
+     * This folder will contain all runtime artifacts and builtins generated during the "prepare" phase.
+     *
+     * @defaultValue "\{projectRoot\}/.powerlines"
      */
-    mode?: OutputModeType;
+    artifactsPath?: string;
     /**
      * The path of the generated runtime declaration file relative to the workspace root.
      *
@@ -1019,15 +974,6 @@ interface OutputConfig {
      * @defaultValue "powerlines"
      */
     builtinPrefix?: string;
-    /**
-     * The folder where the generated runtime artifacts will be located
-     *
-     * @remarks
-     * This folder will contain all runtime artifacts and builtins generated during the "prepare" phase.
-     *
-     * @defaultValue "\{projectRoot\}/.powerlines"
-     */
-    artifactsFolder?: string;
     /**
      * The module format of the output files
      *
@@ -1044,42 +990,21 @@ interface OutputConfig {
      * The assets can be specified as a string (path to the asset) or as an object with a `glob` property (to match multiple files). The paths are relative to the project root directory.
      */
     assets?: Array<string | AssetGlob>;
-}
-interface BaseConfig {
-    /**
-     * The name of the project
-     */
-    name?: string;
-    /**
-     * The project display title
-     *
-     * @remarks
-     * This option is used in documentation generation and other places where a human-readable title is needed.
-     */
-    title?: string;
     /**
-     * A description of the project
+     * A string preset or a custom {@link StoragePort} to provide fine-grained control over generated/output file storage.
      *
      * @remarks
-     * If this option is not provided, the build process will try to use the \`description\` value from the `\package.json\` file.
-     */
-    description?: string;
-    /**
-     * The log level to use for the Powerlines processes.
+     * If a string preset is provided, it must be one of the following values:
+     * - `"virtual"`: Uses the local file system for storage.
+     * - `"fs"`: Uses an in-memory virtual file system for storage.
      *
-     * @defaultValue "info"
-     */
-    logLevel?: LogLevelLabel | null;
-    /**
-     * A custom logger function to use for logging messages
-     */
-    customLogger?: LogFn;
-    /**
-     * Explicitly set a mode to run in. This mode will be used at various points throughout the Powerlines processes, such as when compiling the source code.
+     * If a custom {@link StoragePort} is provided, it will be used for all file storage operations during the build process.
      *
-     * @defaultValue "production"
+     * @defaultValue "virtual"
      */
-    mode?: "development" | "test" | "production";
+    storage?: StoragePort | StoragePreset;
+}
+interface BaseConfig {
     /**
      * The entry point(s) for the application
      */
@@ -1163,6 +1088,40 @@ interface EnvironmentConfig extends BaseConfig {
     consumer?: "client" | "server";
 }
 interface CommonUserConfig extends BaseConfig {
+    /**
+     * The name of the project
+     */
+    name?: string;
+    /**
+     * The project display title
+     *
+     * @remarks
+     * This option is used in documentation generation and other places where a human-readable title is needed.
+     */
+    title?: string;
+    /**
+     * A description of the project
+     *
+     * @remarks
+     * If this option is not provided, the build process will try to use the \`description\` value from the `\package.json\` file.
+     */
+    description?: string;
+    /**
+     * The log level to use for the Powerlines processes.
+     *
+     * @defaultValue "info"
+     */
+    logLevel?: LogLevelLabel | null;
+    /**
+     * A custom logger function to use for logging messages
+     */
+    customLogger?: LogFn;
+    /**
+     * Explicitly set a mode to run in. This mode will be used at various points throughout the Powerlines processes, such as when compiling the source code.
+     *
+     * @defaultValue "production"
+     */
+    mode?: "development" | "test" | "production";
     /**
      * The type of project being built
      *
@@ -1213,7 +1172,7 @@ interface CommonUserConfig extends BaseConfig {
      * A string identifier that allows a child framework or tool to identify itself when using Powerlines.
      *
      * @remarks
-     * If no values are provided for {@link OutputConfig.dts | output.dts}, {@link OutputConfig.builtinPrefix | output.builtinPrefix}, or {@link OutputConfig.artifactsFolder | output.artifactsFolder}, this value will be used as the default.
+     * If no values are provided for {@link OutputConfig.dts | output.dts}, {@link OutputConfig.builtinPrefix | output.builtinPrefix}, or {@link OutputConfig.artifactsPath | output.artifactsFolder}, this value will be used as the default.
      *
      * @defaultValue "powerlines"
      */
@@ -1469,17 +1428,15 @@ interface UnresolvedContext<TResolvedConfig extends ResolvedConfig = ResolvedCon
      * @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 - Options for writing the file
      */
-    emitBuiltin: (code: string, id: string, path?: string, options?: PowerlinesWriteFileOptions) => Promise<void>;
+    emitBuiltin: (code: string, id: string, path?: string) => Promise<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 - Options for writing the file
      */
-    emitEntry: (code: string, path: string, options?: PowerlinesWriteFileOptions) => Promise<void>;
+    emitEntry: (code: string, path: string) => Promise<void>;
     /**
      * A function to update the context fields using a new user configuration options
      */