@bgord/tools 0.12.12 → 0.12.14

package/dist/basename.vo.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod/v4";
+export declare const BasenameSchema: z.core.$ZodBranded<z.ZodString, "basename">;
+export type BasenameType = z.infer<typeof BasenameSchema>;

package/dist/basename.vo.js

@@ -0,0 +1,16 @@
+import { z } from "zod/v4";
+export const BasenameSchema = z
+    .string()
+    .trim()
+    .min(1, "basename_empty")
+    .max(128, "basename_too_long")
+    .refine((s) => !/[/\\]/.test(s), "basename_slashes_forbidden")
+    // biome-ignore lint: lint/suspicious/noControlCharactersInRegex
+    .refine((s) => !/[\u0000-\u001F\u007F]/.test(s), "basename_control_chars_forbidden")
+    // check dot-segments FIRST so "." / ".." get the intended error
+    .refine((s) => s !== "." && s !== "..", "basename_dot_segments_forbidden")
+    // then disallow any other dotfile (".env", ".gitignore", etc.)
+    .refine((s) => !s.startsWith("."), "basename_dotfiles_forbidden")
+    .refine((s) => !s.endsWith("."), "basename_trailing_dot_forbidden")
+    .regex(/^[A-Za-z0-9._-]+$/, "basename_bad_chars")
+    .brand("basename");

package/dist/directory-path-absolute.vo.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod/v4";
+export declare const DirectoryPathAbsoluteSchema: z.core.$ZodBranded<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodTransform<string, string>>, "absolute_directory_path">;
+export type DirectoryPathAbsoluteType = z.infer<typeof DirectoryPathAbsoluteSchema>;

package/dist/directory-path-absolute.vo.js

@@ -0,0 +1,17 @@
+import { z } from "zod/v4";
+export const DirectoryPathAbsoluteSchema = z
+    .string()
+    .trim()
+    .refine((value) => value.startsWith("/"), "abs_dir_must_start_with_slash")
+    .refine((value) => !value.includes("\\"), "abs_dir_backslash_forbidden")
+    // biome-ignore lint: lint/suspicious/noControlCharactersInRegex
+    .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), "abs_dir_control_chars_forbidden")
+    .transform((value) => value.replace(/\/{2,}/g, "/"))
+    .transform((value) => (value !== "/" && value.endsWith("/") ? value.slice(0, -1) : value))
+    .refine((value) => {
+    if (value === "/")
+        return true;
+    const segments = value.slice(1).split("/");
+    return segments.every((segment) => segment.length > 0 && /^[A-Za-z0-9._-]+$/.test(segment) && segment !== "." && segment !== "..");
+}, "abs_dir_bad_segments")
+    .brand("absolute_directory_path");

package/dist/directory-path-relative.vo.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod/v4";
+export declare const DirectoryPathRelativeSchema: z.core.$ZodBranded<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodTransform<string, string>>, "relative_directory_path">;
+export type DirectoryPathRelativeType = z.infer<typeof DirectoryPathRelativeSchema>;

package/dist/directory-path-relative.vo.js

@@ -0,0 +1,15 @@
+import { z } from "zod/v4";
+export const DirectoryPathRelativeSchema = z
+    .string()
+    .trim()
+    .refine((value) => !value.startsWith("/"), "rel_dir_must_not_start_with_slash")
+    .refine((value) => !value.includes("\\"), "rel_dir_backslash_forbidden")
+    // biome-ignore lint: lint/suspicious/noControlCharactersInRegex
+    .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), "rel_dir_control_chars_forbidden")
+    .transform((value) => value.replace(/\/{2,}/g, "/"))
+    .transform((value) => value.replace(/^\/+|\/+$/g, ""))
+    .refine((value) => value.length > 0, "rel_dir_empty")
+    .refine((value) => value
+    .split("/")
+    .every((segment) => /^[A-Za-z0-9._-]+$/.test(segment) && segment !== "." && segment !== ".."), "rel_dir_bad_segments")
+    .brand("relative_directory_path");

package/dist/extension.vo.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod/v4";
+export declare const ExtensionSchema: z.core.$ZodBranded<z.ZodPipe<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodTransform<string, string>>, z.ZodString>, "extension">;
+export type ExtensionType = z.infer<typeof ExtensionSchema>;

package/dist/extension.vo.js

@@ -0,0 +1,12 @@
+import { z } from "zod/v4";
+export const ExtensionSchema = z
+    .string()
+    .trim()
+    .transform((value) => (value.startsWith(".") ? value.slice(1) : value))
+    .transform((value) => value.toLowerCase())
+    .pipe(z
+    .string()
+    .min(1, "extension_empty")
+    .max(16, "extension_too_long")
+    .regex(/^[a-z0-9]+$/, "extension_bad_chars"))
+    .brand("extension");

package/dist/file-path.vo.d.ts

@@ -0,0 +1,29 @@
+import { type DirectoryPathAbsoluteType } from "./directory-path-absolute.vo";
+import { type DirectoryPathRelativeType } from "./directory-path-relative.vo";
+import type { Filename } from "./filename.vo";
+export declare class RelativeFilePath {
+    private readonly directory;
+    private readonly filename;
+    private constructor();
+    static fromParts(directoryCandidate: string, filename: Filename): RelativeFilePath;
+    static fromPartsSafe(directory: DirectoryPathRelativeType, filename: Filename): RelativeFilePath;
+    get(): string;
+    getDirectory(): DirectoryPathRelativeType;
+    getFilename(): Filename;
+    withDirectoryRelative(newDirectory: DirectoryPathRelativeType): RelativeFilePath;
+    withFilename(newFilename: Filename): RelativeFilePath;
+    toAbsolute(newDirectory: DirectoryPathAbsoluteType): AbsoluteFilePath;
+}
+export declare class AbsoluteFilePath {
+    private readonly directory;
+    private readonly filename;
+    private constructor();
+    static fromParts(directoryCandidate: string, filename: Filename): AbsoluteFilePath;
+    static fromPartsSafe(directory: DirectoryPathAbsoluteType, filename: Filename): AbsoluteFilePath;
+    get(): string;
+    getDirectory(): DirectoryPathAbsoluteType;
+    getFilename(): Filename;
+    withDirectoryAbsolute(newDirectory: DirectoryPathAbsoluteType): AbsoluteFilePath;
+    withFilename(newFilename: Filename): AbsoluteFilePath;
+    toRelative(newDirectory: DirectoryPathRelativeType): RelativeFilePath;
+}

package/dist/file-path.vo.js

@@ -0,0 +1,70 @@
+import { DirectoryPathAbsoluteSchema } from "./directory-path-absolute.vo";
+import { DirectoryPathRelativeSchema } from "./directory-path-relative.vo";
+export class RelativeFilePath {
+    directory;
+    filename;
+    constructor(directory, filename) {
+        this.directory = directory;
+        this.filename = filename;
+    }
+    static fromParts(directoryCandidate, filename) {
+        const directory = DirectoryPathRelativeSchema.parse(directoryCandidate);
+        return new RelativeFilePath(directory, filename);
+    }
+    static fromPartsSafe(directory, filename) {
+        return new RelativeFilePath(directory, filename);
+    }
+    get() {
+        return `${this.directory}/${this.filename.get()}`;
+    }
+    getDirectory() {
+        return this.directory;
+    }
+    getFilename() {
+        return this.filename;
+    }
+    withDirectoryRelative(newDirectory) {
+        return new RelativeFilePath(newDirectory, this.filename);
+    }
+    withFilename(newFilename) {
+        return new RelativeFilePath(this.directory, newFilename);
+    }
+    toAbsolute(newDirectory) {
+        return AbsoluteFilePath.fromPartsSafe(newDirectory, this.filename);
+    }
+}
+export class AbsoluteFilePath {
+    directory;
+    filename;
+    constructor(directory, filename) {
+        this.directory = directory;
+        this.filename = filename;
+    }
+    static fromParts(directoryCandidate, filename) {
+        const directory = DirectoryPathAbsoluteSchema.parse(directoryCandidate);
+        return new AbsoluteFilePath(directory, filename);
+    }
+    static fromPartsSafe(directory, filename) {
+        return new AbsoluteFilePath(directory, filename);
+    }
+    get() {
+        if (this.directory === "/")
+            return `/${this.filename.get()}`;
+        return `${this.directory}/${this.filename.get()}`;
+    }
+    getDirectory() {
+        return this.directory;
+    }
+    getFilename() {
+        return this.filename;
+    }
+    withDirectoryAbsolute(newDirectory) {
+        return new AbsoluteFilePath(newDirectory, this.filename);
+    }
+    withFilename(newFilename) {
+        return new AbsoluteFilePath(this.directory, newFilename);
+    }
+    toRelative(newDirectory) {
+        return RelativeFilePath.fromPartsSafe(newDirectory, this.filename);
+    }
+}

package/dist/filename-from-string.vo.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod/v4";
+export declare const FilenameFromStringSchema: z.ZodPipe<z.ZodString, z.ZodTransform<{
+    basename: string & z.core.$brand<"basename">;
+    extension: string & z.core.$brand<"extension">;
+}, string>>;
+export type FilenameFromString = z.infer<typeof FilenameFromStringSchema>;

package/dist/filename-from-string.vo.js

@@ -0,0 +1,17 @@
+import { z } from "zod/v4";
+import { BasenameSchema } from "./basename.vo";
+import { ExtensionSchema } from "./extension.vo";
+export const FilenameFromStringSchema = z
+    .string()
+    .trim()
+    .refine((string) => {
+    const index = string.lastIndexOf(".");
+    return index > 0 && index < string.length - 1;
+}, "filename_invalid")
+    // split and validate parts using existing schemas
+    .transform((string) => {
+    const index = string.lastIndexOf(".");
+    const base = BasenameSchema.parse(string.slice(0, index));
+    const extension = ExtensionSchema.parse(string.slice(index + 1));
+    return { basename: base, extension: extension };
+});

package/dist/filename-suffix.vo.d.ts

@@ -0,0 +1,3 @@
+import { z } from "zod/v4";
+export declare const FilenameSuffixSchema: z.core.$ZodBranded<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>, "basename_suffix">;
+export type FilenameSuffixSchemaType = z.infer<typeof FilenameSuffixSchema>;

package/dist/filename-suffix.vo.js

@@ -0,0 +1,7 @@
+import { z } from "zod/v4";
+export const FilenameSuffixSchema = z
+    .string()
+    .trim()
+    .transform((value) => value.replace(/[^A-Za-z0-9_-]/g, ""))
+    .pipe(z.string().max(32, "suffix_too_long"))
+    .brand("basename_suffix");

package/dist/filename.vo.d.ts

@@ -0,0 +1,18 @@
+import { type BasenameType } from "./basename.vo";
+import { type ExtensionType } from "./extension.vo";
+import { type FilenameSuffixSchemaType } from "./filename-suffix.vo";
+export declare class Filename {
+    private readonly basename;
+    private readonly extension;
+    private constructor();
+    static fromParts(basename: string, extension: string): Filename;
+    static fromPartsSafe(basename: BasenameType, extension: ExtensionType): Filename;
+    static fromString(candidate: string): Filename;
+    get(): string;
+    getBasename(): BasenameType;
+    getExtension(): ExtensionType;
+    withExtension(extension: ExtensionType): Filename;
+    withBasename(basename: BasenameType): Filename;
+    withSuffix(candidate: string): Filename;
+    withSuffixSafe(suffix: FilenameSuffixSchemaType): Filename;
+}

package/dist/filename.vo.js

@@ -0,0 +1,46 @@
+import { BasenameSchema } from "./basename.vo";
+import { ExtensionSchema } from "./extension.vo";
+import { FilenameFromStringSchema } from "./filename-from-string.vo";
+import { FilenameSuffixSchema } from "./filename-suffix.vo";
+export class Filename {
+    basename;
+    extension;
+    constructor(basename, extension) {
+        this.basename = basename;
+        this.extension = extension;
+    }
+    static fromParts(basename, extension) {
+        return new Filename(BasenameSchema.parse(basename), ExtensionSchema.parse(extension));
+    }
+    static fromPartsSafe(basename, extension) {
+        return new Filename(basename, extension);
+    }
+    static fromString(candidate) {
+        const { basename, extension } = FilenameFromStringSchema.parse(candidate);
+        return new Filename(basename, extension);
+    }
+    get() {
+        return `${this.basename}.${this.extension}`;
+    }
+    getBasename() {
+        return this.basename;
+    }
+    getExtension() {
+        return this.extension;
+    }
+    withExtension(extension) {
+        return new Filename(this.basename, extension);
+    }
+    withBasename(basename) {
+        return new Filename(basename, this.extension);
+    }
+    withSuffix(candidate) {
+        const suffix = FilenameSuffixSchema.parse(candidate);
+        const basename = BasenameSchema.parse(`${this.basename}${suffix}`);
+        return new Filename(basename, this.extension);
+    }
+    withSuffixSafe(suffix) {
+        const basename = BasenameSchema.parse(`${this.basename}${suffix}`);
+        return new Filename(basename, this.extension);
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./api-key.vo";
+export * from "./basename.vo";
 export * from "./build-version.vo";
 export * from "./clock.vo";
 export * from "./date-calculator.service";
@@ -7,10 +8,17 @@ export * from "./date-range.vo";
 export * from "./dates-of-the-week.vo";
 export * from "./day.vo";
 export * from "./day-iso-id.vo";
+export * from "./directory-path-absolute.vo";
+export * from "./directory-path-relative.vo";
 export * from "./dll.service";
 export * from "./email-mask.service";
 export * from "./etags.vo";
+export * from "./extension.vo";
 export * from "./feature-flag.vo";
+export * from "./file-path.vo";
+export * from "./filename.vo";
+export * from "./filename-from-string.vo";
+export * from "./filename-suffix.vo";
 export * from "./filter.vo";
 export * from "./hour.vo";
 export * from "./iban.vo";

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from "./api-key.vo";
+export * from "./basename.vo";
 export * from "./build-version.vo";
 export * from "./clock.vo";
 export * from "./date-calculator.service";
@@ -7,10 +8,17 @@ export * from "./date-range.vo";
 export * from "./dates-of-the-week.vo";
 export * from "./day.vo";
 export * from "./day-iso-id.vo";
+export * from "./directory-path-absolute.vo";
+export * from "./directory-path-relative.vo";
 export * from "./dll.service";
 export * from "./email-mask.service";
 export * from "./etags.vo";
+export * from "./extension.vo";
 export * from "./feature-flag.vo";
+export * from "./file-path.vo";
+export * from "./filename.vo";
+export * from "./filename-from-string.vo";
+export * from "./filename-suffix.vo";
 export * from "./filter.vo";
 export * from "./hour.vo";
 export * from "./iban.vo";

package/dist/mime.vo.d.ts

@@ -1,3 +1,4 @@
+import { type ExtensionType } from "./extension.vo";
 export type MimeRawType = string;
 type MimeTypeType = string;
 type MimeSubtypeType = string;
@@ -7,6 +8,7 @@ export declare class Mime {
     readonly subtype: MimeSubtypeType;
     constructor(value: MimeRawType);
     isSatisfiedBy(another: Mime): boolean;
+    toExtension(): ExtensionType;
 }
 export declare class InvalidMimeError extends Error {
     constructor();

package/dist/mime.vo.js

@@ -1,3 +1,4 @@
+import { ExtensionSchema } from "./extension.vo";
 export class Mime {
     raw;
     type;
@@ -22,6 +23,9 @@ export class Mime {
             return false;
         return this.subtype === another.subtype || this.subtype === "*";
     }
+    toExtension() {
+        return ExtensionSchema.parse(this.subtype);
+    }
 }
 export class InvalidMimeError extends Error {
     constructor() {

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/api-key.vo.ts","../src/build-version.vo.ts","../src/clock.vo.ts","../src/date-calculator.service.ts","../src/date-formatter.service.ts","../src/date-range.vo.ts","../src/dates-of-the-week.vo.ts","../src/day-iso-id.vo.ts","../src/day.vo.ts","../src/dll.service.ts","../src/email-mask.service.ts","../src/etags.vo.ts","../src/feature-flag.vo.ts","../src/filter.vo.ts","../src/hour.vo.ts","../src/iban-mask.service.ts","../src/iban.vo.ts","../src/image.vo.ts","../src/index.ts","../src/language.vo.ts","../src/leap-year-checker.service.ts","../src/mean.service.ts","../src/mime-types.vo.ts","../src/mime.vo.ts","../src/min-max-scaler.service.ts","../src/minute.vo.ts","../src/money.vo.ts","../src/noop.service.ts","../src/notification-template.vo.ts","../src/outlier-detector.service.ts","../src/package-version.vo.ts","../src/pagination.service.ts","../src/percentage.service.ts","../src/population-standard-deviation.service.ts","../src/random.service.ts","../src/rate-limiter.service.ts","../src/relative-date.vo.ts","../src/reordering.service.ts","../src/revision.vo.ts","../src/rounding.service.ts","../src/simple-linear-regression.service.ts","../src/size.vo.ts","../src/stepper.service.ts","../src/stopwatch.service.ts","../src/streak-calculator.service.ts","../src/sum.service.ts","../src/thousands-separator.service.ts","../src/time-zone-offset-value.vo.ts","../src/time.service.ts","../src/timestamp.vo.ts","../src/timezone.vo.ts","../src/ts-utils.ts","../src/visually-unambiguous-characters-generator.service.ts","../src/week-iso-id.vo.ts","../src/week.vo.ts","../src/z-score.service.ts"],"version":"5.9.2"}
+{"root":["../src/api-key.vo.ts","../src/basename.vo.ts","../src/build-version.vo.ts","../src/clock.vo.ts","../src/date-calculator.service.ts","../src/date-formatter.service.ts","../src/date-range.vo.ts","../src/dates-of-the-week.vo.ts","../src/day-iso-id.vo.ts","../src/day.vo.ts","../src/directory-path-absolute.vo.ts","../src/directory-path-relative.vo.ts","../src/dll.service.ts","../src/email-mask.service.ts","../src/etags.vo.ts","../src/extension.vo.ts","../src/feature-flag.vo.ts","../src/file-path.vo.ts","../src/filename-from-string.vo.ts","../src/filename-suffix.vo.ts","../src/filename.vo.ts","../src/filter.vo.ts","../src/hour.vo.ts","../src/iban-mask.service.ts","../src/iban.vo.ts","../src/image.vo.ts","../src/index.ts","../src/language.vo.ts","../src/leap-year-checker.service.ts","../src/mean.service.ts","../src/mime-types.vo.ts","../src/mime.vo.ts","../src/min-max-scaler.service.ts","../src/minute.vo.ts","../src/money.vo.ts","../src/noop.service.ts","../src/notification-template.vo.ts","../src/outlier-detector.service.ts","../src/package-version.vo.ts","../src/pagination.service.ts","../src/percentage.service.ts","../src/population-standard-deviation.service.ts","../src/random.service.ts","../src/rate-limiter.service.ts","../src/relative-date.vo.ts","../src/reordering.service.ts","../src/revision.vo.ts","../src/rounding.service.ts","../src/simple-linear-regression.service.ts","../src/size.vo.ts","../src/stepper.service.ts","../src/stopwatch.service.ts","../src/streak-calculator.service.ts","../src/sum.service.ts","../src/thousands-separator.service.ts","../src/time-zone-offset-value.vo.ts","../src/time.service.ts","../src/timestamp.vo.ts","../src/timezone.vo.ts","../src/ts-utils.ts","../src/visually-unambiguous-characters-generator.service.ts","../src/week-iso-id.vo.ts","../src/week.vo.ts","../src/z-score.service.ts"],"version":"5.9.2"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bgord/tools",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "type": "module",
   "license": "MIT",
   "author": "Bartosz Gordon",
@@ -30,11 +30,14 @@
     "lefthook": "1.12.3",
     "only-allow": "1.2.1",
     "shellcheck": "4.1.0",
-    "typescript": "5.9.2"
+    "typescript": "5.9.2",
+    "zod": "4.1.1"
   },
   "dependencies": {
-    "date-fns": "4.1.0",
-    "zod": "3.25.76"
+    "date-fns": "4.1.0"
+  },
+  "peerDependencies": {
+    "zod": "4.1.1"
   },
   "sideEffects": false
 }

package/readme.md

@@ -25,6 +25,7 @@ Run the tests
 ```
 src/
 ├── api-key.vo.ts
+├── basename.vo.ts
 ├── build-version.vo.ts
 ├── clock.vo.ts
 ├── date-calculator.service.ts
@@ -33,10 +34,17 @@ src/
 ├── dates-of-the-week.vo.ts
 ├── day-iso-id.vo.ts
 ├── day.vo.ts
+├── directory-path-absolute.vo.ts
+├── directory-path-relative.vo.ts
 ├── dll.service.ts
 ├── email-mask.service.ts
 ├── etags.vo.ts
+├── extension.vo.ts
 ├── feature-flag.vo.ts
+├── file-path.vo.ts
+├── filename-from-string.vo.ts
+├── filename-suffix.vo.ts
+├── filename.vo.ts
 ├── filter.vo.ts
 ├── hour.vo.ts
 ├── iban-mask.service.ts

package/src/basename.vo.ts

@@ -0,0 +1,19 @@
+import { z } from "zod/v4";
+
+export const BasenameSchema = z
+  .string()
+  .trim()
+  .min(1, "basename_empty")
+  .max(128, "basename_too_long")
+  .refine((s) => !/[/\\]/.test(s), "basename_slashes_forbidden")
+  // biome-ignore lint: lint/suspicious/noControlCharactersInRegex
+  .refine((s) => !/[\u0000-\u001F\u007F]/.test(s), "basename_control_chars_forbidden")
+  // check dot-segments FIRST so "." / ".." get the intended error
+  .refine((s) => s !== "." && s !== "..", "basename_dot_segments_forbidden")
+  // then disallow any other dotfile (".env", ".gitignore", etc.)
+  .refine((s) => !s.startsWith("."), "basename_dotfiles_forbidden")
+  .refine((s) => !s.endsWith("."), "basename_trailing_dot_forbidden")
+  .regex(/^[A-Za-z0-9._-]+$/, "basename_bad_chars")
+  .brand("basename");
+
+export type BasenameType = z.infer<typeof BasenameSchema>;

package/src/directory-path-absolute.vo.ts

@@ -0,0 +1,22 @@
+import { z } from "zod/v4";
+
+export const DirectoryPathAbsoluteSchema = z
+  .string()
+  .trim()
+  .refine((value) => value.startsWith("/"), "abs_dir_must_start_with_slash")
+  .refine((value) => !value.includes("\\"), "abs_dir_backslash_forbidden")
+  // biome-ignore lint: lint/suspicious/noControlCharactersInRegex
+  .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), "abs_dir_control_chars_forbidden")
+  .transform((value) => value.replace(/\/{2,}/g, "/"))
+  .transform((value) => (value !== "/" && value.endsWith("/") ? value.slice(0, -1) : value))
+  .refine((value) => {
+    if (value === "/") return true;
+    const segments = value.slice(1).split("/");
+    return segments.every(
+      (segment) =>
+        segment.length > 0 && /^[A-Za-z0-9._-]+$/.test(segment) && segment !== "." && segment !== "..",
+    );
+  }, "abs_dir_bad_segments")
+  .brand("absolute_directory_path");
+
+export type DirectoryPathAbsoluteType = z.infer<typeof DirectoryPathAbsoluteSchema>;

package/src/directory-path-relative.vo.ts

@@ -0,0 +1,22 @@
+import { z } from "zod/v4";
+
+export const DirectoryPathRelativeSchema = z
+  .string()
+  .trim()
+  .refine((value) => !value.startsWith("/"), "rel_dir_must_not_start_with_slash")
+  .refine((value) => !value.includes("\\"), "rel_dir_backslash_forbidden")
+  // biome-ignore lint: lint/suspicious/noControlCharactersInRegex
+  .refine((value) => !/[\u0000-\u001F\u007F]/.test(value), "rel_dir_control_chars_forbidden")
+  .transform((value) => value.replace(/\/{2,}/g, "/"))
+  .transform((value) => value.replace(/^\/+|\/+$/g, ""))
+  .refine((value) => value.length > 0, "rel_dir_empty")
+  .refine(
+    (value) =>
+      value
+        .split("/")
+        .every((segment) => /^[A-Za-z0-9._-]+$/.test(segment) && segment !== "." && segment !== ".."),
+    "rel_dir_bad_segments",
+  )
+  .brand("relative_directory_path");
+
+export type DirectoryPathRelativeType = z.infer<typeof DirectoryPathRelativeSchema>;

package/src/extension.vo.ts

@@ -0,0 +1,17 @@
+import { z } from "zod/v4";
+
+export const ExtensionSchema = z
+  .string()
+  .trim()
+  .transform((value) => (value.startsWith(".") ? value.slice(1) : value))
+  .transform((value) => value.toLowerCase())
+  .pipe(
+    z
+      .string()
+      .min(1, "extension_empty")
+      .max(16, "extension_too_long")
+      .regex(/^[a-z0-9]+$/, "extension_bad_chars"),
+  )
+  .brand("extension");
+
+export type ExtensionType = z.infer<typeof ExtensionSchema>;

package/src/file-path.vo.ts

@@ -0,0 +1,84 @@
+import { DirectoryPathAbsoluteSchema, type DirectoryPathAbsoluteType } from "./directory-path-absolute.vo";
+import { DirectoryPathRelativeSchema, type DirectoryPathRelativeType } from "./directory-path-relative.vo";
+import type { Filename } from "./filename.vo";
+
+export class RelativeFilePath {
+  private constructor(
+    private readonly directory: DirectoryPathRelativeType,
+    private readonly filename: Filename,
+  ) {}
+
+  static fromParts(directoryCandidate: string, filename: Filename) {
+    const directory = DirectoryPathRelativeSchema.parse(directoryCandidate);
+    return new RelativeFilePath(directory, filename);
+  }
+
+  static fromPartsSafe(directory: DirectoryPathRelativeType, filename: Filename) {
+    return new RelativeFilePath(directory, filename);
+  }
+
+  get() {
+    return `${this.directory}/${this.filename.get()}`;
+  }
+
+  getDirectory(): DirectoryPathRelativeType {
+    return this.directory;
+  }
+
+  getFilename(): Filename {
+    return this.filename;
+  }
+
+  withDirectoryRelative(newDirectory: DirectoryPathRelativeType): RelativeFilePath {
+    return new RelativeFilePath(newDirectory, this.filename);
+  }
+
+  withFilename(newFilename: Filename): RelativeFilePath {
+    return new RelativeFilePath(this.directory, newFilename);
+  }
+
+  toAbsolute(newDirectory: DirectoryPathAbsoluteType): AbsoluteFilePath {
+    return AbsoluteFilePath.fromPartsSafe(newDirectory, this.filename);
+  }
+}
+
+export class AbsoluteFilePath {
+  private constructor(
+    private readonly directory: DirectoryPathAbsoluteType,
+    private readonly filename: Filename,
+  ) {}
+
+  static fromParts(directoryCandidate: string, filename: Filename) {
+    const directory = DirectoryPathAbsoluteSchema.parse(directoryCandidate);
+    return new AbsoluteFilePath(directory, filename);
+  }
+
+  static fromPartsSafe(directory: DirectoryPathAbsoluteType, filename: Filename) {
+    return new AbsoluteFilePath(directory, filename);
+  }
+
+  get() {
+    if (this.directory === ("/" as DirectoryPathAbsoluteType)) return `/${this.filename.get()}`;
+    return `${this.directory}/${this.filename.get()}`;
+  }
+
+  getDirectory(): DirectoryPathAbsoluteType {
+    return this.directory;
+  }
+
+  getFilename(): Filename {
+    return this.filename;
+  }
+
+  withDirectoryAbsolute(newDirectory: DirectoryPathAbsoluteType): AbsoluteFilePath {
+    return new AbsoluteFilePath(newDirectory, this.filename);
+  }
+
+  withFilename(newFilename: Filename): AbsoluteFilePath {
+    return new AbsoluteFilePath(this.directory, newFilename);
+  }
+
+  toRelative(newDirectory: DirectoryPathRelativeType): RelativeFilePath {
+    return RelativeFilePath.fromPartsSafe(newDirectory, this.filename);
+  }
+}

package/src/filename-from-string.vo.ts

@@ -0,0 +1,20 @@
+import { z } from "zod/v4";
+import { BasenameSchema } from "./basename.vo";
+import { ExtensionSchema } from "./extension.vo";
+
+export const FilenameFromStringSchema = z
+  .string()
+  .trim()
+  .refine((string) => {
+    const index = string.lastIndexOf(".");
+    return index > 0 && index < string.length - 1;
+  }, "filename_invalid")
+  // split and validate parts using existing schemas
+  .transform((string) => {
+    const index = string.lastIndexOf(".");
+    const base = BasenameSchema.parse(string.slice(0, index));
+    const extension = ExtensionSchema.parse(string.slice(index + 1));
+    return { basename: base, extension: extension };
+  });
+
+export type FilenameFromString = z.infer<typeof FilenameFromStringSchema>;

package/src/filename-suffix.vo.ts

@@ -0,0 +1,10 @@
+import { z } from "zod/v4";
+
+export const FilenameSuffixSchema = z
+  .string()
+  .trim()
+  .transform((value) => value.replace(/[^A-Za-z0-9_-]/g, ""))
+  .pipe(z.string().max(32, "suffix_too_long"))
+  .brand("basename_suffix");
+
+export type FilenameSuffixSchemaType = z.infer<typeof FilenameSuffixSchema>;

package/src/filename.vo.ts

@@ -0,0 +1,58 @@
+import { BasenameSchema, type BasenameType } from "./basename.vo";
+import { ExtensionSchema, type ExtensionType } from "./extension.vo";
+import { FilenameFromStringSchema } from "./filename-from-string.vo";
+import { FilenameSuffixSchema, type FilenameSuffixSchemaType } from "./filename-suffix.vo";
+
+export class Filename {
+  private constructor(
+    private readonly basename: BasenameType,
+    private readonly extension: ExtensionType,
+  ) {}
+
+  static fromParts(basename: string, extension: string) {
+    return new Filename(BasenameSchema.parse(basename), ExtensionSchema.parse(extension));
+  }
+
+  static fromPartsSafe(basename: BasenameType, extension: ExtensionType) {
+    return new Filename(basename, extension);
+  }
+
+  static fromString(candidate: string) {
+    const { basename, extension } = FilenameFromStringSchema.parse(candidate);
+
+    return new Filename(basename, extension);
+  }
+
+  get() {
+    return `${this.basename}.${this.extension}`;
+  }
+
+  getBasename(): BasenameType {
+    return this.basename;
+  }
+
+  getExtension(): ExtensionType {
+    return this.extension;
+  }
+
+  withExtension(extension: ExtensionType): Filename {
+    return new Filename(this.basename, extension);
+  }
+
+  withBasename(basename: BasenameType): Filename {
+    return new Filename(basename, this.extension);
+  }
+
+  withSuffix(candidate: string): Filename {
+    const suffix = FilenameSuffixSchema.parse(candidate);
+    const basename = BasenameSchema.parse(`${this.basename}${suffix}`);
+
+    return new Filename(basename, this.extension);
+  }
+
+  withSuffixSafe(suffix: FilenameSuffixSchemaType): Filename {
+    const basename = BasenameSchema.parse(`${this.basename}${suffix}`);
+
+    return new Filename(basename, this.extension);
+  }
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./api-key.vo";
+export * from "./basename.vo";
 export * from "./build-version.vo";
 export * from "./clock.vo";
 export * from "./date-calculator.service";
@@ -7,10 +8,17 @@ export * from "./date-range.vo";
 export * from "./dates-of-the-week.vo";
 export * from "./day.vo";
 export * from "./day-iso-id.vo";
+export * from "./directory-path-absolute.vo";
+export * from "./directory-path-relative.vo";
 export * from "./dll.service";
 export * from "./email-mask.service";
 export * from "./etags.vo";
+export * from "./extension.vo";
 export * from "./feature-flag.vo";
+export * from "./file-path.vo";
+export * from "./filename.vo";
+export * from "./filename-from-string.vo";
+export * from "./filename-suffix.vo";
 export * from "./filter.vo";
 export * from "./hour.vo";
 export * from "./iban.vo";

package/src/mime.vo.ts

@@ -1,3 +1,5 @@
+import { ExtensionSchema, type ExtensionType } from "./extension.vo";
+
 export type MimeRawType = string;
 
 type MimeTypeType = string;
@@ -33,6 +35,10 @@ export class Mime {
 
     return this.subtype === another.subtype || this.subtype === "*";
   }
+
+  toExtension(): ExtensionType {
+    return ExtensionSchema.parse(this.subtype);
+  }
 }
 
 export class InvalidMimeError extends Error {