powerlines 0.24.8 → 0.25.0

package/dist/types/fs.d.cts

@@ -1,10 +1,110 @@
 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 { MaybePromise } from '@stryke/types/base';
 
 type VirtualFileExtension = "js" | "ts" | "jsx" | "tsx";
 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.
@@ -24,10 +124,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.
      */
@@ -49,16 +145,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.
      */
@@ -74,21 +163,19 @@ 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;
+type WriteData = string | NodeJS.ArrayBufferView | VirtualFileData;
 interface ResolveOptions extends ResolveOptions$1 {
     /**
      * If true, the module is being resolved as an entry point.
@@ -112,14 +199,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.
      */
@@ -132,208 +211,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).
      *
@@ -376,13 +339,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
      *
@@ -423,17 +379,15 @@ interface VirtualFileSystemInterface {
     dispose: () => Promise<void>;
 }
 declare type __ΩVirtualFileExtension = any[];
-declare type __ΩOutputModeType = any[];
+declare type __ΩStoragePreset = any[];
+declare type __ΩStorageAdapter = any[];
+declare type __ΩStoragePort = any[];
 declare type __ΩVirtualFileMetadata = any[];
 declare type __ΩVirtualFileData = any[];
 declare type __ΩVirtualFile = any[];
-declare type __ΩResolveFSOptions = any[];
-declare type __ΩMakeDirectoryOptions = any[];
-declare type __ΩPowerlinesWriteFileOptions = any[];
-declare type __ΩNodeWriteFileOptions = any[];
-declare type __ΩWriteFileOptions = any[];
-declare type __ΩWriteFileData = any[];
+declare type __ΩWriteOptions = any[];
+declare type __ΩWriteData = any[];
 declare type __ΩResolveOptions = any[];
 declare type __ΩVirtualFileSystemInterface = any[];
 
-export { type MakeDirectoryOptions, type NodeWriteFileOptions, type OutputModeType, type PowerlinesWriteFileOptions, type ResolveFSOptions, type ResolveOptions, type VirtualFile, type VirtualFileData, type VirtualFileExtension, type VirtualFileMetadata, type VirtualFileSystemInterface, type WriteFileData, type WriteFileOptions, __VFS_PATCH__, __VFS_REVERT__, type __ΩMakeDirectoryOptions, type __ΩNodeWriteFileOptions, type __ΩOutputModeType, type __ΩPowerlinesWriteFileOptions, type __ΩResolveFSOptions, type __ΩResolveOptions, type __ΩVirtualFile, type __ΩVirtualFileData, type __ΩVirtualFileExtension, type __ΩVirtualFileMetadata, type __ΩVirtualFileSystemInterface, type __ΩWriteFileData, type __ΩWriteFileOptions };
+export { type ResolveOptions, type StorageAdapter, type StoragePort, StoragePreset, type VirtualFile, type VirtualFileData, type VirtualFileExtension, type VirtualFileMetadata, type VirtualFileSystemInterface, type WriteData, type WriteOptions, __VFS_PATCH__, __VFS_REVERT__, type __ΩResolveOptions, type __ΩStorageAdapter, type __ΩStoragePort, type __ΩStoragePreset, type __ΩVirtualFile, type __ΩVirtualFileData, type __ΩVirtualFileExtension, type __ΩVirtualFileMetadata, type __ΩVirtualFileSystemInterface, type __ΩWriteData, type __ΩWriteOptions };