@real1ty-obsidian-plugins/utils 2.28.0 → 2.30.0

package/dist/file/file.d.ts

@@ -1,332 +0,0 @@
-import type { App, CachedMetadata } from "obsidian";
-import { TFile } from "obsidian";
-/**
- * Retrieves a TFile object from the vault by its path.
- * Handles path normalization using Obsidian's normalizePath utility.
- *
- * **Important**: Obsidian file paths ALWAYS include the `.md` extension.
- * The TFile.path property returns paths like "folder/file.md", not "folder/file".
- *
- * @param app - The Obsidian App instance
- * @param filePath - Path to the file (will be normalized, should include .md extension)
- * @returns TFile if found, null otherwise
- *
- * @example
- * ```ts
- * // Correct: Include .md extension
- * const file = getFileByPath(app, "folder/note.md");
- *
- * // For wikilinks without extension, add .md
- * const linkPath = "MyNote";
- * const file = getFileByPath(app, `${linkPath}.md`);
- * ```
- */
-export declare function getFileByPath(app: App, filePath: string): TFile | null;
-/**
- * Ensures a file path includes the .md extension.
- * Use this when working with wikilinks or user input that may omit extensions.
- *
- * @param path - File path that may or may not include .md extension
- * @returns Path guaranteed to end with .md
- *
- * @example
- * ```ts
- * ensureMarkdownExtension("MyNote") // "MyNote.md"
- * ensureMarkdownExtension("MyNote.md") // "MyNote.md"
- * ensureMarkdownExtension("folder/note") // "folder/note.md"
- * ```
- */
-export declare function ensureMarkdownExtension(path: string): string;
-/**
- * Removes the .md extension from a file path if present.
- * Useful for displaying file names or creating wikilinks.
- *
- * @param path - File path that may include .md extension
- * @returns Path without .md extension
- *
- * @example
- * ```ts
- * removeMarkdownExtension("folder/note.md") // "folder/note"
- * removeMarkdownExtension("folder/note") // "folder/note"
- * ```
- */
-export declare function removeMarkdownExtension(path: string): string;
-/**
- * Extracts the display name from a file path or wiki link.
- *
- * Handles various formats:
- * - `[[path/to/file|Alias]]` -> returns "Alias"
- * - `[[path/to/file]]` -> returns "file"
- * - `path/to/file.md` -> returns "file"
- * - `file.md` -> returns "file"
- *
- * @param input - File path or wiki link string
- * @returns The display name to show in the UI
- */
-export declare function extractDisplayName(input: string): string;
-/**
- * Extracts the actual file path from a wiki link or returns the path as-is.
- *
- * Handles:
- * - `[[path/to/file|Alias]]` -> returns "path/to/file.md"
- * - `[[path/to/file]]` -> returns "path/to/file.md"
- * - `path/to/file.md` -> returns "path/to/file.md"
- *
- * @param input - File path or wiki link string
- * @returns The actual file path (with .md extension)
- */
-export declare function extractFilePath(input: string): string;
-export interface FileContext {
-    path: string;
-    pathWithExt: string;
-    baseName: string;
-    file: TFile | null;
-    frontmatter: Record<string, any> | undefined;
-    cache: CachedMetadata | null;
-}
-/**
- * Creates a comprehensive file context object containing all relevant file information.
- * Handles path normalization, file lookup, and metadata caching.
- */
-export declare function getFileContext(app: App, path: string): FileContext;
-/**
- * Helper function to work with file context that automatically handles file not found cases.
- * Returns null if the file doesn't exist, otherwise executes the callback with the context.
- */
-export declare function withFileContext<T>(app: App, path: string, callback: (context: FileContext) => Promise<T> | T): Promise<T | null>;
-/**
- * Generates a unique file path by appending a counter if the file already exists.
- * Automatically adds .md extension if not present.
- *
- * @param app - The Obsidian App instance
- * @param folder - Folder path (empty string for root, no trailing slash needed)
- * @param baseName - Base file name without extension
- * @returns Unique file path that doesn't exist in the vault
- *
- * @example
- * ```ts
- * // If "MyNote.md" exists, returns "MyNote 1.md"
- * const path = getUniqueFilePath(app, "", "MyNote");
- *
- * // With folder: "Projects/Task.md" -> "Projects/Task 1.md"
- * const path = getUniqueFilePath(app, "Projects", "Task");
- *
- * // Root folder handling
- * const path = getUniqueFilePath(app, "/", "Note"); // -> "Note.md"
- * ```
- */
-export declare function getUniqueFilePath(app: App, folder: string, baseName: string): string;
-/**
- * Generates a unique file path by appending a counter if the file already exists.
- * Accepts a complete file path and iterates with a counter suffix.
- *
- * @param app - The Obsidian App instance
- * @param filePath - Complete file path including folder, name, and extension
- * @returns Unique file path that doesn't exist in the vault
- *
- * @example
- * ```ts
- * // If "folder/note.md" exists, returns "folder/note 1.md"
- * const path = getUniqueFilePathFromFull(app, "folder/note.md");
- *
- * // Works with any extension
- * const path = getUniqueFilePathFromFull(app, "assets/image.png");
- * // -> "assets/image 1.png" if image.png exists
- * ```
- */
-export declare const getUniqueFilePathFromFull: (app: App, filePath: string) => string;
-/**
- * Generates a unique file path by appending a counter if the file already exists.
- * Supports custom file extensions.
- *
- * @param app - The Obsidian App instance
- * @param folder - Folder path (empty string for root)
- * @param baseName - Base file name without extension
- * @param extension - File extension (defaults to "md")
- * @returns Unique file path that doesn't exist in the vault
- */
-export declare const generateUniqueFilePath: (app: App, folder: string, baseName: string, extension?: string) => string;
-/**
- * Checks if a file is a folder note.
- * A folder note is a file whose name matches its parent folder name.
- *
- * @param filePath - Path to the file (e.g., "tasks/tasks.md")
- * @returns true if the file is a folder note, false otherwise
- *
- * @example
- * ```ts
- * isFolderNote("tasks/tasks.md") // true
- * isFolderNote("tasks/subtask.md") // false
- * isFolderNote("note.md") // false (no parent folder)
- * isFolderNote("projects/docs/docs.md") // true
- * ```
- */
-export declare function isFolderNote(filePath: string): boolean;
-/**
- * Gets the folder path for a file.
- *
- * @param filePath - Path to the file (e.g., "tasks/subtask.md")
- * @returns Folder path without trailing slash, or empty string if file is in root
- *
- * @example
- * ```ts
- * getFolderPath("tasks/subtask.md") // "tasks"
- * getFolderPath("projects/docs/notes.md") // "projects/docs"
- * getFolderPath("note.md") // ""
- * ```
- */
-export declare function getFolderPath(filePath: string): string;
-/**
- * Gets all markdown files in a specific folder (non-recursive).
- *
- * @param app - The Obsidian App instance
- * @param folderPath - Path to the folder (e.g., "tasks")
- * @returns Array of TFile objects in the folder
- *
- * @example
- * ```ts
- * const files = getFilesInFolder(app, "tasks");
- * // Returns [task1.md, task2.md, tasks.md] but not tasks/subtasks/file.md
- * ```
- */
-export declare function getFilesInFolder(app: App, folderPath: string): TFile[];
-/**
- * Gets all markdown files in a folder and its subfolders recursively.
- *
- * @param app - The Obsidian App instance
- * @param folderPath - Path to the folder (e.g., "tasks")
- * @returns Array of TFile objects in the folder tree
- *
- * @example
- * ```ts
- * const files = getAllFilesInFolderTree(app, "tasks");
- * // Returns all .md files in tasks/ and all its subdirectories
- * ```
- */
-export declare function getAllFilesInFolderTree(app: App, folderPath: string): TFile[];
-/**
- * Gets the parent file path based on folder structure.
- * For a file in a folder, the parent is the folder note if it exists.
- *
- * @param app - The Obsidian App instance
- * @param filePath - Path to the file
- * @returns Path to parent file, or null if no parent exists
- *
- * @example
- * ```ts
- * // If tasks/tasks.md exists
- * getParentByFolder(app, "tasks/subtask.md") // "tasks/tasks.md"
- *
- * // If parent folder note doesn't exist
- * getParentByFolder(app, "tasks/subtask.md") // null
- *
- * // Root level file
- * getParentByFolder(app, "note.md") // null
- * ```
- */
-export declare function getParentByFolder(app: App, filePath: string): string | null;
-/**
- * Gets all child file paths based on folder structure.
- * Works for both folder notes and regular files.
- *
- * For folder notes (e.g., "tasks/tasks.md"):
- * - Returns all files directly in the folder (excluding the folder note)
- * - Includes subfolder notes one level down
- *
- * For regular files (e.g., "tasks/task1.md"):
- * - Returns the folder note from matching subfolder if it exists (e.g., "tasks/task1/task1.md")
- *
- * @param app - The Obsidian App instance
- * @param filePath - Path to the file
- * @returns Array of child file paths
- *
- * @example
- * ```ts
- * // For tasks/tasks.md (folder note)
- * getChildrenByFolder(app, "tasks/tasks.md")
- * // Returns ["tasks/task1.md", "tasks/task2.md", "tasks/subtasks/subtasks.md"]
- *
- * // For tasks/task1.md (regular file with matching subfolder)
- * getChildrenByFolder(app, "tasks/task1.md")
- * // Returns ["tasks/task1/task1.md"] if it exists
- * ```
- */
-export declare function getChildrenByFolder(app: App, filePath: string): string[];
-/**
- * Finds all root nodes in a folder tree.
- * Root nodes are files at the top level of the folder (directly in the folder, not in subfolders).
- *
- * @param app - The Obsidian App instance
- * @param folderPath - Path to the folder
- * @returns Array of root file paths
- *
- * @example
- * ```ts
- * // For folder structure:
- * // tasks/
- * //   tasks.md (folder note)
- * //   task1.md
- * //   subtasks/
- * //     subtasks.md
- * //     subtask1.md
- *
- * findRootNodesInFolder(app, "tasks")
- * // Returns ["tasks/tasks.md", "tasks/task1.md"]
- * // Excludes subtasks/subtasks.md and subtasks/subtask1.md (they're in subfolder)
- * ```
- */
-export declare function findRootNodesInFolder(app: App, folderPath: string): string[];
-export interface SanitizeFilenameOptions {
-    /**
-     * Style of sanitization to apply.
-     * - "kebab": Convert to lowercase, replace spaces with hyphens (default, backwards compatible)
-     * - "preserve": Preserve spaces and case, only remove invalid characters
-     */
-    style?: "kebab" | "preserve";
-}
-/**
- * Sanitizes a string for use as a filename.
- * Defaults to kebab-case style for backwards compatibility.
- *
- * @param input - String to sanitize
- * @param options - Sanitization options
- * @returns Sanitized filename string
- *
- * @example
- * // Default kebab-case style (backwards compatible)
- * sanitizeForFilename("My File Name") // "my-file-name"
- *
- * // Preserve spaces and case
- * sanitizeForFilename("My File Name", { style: "preserve" }) // "My File Name"
- */
-export declare const sanitizeForFilename: (input: string, options?: SanitizeFilenameOptions) => string;
-/**
- * Sanitizes filename using kebab-case style.
- * - Removes invalid characters
- * - Converts to lowercase
- * - Replaces spaces with hyphens
- *
- * Best for: CLI tools, URLs, slugs, technical files
- *
- * @example
- * sanitizeFilenameKebabCase("My File Name") // "my-file-name"
- * sanitizeFilenameKebabCase("Travel Around The World") // "travel-around-the-world"
- */
-export declare const sanitizeFilenameKebabCase: (input: string) => string;
-/**
- * Sanitizes filename while preserving spaces and case.
- * - Removes invalid characters only
- * - Preserves spaces and original casing
- * - Removes trailing dots (Windows compatibility)
- *
- * Best for: Note titles, human-readable filenames, Obsidian notes
- *
- * @example
- * sanitizeFilenamePreserveSpaces("My File Name") // "My File Name"
- * sanitizeFilenamePreserveSpaces("Travel Around The World") // "Travel Around The World"
- * sanitizeFilenamePreserveSpaces("File<Invalid>Chars") // "FileInvalidChars"
- */
-export declare const sanitizeFilenamePreserveSpaces: (input: string) => string;
-export declare const getFilenameFromPath: (filePath: string) => string;
-export declare const isFileInConfiguredDirectory: (filePath: string, directory: string) => boolean;
-//# sourceMappingURL=file.d.ts.map

package/dist/file/file.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../src/file/file.ts"],"names":[],"mappings":"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"}