@fnndsc/salsa 3.2.4

package/dist/files/index.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @file File group resolution and content dispatch across file source types.
+ *
+ * @module
+ */
+import { ChRISEmbeddedResourceGroup, ListOptions, FilteredResourceData, Result } from "@fnndsc/cumin";
+import { ChrisPathNode } from "@fnndsc/cumin";
+/**
+ * Represents a file or directory item in a recursive listing.
+ */
+export interface FsItem {
+    path: string;
+    type: 'file' | 'dir';
+    size?: number;
+}
+/**
+ * Recursively lists all files and directories under a given ChRIS path.
+ *
+ * @param rootPath - The starting directory path.
+ * @returns A Promise resolving to an array of FsItem objects.
+ */
+export declare function files_listRecursive(rootPath: string): Promise<FsItem[]>;
+/**
+ * Recursively copies a directory from source to destination within ChRIS.
+ *
+ * @param srcPath - The source directory path.
+ * @param destPath - The destination directory path (the parent + new dir name).
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function files_copyRecursively(srcPath: string, destPath: string): Promise<boolean>;
+/**
+ * Uploads content to a specified ChRIS path, effectively creating or overwriting a file.
+ *
+ * @param content - The content to upload (string, Buffer, or Blob).
+ * @param pathStr - The ChRIS path for the new file.
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function files_create(content: string | Buffer | Blob, pathStr: string): Promise<boolean>;
+/**
+ * Creates a new empty file at the specified path (like Unix touch).
+ * Optionally creates the file with specified content.
+ *
+ * @param path - The ChRIS path for the new file.
+ * @param content - Optional content to write to the file (string, Buffer, or Blob).
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function files_touch(path: string, content?: string | Buffer | Blob): Promise<boolean>;
+/**
+ * Copies a single file from one ChRIS path to another.
+ *
+ * @param srcPath - The full path to the source file.
+ * @param destPath - The full path to the destination file (including filename).
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function files_copy(srcPath: string, destPath: string): Promise<boolean>;
+/**
+ * Moves a file or directory by updating its path on the server.
+ *
+ * For directories, this performs a server-side rename without data transfer.
+ * For files, the file ID is resolved and the path is updated.
+ *
+ * @param srcPath - The source file or directory path.
+ * @param destPath - The target path. If an existing directory or trailing slash is provided,
+ *                   the source basename is appended.
+ * @returns Promise resolving to true on success, false on failure.
+ */
+export declare function files_move(srcPath: string, destPath: string): Promise<boolean>;
+/**
+ * Uploads a local file or directory to ChRIS recursively.
+ *
+ * @param localPath - The local filesystem path.
+ * @param remotePath - The ChRIS destination path.
+ * @returns Promise<boolean> success.
+ */
+export declare function files_uploadPath(localPath: string, remotePath: string): Promise<boolean>;
+/**
+ * Creates a new folder (directory) at the specified ChRIS path.
+ *
+ * @param folderPath - The full ChRIS path for the new folder.
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function files_mkdir(folderPath: string): Promise<boolean>;
+/**
+ * Interface for file sharing options.
+ */
+export interface FileShareOptions {
+    is_public?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Creates a ChRISEmbeddedResourceGroup for a specific asset type (files, links, dirs).
+ * This function encapsulates the logic from `FileController.handler_create`.
+ *
+ * @param assetName - The type of asset ('files', 'links', 'dirs').
+ * @param path - Optional ChRIS path. Defaults to current folder context.
+ * @returns A Promise resolving to a ChRISEmbeddedResourceGroup instance, or null on error.
+ */
+export declare function files_getGroup(assetName: string, path?: string): Promise<ChRISEmbeddedResourceGroup<ChrisPathNode> | null>;
+/**
+ * List files, links, or directories based on options.
+ *
+ * @param options - Search and pagination options.
+ * @param assetName - The type of asset to list ('files', 'links', 'dirs').
+ * @param path - Optional ChRIS path. Defaults to current folder context.
+ * @returns A Promise resolving to FilteredResourceData or null.
+ */
+export declare function files_list(options: ListOptions, assetName?: string, path?: string): Promise<FilteredResourceData | null>;
+/**
+ * List *all* files, links, or directories by automatically handling pagination.
+ *
+ * @param options - Search options (limit and offset will be managed internally).
+ * @param assetName - The type of asset to list ('files', 'links', 'dirs').
+ * @param path - Optional ChRIS path. Defaults to current folder context.
+ * @returns A Promise resolving to FilteredResourceData containing all matching assets, or null.
+ */
+export declare function files_listAll(options: ListOptions, assetName?: string, path?: string): Promise<FilteredResourceData | null>;
+/**
+ * Get the list of available fields for files, links, or directories.
+ *
+ * @param assetName - The type of asset ('files', 'links', 'dirs').
+ * @returns A Promise resolving to an array of field names or null.
+ */
+export declare function fileFields_get(assetName?: string): Promise<string[] | null>;
+/**
+ * Deletes a file, link, or directory by its ID.
+ *
+ * @param id - The ID of the asset to delete.
+ * @param assetName - The type of asset ('files', 'links', 'dirs').
+ * @returns A Promise resolving to true on success, false on failure.
+ */
+export declare function files_delete(id: number, assetName?: string): Promise<boolean>;
+/**
+ * Creates a ChRISEmbeddedResourceGroup for a single file.
+ * This function encapsulates the logic from `FileController.member_create`.
+ *
+ * @param path - The ChRIS path to the file.
+ * @returns A Promise resolving to a ChRISEmbeddedResourceGroup instance, or null on error.
+ */
+export declare function files_getSingle(path: string): Promise<ChRISEmbeddedResourceGroup<ChrisPathNode> | null>;
+/**
+ * Shares files in ChRIS.
+ *
+ * @param fileId - The ID of the file to share.
+ * @param options - Options for sharing (e.g., user, permissions).
+ * @returns A Promise resolving to true.
+ */
+export declare function files_share(fileId: number, options: FileShareOptions): Promise<boolean>;
+/**
+ * Retrieves the content of a file by its path.
+ *
+ * Router function that delegates to specialized handlers based on path type.
+ *
+ * @param filePath - The full ChRIS path to the file.
+ * @returns A Result containing the content string or error.
+ */
+export declare function fileContent_get(filePath: string): Promise<Result<string>>;
+/**
+ * Retrieves the binary content of a file by its path.
+ *
+ * Router function that delegates to specialized handlers based on path type.
+ * Returns raw Buffer instead of converting to UTF-8 string.
+ *
+ * @param filePath - The full ChRIS path to the file.
+ * @returns A Result containing the content Buffer or error.
+ */
+export declare function fileContent_getBinary(filePath: string): Promise<Result<Buffer>>;
+/**
+ * Retrieves the binary content of a file by its path as a stream/blob.
+ *
+ * Router function that delegates to specialized handlers based on path type.
+ *
+ * @param filePath - The full ChRIS path to the file.
+ * @returns A Result containing the stream/blob and metadata or error.
+ */
+export declare function fileContent_getBinaryStream(filePath: string): Promise<Result<{
+    stream: unknown;
+    size?: number;
+    filename?: string;
+}>>;