cspell-io 8.1.2 → 8.2.0

package/dist/esm/CSpellIO.d.ts

@@ -1,41 +1,48 @@
 import type { BufferEncoding } from './models/BufferEncoding.js';
-import type { FileReference, FileResource, UrlOrFilename, UrlOrReference } from './models/FileResource.js';
-import type { Stats } from './models/index.js';
+import type { FileReference, TextFileResource, UrlOrFilename, UrlOrReference } from './models/FileResource.js';
+import type { DirEntry, Stats } from './models/index.js';
 export interface CSpellIO {
     /**
      * Read a file
-     * @param uriOrFilename - uri of the file to read
+     * @param urlOrFilename - uri of the file to read
      * @param encoding - optional encoding.
      * @returns A TextFileResource.
      */
-    readFile(uriOrFilename: UrlOrReference, encoding?: BufferEncoding): Promise<FileResource>;
+    readFile(urlOrFilename: UrlOrReference, encoding?: BufferEncoding): Promise<TextFileResource>;
     /**
      * Read a file in Sync mode.
      * Note: `http` requests will fail.
-     * @param uriOrFilename - uri of the file to read
+     * @param urlOrFilename - uri of the file to read
      * @param encoding - optional encoding.
      * @returns A TextFileResource.
+     * @deprecated Use `readFile` instead.
      */
-    readFileSync(uriOrFilename: UrlOrReference, encoding?: BufferEncoding): FileResource;
+    readFileSync(urlOrFilename: UrlOrReference, encoding?: BufferEncoding): TextFileResource;
     /**
      * Write content to a file using utf-8 encoding.
      * It will fail to write to non-file uris.
-     * @param uriOrFilename - uri
+     * @param urlOrFilename - uri
      * @param content - string to write.
      */
-    writeFile(uriOrFilename: UrlOrReference, content: string | ArrayBufferView): Promise<FileReference>;
+    writeFile(urlOrFilename: UrlOrReference, content: string | ArrayBufferView): Promise<FileReference>;
+    /**
+     * Read a directory.
+     * @param urlOrFilename - uri
+     */
+    readDirectory(urlOrFilename: string | URL): Promise<DirEntry[]>;
     /**
      * Get Stats on a uri.
-     * @param uriOrFilename - uri to fetch stats on
+     * @param urlOrFilename - uri to fetch stats on
      * @returns Stats if successful.
      */
-    getStat(uriOrFilename: UrlOrReference): Promise<Stats>;
+    getStat(urlOrFilename: UrlOrReference): Promise<Stats>;
     /**
      * Get Stats on a uri.
-     * @param uriOrFilename - uri to fetch stats on
+     * @param urlOrFilename - uri to fetch stats on
      * @returns Stats if successful, otherwise it throws an error.
+     * @deprecated Use `getStat` instead.
      */
-    getStatSync(uriOrFilename: UrlOrReference): Stats;
+    getStatSync(urlOrFilename: UrlOrReference): Stats;
     /**
      * Compare two Stats.
      * @param left - left stat

package/dist/esm/CSpellIONode.d.ts

@@ -1,13 +1,12 @@
 import { ServiceBus } from '@cspell/cspell-service-bus';
 import type { CSpellIO } from './CSpellIO.js';
-import type { BufferEncoding } from './models/BufferEncoding.js';
-import type { FileReference, FileResource, UrlOrReference } from './models/FileResource.js';
-import type { Stats } from './models/Stats.js';
+import type { BufferEncoding, DirEntry, FileReference, Stats, TextFileResource, UrlOrReference } from './models/index.js';
 export declare class CSpellIONode implements CSpellIO {
     readonly serviceBus: ServiceBus;
     constructor(serviceBus?: ServiceBus);
-    readFile(urlOrFilename: UrlOrReference, encoding?: BufferEncoding): Promise<FileResource>;
-    readFileSync(urlOrFilename: UrlOrReference, encoding?: BufferEncoding): FileResource;
+    readFile(urlOrFilename: UrlOrReference, encoding?: BufferEncoding): Promise<TextFileResource>;
+    readDirectory(urlOrFilename: string | URL): Promise<DirEntry[]>;
+    readFileSync(urlOrFilename: UrlOrReference, encoding?: BufferEncoding): TextFileResource;
     writeFile(urlOrFilename: UrlOrReference, content: string | ArrayBufferView): Promise<FileReference>;
     getStat(urlOrFilename: UrlOrReference): Promise<Stats>;
     getStatSync(urlOrFilename: UrlOrReference): Stats;

package/dist/esm/CSpellIONode.js

@@ -6,6 +6,7 @@ import { ErrorNotImplemented } from './errors/errors.js';
 import { registerHandlers } from './handlers/node/file.js';
 import { toFileURL, toURL, urlBasename, urlDirname } from './node/file/url.js';
 import { RequestFsReadFile, RequestFsReadFileSync, RequestFsStat, RequestFsStatSync, RequestFsWriteFile, } from './requests/index.js';
+import { RequestFsReadDirectory } from './requests/RequestFsReadDirectory.js';
 let defaultCSpellIONode = undefined;
 export class CSpellIONode {
     serviceBus;
@@ -21,6 +22,14 @@ export class CSpellIONode {
         }
         return res.value;
     }
+    readDirectory(urlOrFilename) {
+        const ref = toFileReference(urlOrFilename);
+        const res = this.serviceBus.dispatch(RequestFsReadDirectory.create(ref));
+        if (!isServiceResponseSuccess(res)) {
+            throw genError(res.error, 'readDirectory');
+        }
+        return res.value;
+    }
     readFileSync(urlOrFilename, encoding) {
         const ref = toFileReference(urlOrFilename, encoding);
         const res = this.serviceBus.dispatch(RequestFsReadFileSync.create(ref));

package/dist/esm/CSpellIOWeb.d.ts

@@ -1,9 +1,10 @@
 import type { CSpellIO } from './CSpellIO.js';
-import type { FileReference, FileResource, UrlOrFilename, UrlOrReference } from './models/FileResource.js';
-import type { Stats } from './models/Stats.js';
+import type { FileReference, TextFileResource, UrlOrFilename, UrlOrReference } from './models/FileResource.js';
+import type { DirEntry, Stats } from './models/index.js';
 export declare class CSpellIOWeb implements CSpellIO {
-    readFile(_uriOrFilename: string | URL): Promise<FileResource>;
-    readFileSync(_uriOrFilename: string | URL): FileResource;
+    readFile(_uriOrFilename: string | URL): Promise<TextFileResource>;
+    readFileSync(_uriOrFilename: string | URL): TextFileResource;
+    readDirectory(_urlOrFilename: string | URL): Promise<DirEntry[]>;
     writeFile(_uriOrFilename: UrlOrReference, _content: string | ArrayBufferView): Promise<FileReference>;
     getStat(_uriOrFilename: string | URL): Promise<Stats>;
     getStatSync(_uriOrFilename: string | URL): Stats;

package/dist/esm/CSpellIOWeb.js

@@ -7,6 +7,9 @@ export class CSpellIOWeb {
     readFileSync(_uriOrFilename) {
         throw new ErrorNotImplemented('readFileSync');
     }
+    readDirectory(_urlOrFilename) {
+        throw new ErrorNotImplemented('readDirectory');
+    }
     writeFile(_uriOrFilename, _content) {
         throw new ErrorNotImplemented('writeFile');
     }

package/dist/esm/VirtualFS/redirectProvider.d.ts

@@ -0,0 +1,30 @@
+import type { FSCapabilityFlags, VFileSystemProvider } from '../VirtualFS.js';
+export interface RedirectOptions {
+    /**
+     * Option ts to mask the capabilities of the provider.
+     * @default: -1
+     */
+    capabilitiesMask?: number;
+    capabilities?: FSCapabilityFlags;
+}
+/**
+ * Create a provider that will redirect requests from the publicRoot to the privateRoot.
+ * This is useful for creating a virtual file system that is a subset of another file system.
+ *
+ * Example:
+ * ```ts
+ * const vfs = createVirtualFS();
+ * const provider = createRedirectProvider('test', new URL('file:///public/'), new URL('file:///private/'))
+ * vfs.registerFileSystemProvider(provider);
+ * // Read the content of `file:///private/file.txt`
+ * const file = vfs.fs.readFile(new URL('file:///public/file.txt');
+ * ```
+ *
+ * @param name - name of the provider
+ * @param publicRoot - the root of the public file system.
+ * @param privateRoot - the root of the private file system.
+ * @param options - options for the provider.
+ * @returns FileSystemProvider
+ */
+export declare function createRedirectProvider(name: string, publicRoot: URL, privateRoot: URL, options?: RedirectOptions): VFileSystemProvider;
+//# sourceMappingURL=redirectProvider.d.ts.map

package/dist/esm/VirtualFS/redirectProvider.js

@@ -0,0 +1,147 @@
+import assert from 'assert';
+import { renameFileReference, renameFileResource, urlOrReferenceToUrl } from '../common/index.js';
+import { fsCapabilities, VFSErrorUnsupportedRequest } from '../VirtualFS.js';
+class RedirectProvider {
+    name;
+    publicRoot;
+    privateRoot;
+    options;
+    constructor(name, publicRoot, privateRoot, options = { capabilitiesMask: -1 }) {
+        this.name = name;
+        this.publicRoot = publicRoot;
+        this.privateRoot = privateRoot;
+        this.options = options;
+    }
+    getFileSystem(url, next) {
+        if (url.protocol !== this.publicRoot.protocol || url.host !== this.publicRoot.host) {
+            return undefined;
+        }
+        const privateFs = next(this.privateRoot);
+        if (!privateFs) {
+            return undefined;
+        }
+        const shadowFS = next(url);
+        return remapFS(this.name, privateFs, shadowFS, this.publicRoot, this.privateRoot, this.options);
+    }
+}
+/**
+ * Create a provider that will redirect requests from the publicRoot to the privateRoot.
+ * This is useful for creating a virtual file system that is a subset of another file system.
+ *
+ * Example:
+ * ```ts
+ * const vfs = createVirtualFS();
+ * const provider = createRedirectProvider('test', new URL('file:///public/'), new URL('file:///private/'))
+ * vfs.registerFileSystemProvider(provider);
+ * // Read the content of `file:///private/file.txt`
+ * const file = vfs.fs.readFile(new URL('file:///public/file.txt');
+ * ```
+ *
+ * @param name - name of the provider
+ * @param publicRoot - the root of the public file system.
+ * @param privateRoot - the root of the private file system.
+ * @param options - options for the provider.
+ * @returns FileSystemProvider
+ */
+export function createRedirectProvider(name, publicRoot, privateRoot, options) {
+    assert(publicRoot.pathname.endsWith('/'), 'publicRoot must end with a slash');
+    assert(privateRoot.pathname.endsWith('/'), 'privateRoot must end with a slash');
+    return new RedirectProvider(name, publicRoot, privateRoot, options);
+}
+/**
+ * Create a Remapped file system that will redirect requests from the publicRoot to the privateRoot.
+ * Requests that do not match the publicRoot will be passed to the shadowFs.
+ * @param name - name of the provider
+ * @param fs - the private file system
+ * @param shadowFs - the file system that is obscured by the redirect.
+ * @param publicRoot - the root of the public file system.
+ * @param privateRoot - the root of the private file system.
+ * @returns ProviderFileSystem
+ */
+function remapFS(name, fs, shadowFs, publicRoot, privateRoot, options) {
+    const { capabilitiesMask = -1, capabilities } = options;
+    function mapToPrivate(url) {
+        const relativePath = url.pathname.slice(publicRoot.pathname.length);
+        return new URL(relativePath, privateRoot);
+    }
+    function mapToPublic(url) {
+        const relativePath = url.pathname.slice(privateRoot.pathname.length);
+        return new URL(relativePath, publicRoot);
+    }
+    const mapFileReferenceToPrivate = (ref) => {
+        return renameFileReference(ref, mapToPrivate(ref.url));
+    };
+    const mapFileReferenceToPublic = (ref) => {
+        return renameFileReference(ref, mapToPublic(ref.url));
+    };
+    const mapUrlOrReferenceToPrivate = (urlOrRef) => {
+        return urlOrRef instanceof URL ? mapToPrivate(urlOrRef) : mapFileReferenceToPrivate(urlOrRef);
+    };
+    const mapFileResourceToPublic = (res) => {
+        return renameFileResource(res, mapToPublic(res.url));
+    };
+    const mapFileResourceToPrivate = (res) => {
+        return renameFileResource(res, mapToPrivate(res.url));
+    };
+    const mapDirEntryToPublic = (de) => {
+        const dir = mapToPublic(de.dir);
+        return { ...de, dir };
+    };
+    const fs2 = {
+        stat: async (url) => {
+            const url2 = mapUrlOrReferenceToPrivate(url);
+            const stat = await fs.stat(url2);
+            return stat;
+        },
+        readFile: async (url) => {
+            const url2 = mapUrlOrReferenceToPrivate(url);
+            const file = await fs.readFile(url2);
+            return mapFileResourceToPublic(file);
+        },
+        readDirectory: async (url) => {
+            const url2 = mapToPrivate(url);
+            const dir = await fs.readDirectory(url2);
+            return dir.map(mapDirEntryToPublic);
+        },
+        writeFile: async (file) => {
+            const fileRef2 = mapFileResourceToPrivate(file);
+            const fileRef3 = await fs.writeFile(fileRef2);
+            return mapFileReferenceToPublic(fileRef3);
+        },
+        providerInfo: { ...fs.providerInfo, name },
+        capabilities: capabilities ?? fs.capabilities & capabilitiesMask,
+        dispose: () => fs.dispose(),
+    };
+    return fsPassThrough(fs2, shadowFs, publicRoot);
+}
+function fsPassThrough(fs, shadowFs, root) {
+    function gfs(ur, name) {
+        const url = urlOrReferenceToUrl(ur);
+        const f = url.href.startsWith(root.href) ? fs : shadowFs;
+        if (!f)
+            throw new VFSErrorUnsupportedRequest(name, url, ur instanceof URL ? undefined : { url: ur.url.toString(), encoding: ur.encoding });
+        return f;
+    }
+    const passThroughFs = {
+        get providerInfo() {
+            return fs.providerInfo;
+        },
+        get capabilities() {
+            return fs.capabilities;
+        },
+        stat: async (url) => gfs(url, 'stat').stat(url),
+        readFile: async (url) => gfs(url, 'readFile').readFile(url),
+        writeFile: async (file) => gfs(file, 'writeFile').writeFile(file),
+        readDirectory: async (url) => gfs(url, 'readDirectory').readDirectory(url),
+        getCapabilities(url) {
+            const f = gfs(url, 'getCapabilities');
+            return f.getCapabilities ? f.getCapabilities(url) : fsCapabilities(f.capabilities);
+        },
+        dispose: () => {
+            fs.dispose();
+            shadowFs?.dispose();
+        },
+    };
+    return passThroughFs;
+}
+//# sourceMappingURL=redirectProvider.js.map

package/dist/esm/VirtualFS.d.ts

@@ -0,0 +1,107 @@
+import type { CSpellIO } from './CSpellIO.js';
+import { type DirEntry, type Disposable, type FileReference, type FileResource, type Stats } from './models/index.js';
+type UrlOrReference = URL | FileReference;
+type NextProvider = (url: URL) => VProviderFileSystem | undefined;
+export interface VirtualFS extends Disposable {
+    registerFileSystemProvider(provider: VFileSystemProvider, ...providers: VFileSystemProvider[]): Disposable;
+    /**
+     * Get the fs for a given url.
+     */
+    getFS(url: URL): VFileSystem;
+    /**
+     * The file system. All requests will first use getFileSystem to get the file system before making the request.
+     */
+    readonly fs: Required<VFileSystem>;
+    /**
+     * Clear the cache of file systems.
+     */
+    reset(): void;
+}
+export declare enum FSCapabilityFlags {
+    None = 0,
+    Stat = 1,
+    Read = 2,
+    Write = 4,
+    ReadWrite = 6,
+    ReadDir = 8,
+    WriteDir = 16,
+    ReadWriteDir = 24
+}
+interface FileSystemProviderInfo {
+    name: string;
+}
+interface FileSystemBase {
+    readFile(url: UrlOrReference): Promise<FileResource>;
+    writeFile(file: FileResource): Promise<FileReference>;
+    /**
+     * Information about the provider.
+     * It is up to the provider to define what information is available.
+     */
+    providerInfo: FileSystemProviderInfo;
+}
+export interface VFileSystem extends FileSystemBase {
+    stat(url: UrlOrReference): Promise<VfsStat>;
+    readDirectory(url: URL): Promise<VfsDirEntry[]>;
+    getCapabilities(url: URL): FSCapabilities;
+    hasProvider: boolean;
+}
+export interface VProviderFileSystem extends FileSystemBase, Disposable {
+    stat(url: UrlOrReference): Stats | Promise<Stats>;
+    readDirectory(url: URL): Promise<DirEntry[]>;
+    /**
+     * These are the general capabilities for the provider's file system.
+     * It is possible for a provider to support more capabilities for a given url by providing a getCapabilities function.
+     */
+    capabilities: FSCapabilityFlags;
+    /**
+     * Get the capabilities for a URL. Make it possible for a provider to support more capabilities for a given url.
+     * These capabilities should be more restrictive than the general capabilities.
+     * @param url - the url to try
+     * @returns the capabilities for the url.
+     */
+    getCapabilities?: (url: URL) => FSCapabilities;
+}
+export interface VFileSystemProvider extends Partial<Disposable> {
+    /** Name of the Provider */
+    name: string;
+    /**
+     * Get the file system for a given url. The provider is cached based upon the protocol and hostname.
+     * @param url - the url to get the file system for.
+     * @param next - call this function to get the next provider to try. This is useful for chaining providers that operate on the same protocol.
+     */
+    getFileSystem(url: URL, next: NextProvider): VProviderFileSystem | undefined;
+}
+export declare function createVirtualFS(cspellIO?: CSpellIO): VirtualFS;
+export declare function getDefaultVirtualFs(): VirtualFS;
+export declare class VFSError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare class VFSErrorUnsupportedRequest extends VFSError {
+    readonly request: string;
+    readonly parameters?: unknown;
+    readonly url?: string | undefined;
+    constructor(request: string, url?: URL | string, parameters?: unknown);
+}
+export interface FSCapabilities {
+    readonly flags: FSCapabilityFlags;
+    readonly readFile: boolean;
+    readonly writeFile: boolean;
+    readonly readDirectory: boolean;
+    readonly writeDirectory: boolean;
+    readonly stat: boolean;
+}
+export declare function fsCapabilities(flags: FSCapabilityFlags): FSCapabilities;
+export interface VfsStat extends Stats {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    isUnknown(): boolean;
+}
+export interface VfsDirEntry extends DirEntry {
+    isDirectory(): boolean;
+    isFile(): boolean;
+    isUnknown(): boolean;
+}
+export {};
+//# sourceMappingURL=VirtualFS.d.ts.map