@visulima/fs 4.0.6 → 4.1.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## @visulima/fs [4.1.0](https://github.com/visulima/visulima/compare/@visulima/fs@4.0.6...@visulima/fs@4.1.0) (2025-11-19)
+
+### Features
+
+* **fs:** Added new `sanitize.ts` utility for string file name sanitization ([78ee034](https://github.com/visulima/visulima/commit/78ee0349fe8b35145cfa6eebe3d72e1907da2990))
+
+### Miscellaneous Chores
+
+* **release:** update dependencies and versions across multiple packages ([39ad777](https://github.com/visulima/visulima/commit/39ad777e15aeb77d1ec4182763ab7473740ccbc4))
+
 ## @visulima/fs [4.0.6](https://github.com/visulima/visulima/compare/@visulima/fs@4.0.5...@visulima/fs@4.0.6) (2025-11-13)
 
 ### Bug Fixes

package/dist/error/already-exists-error.d.ts

@@ -28,7 +28,7 @@
 declare class AlreadyExistsError extends Error {
     /**
      * Creates a new instance.
-     * @param message The error message.
+     * @param message
      */
     constructor(message: string);
     get code(): string;

package/dist/error/directory-error.d.ts

@@ -36,7 +36,7 @@
 declare class DirectoryError extends Error {
     /**
      * Creates a new instance.
-     * @param message The error message.
+     * @param message
      */
     constructor(message: string);
     get code(): string;

package/dist/error/not-empty-error.d.ts

@@ -40,7 +40,7 @@
 declare class NotEmptyError extends Error {
     /**
      * Creates a new instance.
-     * @param message The error message.
+     * @param message
      */
     constructor(message: string);
     get code(): string;

package/dist/error/not-found-error.d.ts

@@ -33,7 +33,7 @@
 declare class NotFoundError extends Error {
     /**
      * Creates a new instance.
-     * @param message The error message.
+     * @param message
      */
     constructor(message: string);
     get code(): string;

package/dist/error/permission-error.d.ts

@@ -34,7 +34,7 @@
 declare class PermissionError extends Error {
     /**
      * Creates a new instance.
-     * @param message The error message.
+     * @param message
      */
     constructor(message: string);
     get code(): string;

package/dist/error.js

@@ -1,7 +1,7 @@
-export { default as AlreadyExistsError } from './packem_shared/AlreadyExistsError-D5BGeeNR.js';
-export { default as DirectoryError } from './packem_shared/DirectoryError-CaUV2Pbk.js';
+export { default as AlreadyExistsError } from './packem_shared/AlreadyExistsError-6Y9hjgMn.js';
+export { default as DirectoryError } from './packem_shared/DirectoryError-BfYPkIYP.js';
 export { default as JSONError } from './packem_shared/JSONError-BkHRnInH.js';
-export { default as NotEmptyError } from './packem_shared/NotEmptyError-mOHWXE0m.js';
-export { default as NotFoundError } from './packem_shared/NotFoundError-D4llRgRs.js';
-export { default as PermissionError } from './packem_shared/PermissionError-1qs0skfo.js';
+export { default as NotEmptyError } from './packem_shared/NotEmptyError-B21RUlVr.js';
+export { default as NotFoundError } from './packem_shared/NotFoundError-BIp61X6k.js';
+export { default as PermissionError } from './packem_shared/PermissionError-CjoiJgip.js';
 export { default as WalkError } from './packem_shared/WalkError-DUdQd6FT.js';

package/dist/find/walk-sync.d.ts

@@ -1,9 +1,17 @@
 import type { WalkEntry, WalkOptions } from "../types.d.ts";
 /**
  * Synchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
- * This is the synchronous version of the {@link walk} function.
+ * This is the synchronous version of the {@linkcode walk} function.
  * @param directory The root directory to start walking from.
  * @param options Optional configuration to control the walking process. See {@link WalkOptions}.
+ * @param options.extensions List of file extensions used to filter entries.
+ * @param options.followSymlinks Indicates whether symlinks should be resolved or not.
+ * @param options.includeDirs Indicates whether directory entries should be included or not.
+ * @param options.includeFiles Indicates whether file entries should be included or not.
+ * @param options.includeSymlinks Indicates whether symlink entries should be included or not.
+ * @param options.match List of regular expression or glob patterns used to filter entries.
+ * @param options.maxDepth Maximum depth to walk. Defaults to infinity.
+ * @param options.skip List of regular expression or glob patterns used to skip entries.
  * @returns An iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
  * @example
  * ```javascript

package/dist/find/walk.d.ts

@@ -3,6 +3,14 @@ import type { WalkEntry, WalkOptions } from "../types.d.ts";
  * Asynchronously walks the file tree rooted at `directory`, yielding each file or directory that matches the criteria specified in `options`.
  * @param directory The root directory to start walking from.
  * @param options Optional configuration to control the walking process. See {@link WalkOptions}.
+ * @param options.extensions List of file extensions used to filter entries.
+ * @param options.followSymlinks Indicates whether symlinks should be resolved or not.
+ * @param options.includeDirs Indicates whether directory entries should be included or not.
+ * @param options.includeFiles Indicates whether file entries should be included or not.
+ * @param options.includeSymlinks Indicates whether symlink entries should be included or not.
+ * @param options.match List of regular expression or glob patterns used to filter entries.
+ * @param options.maxDepth Maximum depth to walk. Defaults to infinity.
+ * @param options.skip List of regular expression or glob patterns used to skip entries.
  * @returns An async iterable iterator yielding {@link WalkEntry} objects for each matching file or directory.
  * @example
  * ```javascript

package/dist/index.d.ts

@@ -26,6 +26,8 @@ export { default as emptyDir } from "./remove/empty-dir.d.ts";
 export { default as emptyDirSync } from "./remove/empty-dir-sync.d.ts";
 export { default as remove } from "./remove/remove.d.ts";
 export { default as removeSync } from "./remove/remove-sync.d.ts";
+export type { SanitizeOptions } from "./sanitize.d.ts";
+export { sanitize } from "./sanitize.d.ts";
 export type { CodeFrameLocation, CodeFrameOptions, ContentType, FindUpName, FindUpNameFnResult, FindUpNameSync, FindUpNameSyncFnResult, FindUpOptions, JsonReplacer, JsonReviver, ReadFileEncoding, ReadFileOptions, ReadJsonOptions, WalkEntry, WalkOptions, WriteFileOptions, WriteJsonOptions, } from "./types.d.ts";
 export { default as writeFile } from "./write/write-file.d.ts";
 export { default as writeFileSync } from "./write/write-file-sync.d.ts";

package/dist/index.js

@@ -5,8 +5,8 @@ export { default as ensureFile } from './packem_shared/ensureFile-BUtXGlGT.js';
 export { default as ensureFileSync } from './packem_shared/ensureFileSync-C8hASR-1.js';
 export { default as ensureLink } from './packem_shared/ensureLink-BPnAG5-P.js';
 export { default as ensureLinkSync } from './packem_shared/ensureLinkSync-B-Z7X0ub.js';
-export { default as ensureSymlink } from './packem_shared/ensureSymlink-BGz6W-Wa.js';
-export { default as ensureSymlinkSync } from './packem_shared/ensureSymlinkSync-C5Gk8QYi.js';
+export { default as ensureSymlink } from './packem_shared/ensureSymlink-U5B6J0BN.js';
+export { default as ensureSymlinkSync } from './packem_shared/ensureSymlinkSync-DHnZj-9F.js';
 export { CRLF, EOL, LF, detect, format } from './eol.js';
 export { default as collect } from './packem_shared/collect-DcBwsYYd.js';
 export { default as collectSync } from './packem_shared/collectSync-Bkjf9Dbm.js';
@@ -17,14 +17,15 @@ export { default as walkSync } from './packem_shared/walkSync-DDBq95s8.js';
 export { default as isAccessible } from './packem_shared/isAccessible-iOp0Bou6.js';
 export { default as isAccessibleSync } from './packem_shared/isAccessibleSync-38BmiIcx.js';
 export { move, moveSync, rename, renameSync } from './packem_shared/move-BD6JbYSu.js';
-export { default as readFile } from './packem_shared/readFile-XVOjAw8r.js';
-export { default as readFileSync } from './packem_shared/readFileSync-B9Zg5PSF.js';
-export { default as readJson } from './packem_shared/readJson-Dra2m6s-.js';
-export { default as readJsonSync } from './packem_shared/readJsonSync-B6Dl1I_6.js';
+export { default as readFile } from './packem_shared/readFile-BcK0rkht.js';
+export { default as readFileSync } from './packem_shared/readFileSync-BDgEnnqT.js';
+export { default as readJson } from './packem_shared/readJson-ac6N9-5G.js';
+export { default as readJsonSync } from './packem_shared/readJsonSync-BTlwqLNV.js';
 export { default as emptyDir } from './packem_shared/emptyDir-CYB5Tict.js';
 export { default as emptyDirSync } from './packem_shared/emptyDirSync-BD8-1Ytl.js';
 export { default as remove } from './packem_shared/remove-_oDY3uKo.js';
 export { default as removeSync } from './packem_shared/removeSync-DETRj7Qn.js';
+export { sanitize } from './packem_shared/sanitize-lOzE6k2A.js';
 export { default as writeFile } from './packem_shared/writeFile-NT1fLEEe.js';
 export { default as writeFileSync } from './packem_shared/writeFileSync-Bj5UDSf0.js';
 export { default as writeJson } from './packem_shared/writeJson-DQLdAi0d.js';

package/dist/move/index.d.ts

@@ -28,7 +28,6 @@ export declare const move: (sourcePath: string, destinationPath: string, options
  * @param sourcePath The file you want to move.
  * @param destinationPath Where you want the file moved.
  * @param options Configuration options.
- * @returns Nothing is returned.
  * @example
  * ```
  * import { moveSync } from '@visulima/fs';
@@ -58,7 +57,6 @@ export declare const rename: (source: string, destination: string, options?: Opt
  * @param source The file you want to rename.
  * @param destination The name of the renamed file.
  * @param options Configuration options.
- * @returns A `Promise` that resolves when the file has been renamed.
  * @example
  * ```
  * import { renameSync } from '@visulima/fs';

package/dist/move/types.d.ts

@@ -1,4 +1,3 @@
-type FilePermissions = number;
 export type Options = {
     /**
      * The working directory to find source files.
@@ -12,7 +11,7 @@ export type Options = {
      * It has no effect on Windows.
      * @default 0o777
      */
-    readonly directoryMode?: FilePermissions;
+    readonly directoryMode?: number;
     /**
      * Overwrite existing destination file.
      * @default true
@@ -35,4 +34,3 @@ export type InternalOptions = Options & {
      */
     validateDirectory?: boolean;
 };
-export {};

package/dist/packem_shared/{AlreadyExistsError-D5BGeeNR.js → AlreadyExistsError-6Y9hjgMn.js}

@@ -1,7 +1,7 @@
 class AlreadyExistsError extends Error {
   /**
    * Creates a new instance.
-   * @param message The error message.
+   * @param message
    */
   constructor(message) {
     super(`EEXIST: ${message}`);

package/dist/packem_shared/{DirectoryError-CaUV2Pbk.js → DirectoryError-BfYPkIYP.js}

@@ -1,7 +1,7 @@
 class DirectoryError extends Error {
   /**
    * Creates a new instance.
-   * @param message The error message.
+   * @param message
    */
   constructor(message) {
     super(`EISDIR: Illegal operation on a directory, ${message}`);

package/dist/packem_shared/{NotEmptyError-mOHWXE0m.js → NotEmptyError-B21RUlVr.js}

@@ -1,7 +1,7 @@
 class NotEmptyError extends Error {
   /**
    * Creates a new instance.
-   * @param message The error message.
+   * @param message
    */
   constructor(message) {
     super(`ENOTEMPTY: Directory not empty, ${message}`);

package/dist/packem_shared/{NotFoundError-D4llRgRs.js → NotFoundError-BIp61X6k.js}

@@ -1,7 +1,7 @@
 class NotFoundError extends Error {
   /**
    * Creates a new instance.
-   * @param message The error message.
+   * @param message
    */
   constructor(message) {
     super(`ENOENT: ${message}`);

package/dist/packem_shared/{PermissionError-1qs0skfo.js → PermissionError-CjoiJgip.js}

@@ -1,7 +1,7 @@
 class PermissionError extends Error {
   /**
    * Creates a new instance.
-   * @param message The error message.
+   * @param message
    */
   constructor(message) {
     super(`EPERM: Operation not permitted, ${message}`);

package/dist/packem_shared/{ensureSymlink-BGz6W-Wa.js → ensureSymlink-U5B6J0BN.js}

@@ -30,7 +30,7 @@ import ensureDir from './ensureDir-C_kuQ5Ik.js';
 import { g as getFileInfoType } from './get-file-info-type-FD4-jsyg.js';
 import { i as isStatsIdentical } from './is-stats-identical-D8FxpvQU.js';
 import { r as resolveSymlinkTarget } from './resolve-symlink-target-Kh4GovFf.js';
-import AlreadyExistsError from './AlreadyExistsError-D5BGeeNR.js';
+import AlreadyExistsError from './AlreadyExistsError-6Y9hjgMn.js';
 
 const isWindows = process.platform === "win32" || /^(?:msys|cygwin)$/.test(process.env.OSTYPE);
 const ensureSymlink = async (target, linkName, type) => {

package/dist/packem_shared/{ensureSymlinkSync-C5Gk8QYi.js → ensureSymlinkSync-DHnZj-9F.js}

@@ -30,7 +30,7 @@ import ensureDirSync from './ensureDirSync-CI5g-uBI.js';
 import { g as getFileInfoType } from './get-file-info-type-FD4-jsyg.js';
 import { i as isStatsIdentical } from './is-stats-identical-D8FxpvQU.js';
 import { r as resolveSymlinkTarget } from './resolve-symlink-target-Kh4GovFf.js';
-import AlreadyExistsError from './AlreadyExistsError-D5BGeeNR.js';
+import AlreadyExistsError from './AlreadyExistsError-6Y9hjgMn.js';
 
 const isWindows = process.platform === "win32" || /^(?:msys|cygwin)$/.test(process.env.OSTYPE);
 const ensureSymlinkSync = (target, linkName, type) => {

package/dist/packem_shared/{parseJson-CqUuRguZ.js → parseJson-C8xb-3LR.js}

@@ -169,7 +169,7 @@ const indexToLineColumn = (input, index, options) => {
   };
 };
 
-const getCodePoint = (character) => `\\u{${character.codePointAt(0).toString(16)}}`;
+const getCodePoint = (character) => String.raw`\u{${character.codePointAt(0).toString(16)}}`;
 const generateCodeFrame = (source, location, options) => codeFrame(
   source,
   { start: location },
@@ -194,7 +194,7 @@ const getErrorLocation = (source, message) => {
   return indexToLineColumn(source, index);
 };
 const addCodePointToUnexpectedToken = (message) => message.replace(
-  // TODO[engine:node@>=20]: The token always quoted after Node.js 20
+  // The token is always quoted after Node.js 20, but we handle both cases for compatibility
   // eslint-disable-next-line regexp/no-potentially-useless-backreference
   /(?<=^Unexpected token )(?<quote>')?(.)\k<quote>/,
   (_, _quote, token) => `"${token}"(${getCodePoint(token)})`

package/dist/packem_shared/{readFile-XVOjAw8r.js → readFile-BcK0rkht.js}

@@ -26,7 +26,7 @@ const {
 } = __cjs_getBuiltinModule("node:zlib");
 import { toPath } from '@visulima/path/utils';
 import { R_OK } from './F_OK-BalxCn9n.js';
-import PermissionError from './PermissionError-1qs0skfo.js';
+import PermissionError from './PermissionError-CjoiJgip.js';
 import isAccessible from './isAccessible-iOp0Bou6.js';
 import assertValidFileOrDirectoryPath from './assertValidFileOrDirectoryPath-8HANmVjk.js';
 

package/dist/packem_shared/{readFileSync-B9Zg5PSF.js → readFileSync-BDgEnnqT.js}

@@ -26,7 +26,7 @@ const {
 } = __cjs_getBuiltinModule("node:zlib");
 import { toPath } from '@visulima/path/utils';
 import { R_OK } from './F_OK-BalxCn9n.js';
-import PermissionError from './PermissionError-1qs0skfo.js';
+import PermissionError from './PermissionError-CjoiJgip.js';
 import isAccessibleSync from './isAccessibleSync-38BmiIcx.js';
 import assertValidFileOrDirectoryPath from './assertValidFileOrDirectoryPath-8HANmVjk.js';
 

package/dist/packem_shared/{readJson-Dra2m6s-.js → readJson-ac6N9-5G.js}

@@ -1,6 +1,6 @@
 import { toPath } from '@visulima/path/utils';
-import parseJson from './parseJson-CqUuRguZ.js';
-import readFile from './readFile-XVOjAw8r.js';
+import parseJson from './parseJson-C8xb-3LR.js';
+import readFile from './readFile-BcK0rkht.js';
 
 async function readJson(path, reviver, options) {
   if (typeof reviver === "object") {

package/dist/packem_shared/{readJsonSync-B6Dl1I_6.js → readJsonSync-BTlwqLNV.js}

@@ -1,6 +1,6 @@
 import { toPath } from '@visulima/path/utils';
-import parseJson from './parseJson-CqUuRguZ.js';
-import readFileSync from './readFileSync-B9Zg5PSF.js';
+import parseJson from './parseJson-C8xb-3LR.js';
+import readFileSync from './readFileSync-BDgEnnqT.js';
 
 function readJsonSync(path, reviver, options) {
   if (typeof reviver === "object") {

package/dist/packem_shared/{readYaml-Bu1nsexB.js → readYaml-Cj6HxRoa.js}

@@ -1,5 +1,5 @@
 import { parse } from 'yaml';
-import readFile from './readFile-XVOjAw8r.js';
+import readFile from './readFile-BcK0rkht.js';
 
 async function readYaml(path, reviver, options) {
   const { buffer, compression, encoding = "utf8", flag, ...parseOptions } = options ?? {};

package/dist/packem_shared/{readYamlSync-Di88aMME.js → readYamlSync-D3_iAKVv.js}

@@ -1,5 +1,5 @@
 import { parse } from 'yaml';
-import readFileSync from './readFileSync-B9Zg5PSF.js';
+import readFileSync from './readFileSync-BDgEnnqT.js';
 
 function readYamlSync(path, reviver, options) {
   const { buffer, compression, encoding = "utf8", flag, ...parseOptions } = options ?? {};

package/dist/packem_shared/sanitize-lOzE6k2A.js

@@ -0,0 +1,205 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const {
+  platform
+} = __cjs_getProcess;
+
+const FALLBACK_NAME = "unnamed";
+const MAX_LENGTH = 128;
+const REPLACEMENT_CHARACTERS = {
+  '"': "ˮ",
+  // 0x02EE - MODIFIER LETTER DOUBLE APOSTROPHE
+  "*": "⁎",
+  // 0x204E - LOW ASTERISK
+  "/": "⁄",
+  // 0x2044 - FRACTION SLASH
+  ":": "꞉",
+  // 0xA789 - MODIFIER LETTER COLON
+  "<": "‹",
+  // 0x2039 - SINGLE LEFT-POINTING ANGLE QUOTATION MARK
+  ">": "›",
+  // 0x203A - SINGLE RIGHT-POINTING ANGLE QUOTATION MARK
+  "?": "ʔ",
+  // 0x0294 - LATIN LETTER GLOTTAL STOP
+  "\\": "∖",
+  // 0x2216 - SET MINUS
+  "|": "ǀ"
+  // 0x01C0 - LATIN LETTER DENTAL CLICK
+};
+const CONTROL_CHARS_REGEX = /[\u0000-\u001F\u0080-\u009F]/g;
+const RELATIVE_PATHS_REGEX = /^(?:\.+[/\\]+)+|^\.+$/g;
+const WINDOWS_SPECIAL_NAMES_REGEX = /^(?:con|prn|aux|nul|com\d|lpt\d)$/i;
+const WINDOWS_FORBIDDEN_CHARS_REGEX = /[<>:"/\\|?*]/g;
+const UNIX_FORBIDDEN_CHARS_REGEX = /\//g;
+const TRIM_CHARS = /* @__PURE__ */ new Set(["	", " ", "."]);
+const hasExtension = (name, lastDotIndex) => lastDotIndex > 0 && lastDotIndex < name.length - 1;
+const truncateWithExtension = (name, maxLength) => {
+  const lastDotIndex = name.lastIndexOf(".");
+  if (!hasExtension(name, lastDotIndex)) {
+    return name.slice(0, maxLength);
+  }
+  const baseName = name.slice(0, lastDotIndex);
+  const extension = name.slice(lastDotIndex);
+  const maxBaseLength = maxLength - extension.length;
+  return maxBaseLength > 0 ? `${baseName.slice(0, maxBaseLength)}${extension}` : name.slice(0, maxLength);
+};
+const trimSpacesAndPeriods = (input) => {
+  let start = 0;
+  let end = input.length;
+  while (start < end) {
+    const char = input[start];
+    if (char === void 0 || !TRIM_CHARS.has(char)) {
+      break;
+    }
+    start += 1;
+  }
+  while (end > start) {
+    const char = input[end - 1];
+    if (char === void 0 || !TRIM_CHARS.has(char)) {
+      break;
+    }
+    end -= 1;
+  }
+  return input.slice(start, end);
+};
+const cleanWindowsName = (name) => {
+  const lastDotIndex = name.lastIndexOf(".");
+  if (hasExtension(name, lastDotIndex)) {
+    const baseName = name.slice(0, lastDotIndex);
+    const extension = name.slice(lastDotIndex);
+    let cleanedBaseName = baseName;
+    while (cleanedBaseName.length > 0) {
+      const char = cleanedBaseName[cleanedBaseName.length - 1];
+      if (char === void 0 || !TRIM_CHARS.has(char)) {
+        break;
+      }
+      cleanedBaseName = cleanedBaseName.slice(0, -1);
+    }
+    if (cleanedBaseName.length === 0) {
+      return extension.slice(1);
+    }
+    return `${cleanedBaseName}${extension}`;
+  }
+  let cleaned = name;
+  while (cleaned.length > 0) {
+    const char = cleaned[cleaned.length - 1];
+    if (char === void 0 || !TRIM_CHARS.has(char)) {
+      break;
+    }
+    cleaned = cleaned.slice(0, -1);
+  }
+  return cleaned;
+};
+const isWindowsReservedName = (name) => {
+  const lastDotIndex = name.lastIndexOf(".");
+  if (hasExtension(name, lastDotIndex)) {
+    return false;
+  }
+  if (WINDOWS_SPECIAL_NAMES_REGEX.test(name)) {
+    return true;
+  }
+  let trimmed = name;
+  while (trimmed.length > 0) {
+    const char = trimmed[trimmed.length - 1];
+    if (char === void 0 || !TRIM_CHARS.has(char)) {
+      break;
+    }
+    trimmed = trimmed.slice(0, -1);
+  }
+  if (trimmed.length > 0 && WINDOWS_SPECIAL_NAMES_REGEX.test(trimmed)) {
+    return true;
+  }
+  return false;
+};
+const cleanFat32Name = (name) => {
+  const lastDotIndex = name.lastIndexOf(".");
+  if (hasExtension(name, lastDotIndex)) {
+    const baseName = name.slice(0, lastDotIndex);
+    const extension = name.slice(lastDotIndex);
+    const cleanedBaseName = trimSpacesAndPeriods(baseName);
+    if (cleanedBaseName.length === 0) {
+      return void 0;
+    }
+    return `${cleanedBaseName}${extension}`;
+  }
+  const trimmed = name.trim();
+  if (trimmed.length > 0 && trimmed[0] === "." && trimmed.length <= 5) {
+    const secondDotIndex = trimmed.indexOf(".", 1);
+    if (secondDotIndex === -1) {
+      return void 0;
+    }
+  }
+  const cleaned = trimSpacesAndPeriods(name);
+  if (cleaned.length === 0) {
+    return void 0;
+  }
+  return cleaned;
+};
+const getFileSystemType = (options) => {
+  const filesystem = options?.filesystem ?? "auto";
+  if (filesystem === "auto") {
+    return platform === "win32" ? "win32" : "unix";
+  }
+  if (filesystem === "darwin") {
+    return "unix";
+  }
+  return filesystem;
+};
+const sanitize = (name, options) => {
+  if (typeof name !== "string" || name.length === 0) {
+    return FALLBACK_NAME;
+  }
+  const fileSystemType = getFileSystemType(options);
+  let sanitized = name;
+  sanitized = sanitized.replace(CONTROL_CHARS_REGEX, "");
+  if (sanitized.length === 0) {
+    return FALLBACK_NAME;
+  }
+  sanitized = sanitized.replace(RELATIVE_PATHS_REGEX, "");
+  if (sanitized.length === 0) {
+    return FALLBACK_NAME;
+  }
+  if (fileSystemType === "win32" || fileSystemType === "fat32") {
+    const lastDotIndex = sanitized.lastIndexOf(".");
+    if (!hasExtension(sanitized, lastDotIndex) && WINDOWS_SPECIAL_NAMES_REGEX.test(sanitized)) {
+      return FALLBACK_NAME;
+    }
+  }
+  sanitized = fileSystemType === "win32" || fileSystemType === "fat32" ? sanitized.replaceAll(WINDOWS_FORBIDDEN_CHARS_REGEX, (char) => REPLACEMENT_CHARACTERS[char] ?? "") : sanitized.replaceAll(UNIX_FORBIDDEN_CHARS_REGEX, REPLACEMENT_CHARACTERS["/"]);
+  sanitized = sanitized.trim();
+  if (fileSystemType === "win32" || fileSystemType === "fat32") {
+    if (isWindowsReservedName(sanitized)) {
+      return FALLBACK_NAME;
+    }
+    if (fileSystemType === "win32") {
+      sanitized = cleanWindowsName(sanitized);
+      if (sanitized.length === 0) {
+        return FALLBACK_NAME;
+      }
+    }
+  }
+  if (fileSystemType === "fat32") {
+    const cleaned = cleanFat32Name(sanitized);
+    if (cleaned === void 0) {
+      return FALLBACK_NAME;
+    }
+    sanitized = cleaned;
+  }
+  if (sanitized.length === 0) {
+    return FALLBACK_NAME;
+  }
+  const maxLength = options?.maxLength ?? MAX_LENGTH;
+  if (sanitized.length > maxLength) {
+    sanitized = truncateWithExtension(sanitized, maxLength);
+    if (sanitized.length === 0) {
+      return FALLBACK_NAME;
+    }
+  }
+  return sanitized;
+};
+
+export { sanitize };

package/dist/read/read-yaml-sync.d.ts

@@ -1,4 +1,4 @@
-import type { ReadYamlOptions, YamlReviver } from "../types.d.ts";
-declare function readYamlSync<R = Record<string, unknown>>(path: URL | string, options?: ReadYamlOptions<"brotli" | "gzip" | "none">): R;
-declare function readYamlSync<R = Record<string, unknown>>(path: URL | string, reviver?: YamlReviver, options?: ReadYamlOptions<"brotli" | "gzip" | "none">): R;
+import type { CompressionType, ReadYamlOptions, YamlReviver } from "../types.d.ts";
+declare function readYamlSync<R = Record<string, unknown>>(path: URL | string, options?: ReadYamlOptions<CompressionType>): R;
+declare function readYamlSync<R = Record<string, unknown>>(path: URL | string, reviver?: YamlReviver, options?: ReadYamlOptions<CompressionType>): R;
 export default readYamlSync;

package/dist/read/read-yaml.d.ts

@@ -1,4 +1,4 @@
-import type { ReadYamlOptions, YamlReviver } from "../types.d.ts";
-declare function readYaml<R = Record<string, unknown>>(path: URL | string, options?: ReadYamlOptions<"brotli" | "gzip" | "none">): Promise<R>;
-declare function readYaml<R = Record<string, unknown>>(path: URL | string, reviver?: YamlReviver, options?: ReadYamlOptions<"brotli" | "gzip" | "none">): Promise<R>;
+import type { CompressionType, ReadYamlOptions, YamlReviver } from "../types.d.ts";
+declare function readYaml<R = Record<string, unknown>>(path: URL | string, options?: ReadYamlOptions<CompressionType>): Promise<R>;
+declare function readYaml<R = Record<string, unknown>>(path: URL | string, reviver?: YamlReviver, options?: ReadYamlOptions<CompressionType>): Promise<R>;
 export default readYaml;

package/dist/remove/empty-dir-sync.d.ts

@@ -6,7 +6,6 @@ import type { RetryOptions } from "../types.d.ts";
  * The directory itself is not deleted.
  * @param dir The path to the directory to empty.
  * @param options Optional configuration for the operation. See {@link RetryOptions}.
- * @returns void
  * @example
  * ```javascript
  * import { emptyDirSync } from "@visulima/fs";

package/dist/remove/remove-sync.d.ts

@@ -4,7 +4,6 @@ import type { RetryOptions } from "../types.d.ts";
  * If the path does not exist, it does nothing.
  * @param path The path to the file or directory to remove.
  * @param options Optional configuration for the operation. See {@link RetryOptions}.
- * @returns void
  * @example
  * ```javascript
  * import { removeSync } from "@visulima/fs";

package/dist/sanitize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Supported filesystem types
+ */
+export type FileSystemType = "win32" | "unix" | "darwin" | "fat32" | "auto";
+/**
+ * Options for the sanitize function
+ */
+export interface SanitizeOptions {
+    /**
+     * Target filesystem type for sanitization rules
+     * - "win32": Windows filesystem rules (reserved names, Windows forbidden chars, no trailing periods/spaces)
+     * - "unix": Unix/Linux filesystem rules (only / and null forbidden)
+     * - "darwin": macOS filesystem rules (same as unix)
+     * - "fat32": FAT32 filesystem rules (Windows rules + no leading/trailing spaces/periods in name part)
+     * - "auto": Automatically detect from process.platform
+     * @default "auto"
+     */
+    filesystem?: FileSystemType;
+    /**
+     * Maximum length of the sanitized name
+     * @default 128
+     */
+    maxLength?: number;
+}
+/**
+ * Sanitizes a filename by removing or replacing forbidden characters.
+ * @param name The filename to sanitize.
+ * @param options Optional configuration.
+ * @returns The sanitized filename, or "unnamed" if the result would be empty.
+ */
+export declare const sanitize: (name: string, options?: Partial<SanitizeOptions>) => string;

package/dist/size.d.ts

@@ -1,6 +1,16 @@
 import { Readable } from "node:stream";
 import { URL } from "node:url";
 import type { BrotliOptions, ZlibOptions } from "node:zlib";
+/**
+ * Input type for size calculation functions.
+ * Can be a Buffer, Readable stream, URL object, or string (file path or content).
+ */
+type SizeInput = Buffer | Readable | URL | string;
+/**
+ * Input type for synchronous size calculation functions.
+ * Can be a Buffer, URL object, or string (file path or content).
+ */
+type SizeInputSync = Buffer | URL | string;
 /**
  * Asynchronously calculates the gzipped size of the given input.
  * The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content).
@@ -44,7 +54,7 @@ import type { BrotliOptions, ZlibOptions } from "node:zlib";
  * main().catch(console.error);
  * ```
  */
-export declare const gzipSize: (input: Buffer | Readable | URL | string, options?: ZlibOptions) => Promise<number>;
+export declare const gzipSize: (input: SizeInput, options?: ZlibOptions) => Promise<number>;
 /**
  * Asynchronously calculates the Brotli compressed size of the given input.
  * The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content).
@@ -88,7 +98,7 @@ export declare const gzipSize: (input: Buffer | Readable | URL | string, options
  * main().catch(console.error);
  * ```
  */
-export declare const brotliSize: (input: Buffer | Readable | URL | string, options?: BrotliOptions) => Promise<number>;
+export declare const brotliSize: (input: SizeInput, options?: BrotliOptions) => Promise<number>;
 /**
  * Asynchronously calculates the raw (uncompressed) size of the given input.
  * The input can be a Buffer, a Readable stream, a URL object pointing to a file, or a string (file path or content).
@@ -131,7 +141,7 @@ export declare const brotliSize: (input: Buffer | Readable | URL | string, optio
  * main().catch(console.error);
  * ```
  */
-export declare const rawSize: (input: Buffer | Readable | URL | string) => Promise<number>;
+export declare const rawSize: (input: SizeInput) => Promise<number>;
 /**
  * Synchronously calculates the gzipped size of the given input.
  * The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
@@ -168,7 +178,7 @@ export declare const rawSize: (input: Buffer | Readable | URL | string) => Promi
  * }
  * ```
  */
-export declare const gzipSizeSync: (input: Buffer | URL | string, options?: ZlibOptions) => number;
+export declare const gzipSizeSync: (input: SizeInputSync, options?: ZlibOptions) => number;
 /**
  * Synchronously calculates the Brotli compressed size of the given input.
  * The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
@@ -205,7 +215,7 @@ export declare const gzipSizeSync: (input: Buffer | URL | string, options?: Zlib
  * }
  * ```
  */
-export declare const brotliSizeSync: (input: Buffer | URL | string, options?: BrotliOptions) => number;
+export declare const brotliSizeSync: (input: SizeInputSync, options?: BrotliOptions) => number;
 /**
  * Synchronously calculates the raw (uncompressed) size of the given input.
  * The input can be a Buffer, a URL object pointing to a file, or a string (file path or content).
@@ -242,4 +252,5 @@ export declare const brotliSizeSync: (input: Buffer | URL | string, options?: Br
  * }
  * ```
  */
-export declare const rawSizeSync: (input: Buffer | URL | string) => number;
+export declare const rawSizeSync: (input: SizeInputSync) => number;
+export {};

package/dist/types.d.ts

@@ -58,6 +58,10 @@ export interface WalkEntry extends Pick<Dirent, "isDirectory" | "isFile" | "isSy
     /** The full path to the entry. */
     path: string;
 }
+/**
+ * Supported compression types for file operations.
+ */
+export type CompressionType = "brotli" | "gzip" | "none";
 /**
  * Supported file encodings for reading files.
  */
@@ -175,6 +179,7 @@ export type WriteFileOptions = {
 export type JsonReplacer = (number | string)[] | ((this: unknown, key: string, value: unknown) => unknown) | null;
 /**
  * Type for the `replacer` parameter used in YAML serialization, similar to `JSON.stringify`'s replacer.
+ * @deprecated Use {@link JsonReplacer} directly instead.
  */
 export type YamlReplacer = JsonReplacer;
 /**

package/dist/utils.js

@@ -1,6 +1,6 @@
 export { default as JSONError } from './packem_shared/JSONError-BkHRnInH.js';
 export { default as assertValidFileContents } from './packem_shared/assertValidFileContents-BmcLtsGd.js';
 export { default as assertValidFileOrDirectoryPath } from './packem_shared/assertValidFileOrDirectoryPath-8HANmVjk.js';
-export { default as parseJson } from './packem_shared/parseJson-CqUuRguZ.js';
+export { default as parseJson } from './packem_shared/parseJson-C8xb-3LR.js';
 export { default as stripJsonComments } from './packem_shared/stripJsonComments-21XWVDwP.js';
 export { toPath } from '@visulima/path/utils';

package/dist/write/write-json-sync.d.ts

@@ -5,7 +5,6 @@ import type { WriteJsonOptions } from "../types.d.ts";
  * @param path The path to the JSON file to write. Can be a file URL or a string path.
  * @param data The data to serialize and write. Can be any JavaScript value that can be stringified by `JSON.stringify` or a custom stringifier.
  * @param options Optional configuration for writing the JSON file. See {@link WriteJsonOptions}.
- * @returns void
  * @example
  * ```javascript
  * import { writeJsonSync } from "@visulima/fs";

package/dist/yaml.js

@@ -1,4 +1,4 @@
-export { default as readYaml } from './packem_shared/readYaml-Bu1nsexB.js';
-export { default as readYamlSync } from './packem_shared/readYamlSync-Di88aMME.js';
+export { default as readYaml } from './packem_shared/readYaml-Cj6HxRoa.js';
+export { default as readYamlSync } from './packem_shared/readYamlSync-D3_iAKVv.js';
 export { default as writeYaml } from './packem_shared/writeYaml-BMY0kOPf.js';
 export { default as writeYamlSync } from './packem_shared/writeYamlSync-DqPu8cCd.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/fs",
-  "version": "4.0.6",
+  "version": "4.1.0",
   "description": "Human friendly file system utilities for Node.js",
   "keywords": [
     "anolilab",
@@ -113,6 +113,7 @@
     "LICENSE.md"
   ],
   "dependencies": {
+    "type-fest": "^5.2.0",
     "@visulima/path": "2.0.5"
   },
   "peerDependencies": {