cspell-io 8.2.1 → 8.2.4

package/dist/esm/VirtualFS.d.ts

@@ -1,5 +1,5 @@
 import type { CSpellIO } from './CSpellIO.js';
-import { type DirEntry, type Disposable, type FileReference, type FileResource, type Stats } from './models/index.js';
+import type { BufferEncoding, DirEntry, Disposable, FileReference, FileResource, Stats, TextFileResource } from './models/index.js';
 type UrlOrReference = URL | FileReference;
 type NextProvider = (url: URL) => VProviderFileSystem | undefined;
 export interface VirtualFS extends Disposable {
@@ -16,6 +16,11 @@ export interface VirtualFS extends Disposable {
      * Clear the cache of file systems.
      */
     reset(): void;
+    /**
+     * Indicates that logging has been enabled.
+     */
+    loggingEnabled: boolean;
+    enableLogging(value?: boolean): void;
 }
 export declare enum FSCapabilityFlags {
     None = 0,
@@ -30,22 +35,54 @@ export declare enum FSCapabilityFlags {
 interface FileSystemProviderInfo {
     name: string;
 }
-interface FileSystemBase {
-    readFile(url: UrlOrReference): Promise<FileResource>;
+export interface VFileSystem {
+    /**
+     * Read a file.
+     * @param url - URL to read
+     * @param encoding - optional encoding
+     * @returns A FileResource, the content will not be decoded. Use `.getText()` to get the decoded text.
+     */
+    readFile(url: UrlOrReference, encoding?: BufferEncoding): Promise<TextFileResource>;
+    /**
+     * Write a file
+     * @param file - the file to write
+     */
     writeFile(file: FileResource): Promise<FileReference>;
     /**
-     * Information about the provider.
-     * It is up to the provider to define what information is available.
+     * Get the stats for a url.
+     * @param url - Url to fetch stats for.
      */
-    providerInfo: FileSystemProviderInfo;
-}
-export interface VFileSystem extends FileSystemBase {
     stat(url: UrlOrReference): Promise<VfsStat>;
+    /**
+     * Read the directory entries for a url.
+     * The url should end with `/` to indicate a directory.
+     * @param url - the url to read the directory entries for.
+     */
     readDirectory(url: URL): Promise<VfsDirEntry[]>;
+    /**
+     * Get the capabilities for a URL.
+     * The capabilities can be more restrictive than the general capabilities of the provider.
+     * @param url - the url to try
+     */
     getCapabilities(url: URL): FSCapabilities;
+    /**
+     * Information about the provider.
+     * It is up to the provider to define what information is available.
+     */
+    providerInfo: FileSystemProviderInfo;
+    /**
+     * Indicates that a provider was found for the url.
+     */
     hasProvider: boolean;
 }
-export interface VProviderFileSystem extends FileSystemBase, Disposable {
+export interface VProviderFileSystem extends Disposable {
+    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;
     stat(url: UrlOrReference): Stats | Promise<Stats>;
     readDirectory(url: URL): Promise<DirEntry[]>;
     /**
@@ -97,11 +134,13 @@ export interface VfsStat extends Stats {
     isDirectory(): boolean;
     isFile(): boolean;
     isUnknown(): boolean;
+    isSymbolicLink(): boolean;
 }
 export interface VfsDirEntry extends DirEntry {
     isDirectory(): boolean;
     isFile(): boolean;
     isUnknown(): boolean;
+    isSymbolicLink(): boolean;
 }
 export {};
 //# sourceMappingURL=VirtualFS.d.ts.map

package/dist/esm/VirtualFS.js

@@ -1,6 +1,7 @@
-import { urlOrReferenceToUrl } from './common/index.js';
+import { createTextFileResource, urlOrReferenceToUrl } from './common/index.js';
 import { getDefaultCSpellIO } from './CSpellIONode.js';
-import { FileType, } from './models/index.js';
+import { FileType } from './models/index.js';
+const debug = false;
 export var FSCapabilityFlags;
 (function (FSCapabilityFlags) {
     FSCapabilityFlags[FSCapabilityFlags["None"] = 0] = "None";
@@ -17,9 +18,22 @@ class CVirtualFS {
     cachedFs = new Map();
     revCacheFs = new Map();
     fs;
+    loggingEnabled = debug;
     constructor() {
         this.fs = fsPassThrough((url) => this._getFS(url));
     }
+    enableLogging(value) {
+        this.loggingEnabled = value ?? true;
+    }
+    log = console.log;
+    logEvent = (event) => {
+        if (this.loggingEnabled) {
+            const id = event.traceID.toFixed(13).replace(/\d{4}(?=\d)/g, '$&.');
+            const msg = event.message ? `\n\t\t${event.message}` : '';
+            const method = rPad(`${event.method}-${event.event}`, 16);
+            this.log(`${method} ID:${id} ts:${event.ts.toFixed(13)} ${chopUrl(event.url)}${msg}`);
+        }
+    };
     registerFileSystemProvider(...providers) {
         providers.forEach((provider) => this.providers.add(provider));
         this.reset();
@@ -67,7 +81,7 @@ class CVirtualFS {
         for (const provider of this.providers) {
             next = fnNext(provider, next);
         }
-        const fs = new WrappedProviderFs(next(url));
+        const fs = new WrappedProviderFs(next(url), this.logEvent);
         this.cachedFs.set(key, fs);
         return fs;
     }
@@ -211,57 +225,89 @@ export function fsCapabilities(flags) {
 }
 class WrappedProviderFs {
     fs;
+    eventLogger;
     hasProvider;
     capabilities;
     providerInfo;
     _capabilities;
-    constructor(fs) {
+    constructor(fs, eventLogger) {
         this.fs = fs;
+        this.eventLogger = eventLogger;
         this.hasProvider = !!fs;
         this.capabilities = fs?.capabilities || FSCapabilityFlags.None;
         this._capabilities = fsCapabilities(this.capabilities);
         this.providerInfo = fs?.providerInfo || { name: 'unknown' };
     }
+    logEvent(method, event, traceID, url, message) {
+        this.eventLogger({ method, event, url, traceID, ts: performance.now(), message });
+    }
     getCapabilities(url) {
         if (this.fs?.getCapabilities)
             return this.fs.getCapabilities(url);
         return this._capabilities;
     }
-    async stat(url) {
+    async stat(urlRef) {
+        const traceID = performance.now();
+        const url = urlOrReferenceToUrl(urlRef);
+        this.logEvent('stat', 'start', traceID, url);
         try {
-            checkCapabilityOrThrow(this.fs, this.capabilities, FSCapabilityFlags.Stat, 'stat', urlOrReferenceToUrl(url));
-            return new CVfsStat(await this.fs.stat(url));
+            checkCapabilityOrThrow(this.fs, this.capabilities, FSCapabilityFlags.Stat, 'stat', url);
+            return new CVfsStat(await this.fs.stat(urlRef));
         }
         catch (e) {
+            this.logEvent('stat', 'error', traceID, url, e instanceof Error ? e.message : '');
             throw wrapError(e);
         }
+        finally {
+            this.logEvent('stat', 'end', traceID, url);
+        }
     }
-    async readFile(url) {
+    async readFile(urlRef, encoding) {
+        const traceID = performance.now();
+        const url = urlOrReferenceToUrl(urlRef);
+        this.logEvent('readFile', 'start', traceID, url);
         try {
-            checkCapabilityOrThrow(this.fs, this.capabilities, FSCapabilityFlags.Read, 'readFile', urlOrReferenceToUrl(url));
-            return await this.fs.readFile(url);
+            checkCapabilityOrThrow(this.fs, this.capabilities, FSCapabilityFlags.Read, 'readFile', url);
+            return createTextFileResource(await this.fs.readFile(urlRef), encoding);
         }
         catch (e) {
+            this.logEvent('readFile', 'error', traceID, url, e instanceof Error ? e.message : '');
             throw wrapError(e);
         }
+        finally {
+            this.logEvent('readFile', 'end', traceID, url);
+        }
     }
     async readDirectory(url) {
+        const traceID = performance.now();
+        this.logEvent('readDir', 'start', traceID, url);
         try {
             checkCapabilityOrThrow(this.fs, this.capabilities, FSCapabilityFlags.ReadDir, 'readDirectory', url);
             return (await this.fs.readDirectory(url)).map((e) => new CVfsDirEntry(e));
         }
         catch (e) {
+            this.logEvent('readDir', 'error', traceID, url, e instanceof Error ? e.message : '');
             throw wrapError(e);
         }
+        finally {
+            this.logEvent('readDir', 'end', traceID, url);
+        }
     }
     async writeFile(file) {
+        const traceID = performance.now();
+        const url = file.url;
+        this.logEvent('writeFile', 'start', traceID, url);
         try {
             checkCapabilityOrThrow(this.fs, this.capabilities, FSCapabilityFlags.Write, 'writeFile', file.url);
             return await this.fs.writeFile(file);
         }
         catch (e) {
+            this.logEvent('writeFile', 'error', traceID, url, e instanceof Error ? e.message : '');
             throw wrapError(e);
         }
+        finally {
+            this.logEvent('writeFile', 'end', traceID, url);
+        }
     }
     static disposeOf(fs) {
         fs instanceof WrappedProviderFs && fs.fs?.dispose();
@@ -286,6 +332,9 @@ class CFileType {
     isUnknown() {
         return !this.fileType;
     }
+    isSymbolicLink() {
+        return !!(this.fileType & FileType.SymbolicLink);
+    }
 }
 class CVfsStat extends CFileType {
     stat;
@@ -322,5 +371,27 @@ class CVfsDirEntry extends CFileType {
         this._url = new URL(this.entry.name, this.entry.dir);
         return this._url;
     }
+    toJSON() {
+        return {
+            name: this.name,
+            dir: this.dir,
+            fileType: this.fileType,
+        };
+    }
+}
+function chopUrl(url) {
+    if (!url)
+        return '';
+    const href = url.href;
+    const parts = href.split('/');
+    const n = parts.indexOf('node_modules');
+    if (n > 0) {
+        const tail = parts.slice(Math.max(parts.length - 3, n + 1));
+        return parts.slice(0, n + 1).join('/') + '/…/' + tail.join('/');
+    }
+    return href;
+}
+function rPad(str, len, ch = ' ') {
+    return str + ch.repeat(Math.max(0, len - str.length));
 }
 //# sourceMappingURL=VirtualFS.js.map

package/dist/esm/common/CFileResource.d.ts

@@ -9,7 +9,7 @@ export declare class CFileResource implements TextFileResource {
     private _gz?;
     constructor(url: URL, content: string | ArrayBufferView, encoding: BufferEncoding | undefined, baseFilename: string | undefined, gz: boolean | undefined);
     get gz(): boolean;
-    getText(): string;
+    getText(encoding?: BufferEncoding): string;
     toJson(): {
         url: string;
         content: string;
@@ -23,6 +23,6 @@ export declare class CFileResource implements TextFileResource {
     static from(fileReference: FileReference | URL, content: string | ArrayBufferView): CFileResource;
     static from(url: URL, content: string | ArrayBufferView, encoding?: BufferEncoding | undefined, baseFilename?: string | undefined, gz?: boolean): CFileResource;
 }
-export declare function fromFileResource(fileResource: FileResource): TextFileResource;
+export declare function fromFileResource(fileResource: FileResource, encoding?: BufferEncoding): TextFileResource;
 export declare function renameFileResource(fileResource: FileResource, url: URL): FileResource;
 //# sourceMappingURL=CFileResource.d.ts.map

package/dist/esm/common/CFileResource.js

@@ -23,10 +23,10 @@ export class CFileResource {
             return false;
         return isGZipped(this.content);
     }
-    getText() {
+    getText(encoding) {
         if (this._text !== undefined)
             return this._text;
-        const text = typeof this.content === 'string' ? this.content : decode(this.content, this.encoding);
+        const text = typeof this.content === 'string' ? this.content : decode(this.content, encoding ?? this.encoding);
         this._text = text;
         return text;
     }
@@ -63,10 +63,10 @@ export class CFileResource {
         return new CFileResource(fileResource.url, fileResource.content, fileResource.encoding, fileResource.baseFilename, fileResource.gz);
     }
 }
-export function fromFileResource(fileResource) {
-    return CFileResource.from(fileResource);
+export function fromFileResource(fileResource, encoding) {
+    return CFileResource.from(encoding ? { ...fileResource, encoding } : fileResource);
 }
 export function renameFileResource(fileResource, url) {
-    return CFileResource.from(url, fileResource.content, fileResource.encoding, fileResource.baseFilename, fileResource.gz);
+    return CFileResource.from({ ...fileResource, url });
 }
 //# sourceMappingURL=CFileResource.js.map

package/dist/esm/common/index.d.ts

@@ -1,4 +1,5 @@
 export { CFileReference, renameFileReference } from './CFileReference.js';
 export { CFileResource, fromFileResource as createTextFileResource, renameFileResource } from './CFileResource.js';
+export { compareStats } from './stat.js';
 export { urlOrReferenceToUrl } from './urlOrReferenceToUrl.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/common/index.js

@@ -1,4 +1,5 @@
 export { CFileReference, renameFileReference } from './CFileReference.js';
 export { CFileResource, fromFileResource as createTextFileResource, renameFileResource } from './CFileResource.js';
+export { compareStats } from './stat.js';
 export { urlOrReferenceToUrl } from './urlOrReferenceToUrl.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/handlers/node/file.js

@@ -208,6 +208,7 @@ function direntToDirEntry(dir, dirent) {
     };
 }
 function toFileType(statLike) {
-    return statLike.isFile() ? FileType.File : statLike.isDirectory() ? FileType.Directory : FileType.Unknown;
+    const t = statLike.isFile() ? FileType.File : statLike.isDirectory() ? FileType.Directory : FileType.Unknown;
+    return statLike.isSymbolicLink() ? t | FileType.SymbolicLink : t;
 }
 //# sourceMappingURL=file.js.map

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { toArray as asyncIterableToArray } from './async/asyncIterable.js';
 export * from './common/index.js';
-export { createTextFileResource } from './common/index.js';
+export { compareStats, createTextFileResource } from './common/index.js';
 export type { CSpellIO } from './CSpellIO.js';
 export { CSpellIONode, getDefaultCSpellIO } from './CSpellIONode.js';
 export { getStat, getStatSync, readFileText, readFileTextSync, writeToFile, writeToFileIterable, writeToFileIterableP, } from './file/index.js';

package/dist/esm/index.js

@@ -1,6 +1,6 @@
 export { toArray as asyncIterableToArray } from './async/asyncIterable.js';
 export * from './common/index.js';
-export { createTextFileResource } from './common/index.js';
+export { compareStats, createTextFileResource } from './common/index.js';
 export { CSpellIONode, getDefaultCSpellIO } from './CSpellIONode.js';
 export { getStat, getStatSync, readFileText, readFileTextSync, writeToFile, writeToFileIterable, writeToFileIterableP, } from './file/index.js';
 export { FileType as VFileType } from './models/Stats.js';

package/dist/esm/models/FileResource.d.ts

@@ -27,7 +27,13 @@ export interface FileResource extends FileReference {
     readonly content: string | ArrayBufferView;
 }
 export interface TextFileResource extends FileResource {
-    getText(): string;
+    /**
+     * Extract the text of the file.
+     * @param encoding - optional encoding to use when decoding the content.
+     *   by default it uses the encoding of the file if one was specified, otherwise it uses `utf8`.
+     *   If the content is a string, then the encoding is ignored.
+     */
+    getText(encoding?: BufferEncoding): string;
 }
 export type UrlOrFilename = string | URL;
 export type UrlOrReference = UrlOrFilename | FileReference;

package/dist/esm/models/Stats.d.ts

@@ -31,7 +31,11 @@ export declare enum FileType {
     /**
      * A directory.
      */
-    Directory = 2
+    Directory = 2,
+    /**
+     * A symbolic link.
+     */
+    SymbolicLink = 64
 }
 export interface DirEntry {
     name: string;

package/dist/esm/models/Stats.js

@@ -12,5 +12,9 @@ export var FileType;
      * A directory.
      */
     FileType[FileType["Directory"] = 2] = "Directory";
+    /**
+     * A symbolic link.
+     */
+    FileType[FileType["SymbolicLink"] = 64] = "SymbolicLink";
 })(FileType || (FileType = {}));
 //# sourceMappingURL=Stats.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cspell-io",
-  "version": "8.2.1",
+  "version": "8.2.4",
   "description": "A library of useful I/O functions used across various cspell tools.",
   "type": "module",
   "sideEffects": false,
@@ -51,7 +51,7 @@
     "typescript": "^5.3.3"
   },
   "dependencies": {
-    "@cspell/cspell-service-bus": "8.2.1"
+    "@cspell/cspell-service-bus": "8.2.4"
   },
-  "gitHead": "b0c889ee4068aa8a2447106c5c7f449debc85bdd"
+  "gitHead": "d3c5ff685b3aa2bf984f557d81380f2c994547e0"
 }