@zenfs/core/dist/vfs/xattr.d.ts

A filesystem, anywhere

import type { BufferEncodingOption, ObjectEncodingOptions } from 'node:fs';
import type { V_Context } from '../context.js';
/**
 * Extended attribute name with namespace prefix.
 * Format is namespace.attributename where namespace is one of:
 * - user: User attributes
 * - trusted: Trusted attributes (privileged)
 * - system: System attributes
 * - security: Security attributes
 *
 * Note: Currently only the 'user' namespace is supported.
 */
export type Name = `${'user' | 'trusted' | 'system' | 'security'}.${string}`;
/**
 * Options for xattr operations.
 */
export interface Options {
    /**
     * If true, don't follow symlinks.
     * @default false
     */
    noFollow?: boolean;
    /**
     * Encoding for attribute values.
     * If 'buffer' or undefined, the value is returned as a Buffer.
     * Otherwise, the value is returned as a string using the specified encoding.
     * @default undefined
     */
    encoding?: BufferEncoding | 'buffer';
}
/**
 * Options for setting extended attributes.
 * Extends the base Options with additional flags for create/replace behavior.
 */
export interface SetOptions extends Options {
    /**
     * If true, fail if the attribute already exists.
     * @default false
     */
    create?: boolean;
    /**
     * If true, fail if the attribute does not exist.
     * @default false
     */
    replace?: boolean;
}
/**
 * Gets the value of an extended attribute.
 *
 * @param path Path to the file
 * @param name Name of the attribute to get
 * @param opt Options for the operation
 * @returns A buffer containing the attribute value when encoding is 'buffer' or undefined, or a string when a string encoding is specified
 */
export declare function get(this: V_Context, path: string, name: Name, opt?: Options & (BufferEncodingOption | {
    encoding?: null;
})): Promise<Uint8Array>;
export declare function get(this: V_Context, path: string, name: Name, opt: Options & ObjectEncodingOptions): Promise<string>;
/**
 * Synchronously gets the value of an extended attribute.
 *
 * @param path Path to the file
 * @param name Name of the attribute to get
 * @param opt Options for the operation
 * @returns A buffer containing the attribute value when encoding is 'buffer' or undefined, or a string when a string encoding is specified
 */
export declare function getSync(this: V_Context, path: string, name: Name, opt?: Options & (BufferEncodingOption | {
    encoding?: null;
})): Uint8Array;
export declare function getSync(this: V_Context, path: string, name: Name, opt: Options & ObjectEncodingOptions): string;
/**
 * Sets the value of an extended attribute.
 *
 * @param path Path to the file
 * @param name Name of the attribute to set
 * @param value Value to set
 * @param opt Options for the operation
 */
export declare function set(this: V_Context, path: string, name: Name, value: string | Uint8Array, opt?: SetOptions): Promise<void>;
/**
 * Synchronously sets the value of an extended attribute.
 *
 * @param path Path to the file
 * @param name Name of the attribute to set
 * @param value Value to set
 * @param opt Options for the operation
 */
export declare function setSync(this: V_Context, path: string, name: Name, value: string | Uint8Array, opt?: SetOptions): void;
/**
 * Removes an extended attribute from a file.
 *
 * @param path Path to the file
 * @param name Name of the attribute to remove
 */
export declare function remove(this: V_Context, path: string, name: Name): Promise<void>;
/**
 * Synchronously removes an extended attribute from a file.
 *
 * @param path Path to the file
 * @param name Name of the attribute to remove
 */
export declare function removeSync(this: V_Context, path: string, name: Name): void;
/**
 * Lists all extended attributes of a file.
 *
 * @param path Path to the file
 * @returns Array of attribute names
 */
export declare function list(this: V_Context, path: string): Promise<Name[]>;
/**
 * Synchronously lists all extended attributes of a file.
 *
 * @param path Path to the file
 * @returns Array of attribute names
 */
export declare function listSync(this: V_Context, path: string): Name[];