@struktoai/mirage-core/dist/core/msgraph/drive.d.ts

A Unified Virtual Filesystem For AI Agents

import type { ByteSource } from '../../io/types.ts';
import { DirListing, FileStat, type PathSpec } from '../../types.ts';
import type { resolveMsGraphConfig } from './config.ts';
export type DriveUrl = (path: string, action?: string) => string;
export type DriveRef = (folder?: string) => string;
export declare class DriveLoc {
    readonly drive: string;
    readonly path: string;
    readonly virtual: string;
    private readonly url;
    private readonly ref;
    constructor(init: {
        drive: string;
        path: string;
        virtual: string;
        url: DriveUrl;
        ref: DriveRef;
    });
    item(action?: string): string;
    itemAt(path: string, action?: string): string;
    child(name: string): DriveLoc;
    parent(): string;
    reference(folder?: string): string;
}
export declare function parentPath(path: string): string;
export declare function baseName(path: string): string;
export declare function directoryPath(path: PathSpec): PathSpec;
export declare function virtualKey(path: PathSpec): string;
export declare function asNumber(value: unknown): number | null;
export declare function folderChildCount(item: Record<string, unknown>): number | null;
export declare function copyTree(config: ReturnType<typeof resolveMsGraphConfig>, src: DriveLoc, dst: DriveLoc, srcVirtual?: string, dstVirtual?: string): Promise<void>;
/** What a renameReplace moved, and what it replaced. */
export interface MovedItem {
    moved: Record<string, unknown>;
    replacedNonFile: boolean;
}
/**
 * Move `src` to `dst`, replacing a file or an empty folder there. Answers
 * the moved driveItem and whether the move replaced something at `dst`
 * that was not positively a file.
 */
export declare function renameReplace(config: ReturnType<typeof resolveMsGraphConfig>, src: DriveLoc, dst: DriveLoc, srcVirtual?: string, dstVirtual?: string): Promise<MovedItem>;
export interface FolderTarget {
    item: string;
    parent: string;
    virtual: string;
}
/**
 * Create one folder, naming a refusal the way mkdir(2) does.
 *
 * "replace" is unreliable for folders on real Graph, so the create uses
 * "fail" and reads its 409: a folder already holding the name is success when
 * `existOk` (a level `mkdir -p` passes through) and EEXIST otherwise, so a
 * folder another client made after the lookup ran is still refused; a file
 * holding it is EEXIST. Graph answers a create under a missing parent and
 * under a file alike with 404, so the parent is looked up to tell ENOENT from
 * ENOTDIR. Both lookups run on a refusal only. Mirrors Python's
 * `create_child_folder`.
 */
export declare function createChildFolder(config: ReturnType<typeof resolveMsGraphConfig>, parentUrl: string, name: string, target: FolderTarget, existOk?: boolean): Promise<void>;
/**
 * Replace a drive item's content, creating it and its parents, and answer how
 * many bytes went. A small body is one `PUT`; anything past the simple-upload
 * limit goes through an upload session. A stream is spooled first, so its size
 * picks between the two; `signal` stops it.
 */
export declare function writeItem(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, data: ByteSource, signal?: AbortSignal, virtual?: string): Promise<number>;
export declare function readItem(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, virtual: string, backend: string, offset?: number, size?: number | null): Promise<Uint8Array>;
export declare function streamItem(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, virtual: string, backend: string): AsyncIterable<Uint8Array>;
export declare function iterTree(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, virtual?: string): AsyncIterable<[string, Record<string, unknown>, boolean]>;
/**
 * The id of the folder a driveItem sits in, '' when it names none: a listing's
 * item or a `/delta` feed's. Mirrors Python's `parent_id`.
 */
export declare function parentId(item: {
    parentReference?: unknown;
}): string;
/**
 * Every item under a folder, each as a listing's stat renders it, from one
 * read of Graph's `/delta` feed started at that folder.
 *
 * One request asks the folder for its id, then the feed lists every item below
 * it a page at a time, where a walk sends a listing per folder. The feed names
 * an item by id with its name and its parent's id, never its path, and may
 * list one more than once (its last row is its state), so each is placed by
 * its parents up to the folder. An item under one a listing shows as a file (a
 * package's contents) is left out, as a listing of that file would leave it.
 * Null when no folder is at `loc`, so the walk's readdir reports what is
 * there, when Graph refuses the feed, when the feed does not list the folder
 * the first request found (another folder took its path in between, and the
 * feed describes that one), when the feed holds a folder shared from another
 * drive, whose items only that drive's feed lists, and when a file
 * comes without the `cTag` its listing row carries (OneDrive for Business and
 * SharePoint leave it out of the feed), since the mount keeps the answer as
 * the folders' listings. Mirrors Python's `delta_tree`.
 */
export declare function deltaTree(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, virtual?: string): Promise<Map<string, FileStat> | null>;
/**
 * Every item under a folder, each as its folder's listing renders it, from the
 * folders' listings sent `BATCH_LIMIT` to a request through Graph's JSON
 * batching, where a walk sends a request per folder.
 *
 * The folder's own children are its listing (`readdirItems`), so a folder that
 * is not there raises what a listing raises. A listing the batch does not
 * answer with its first page (Graph throttled or failed that one) is asked on
 * its own, once the longest wait the batch's answers asked for has passed since
 * it arrived (one wait a batch, each answer's counted from the same moment),
 * and a listing's later pages are read as a listing reads them. Null when
 * Graph refuses a batch, or when a
 * listing below the folder fails (a folder gone, or one the account may not
 * open), so the walk lists what is there and reports, or skips, each folder on
 * its own; null too once it holds more than `limit` items, which no listing
 * is paged past. Mirrors Python's `batch_tree`.
 */
export declare function batchTree(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, path: PathSpec, limit?: number): Promise<Map<string, FileStat> | null>;
export declare function driveRootEmpty(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, virtual?: string): Promise<boolean>;
/**
 * A folder's children, each as `stat` answers it; past a walk's `limit` Graph
 * is paged no further, and the listing is partial. Mirrors Python's
 * `readdir_items`.
 */
export declare function readdirItems(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, path: PathSpec, limit?: number): Promise<FileStat[] | DirListing>;
/** One drive item's stat, from Graph. Mirrors Python's `stat_item`. */
export declare function statItem(config: ReturnType<typeof resolveMsGraphConfig>, loc: DriveLoc, path: PathSpec): Promise<FileStat>;
export declare function makeExists<A>(stat: (accessor: A, path: PathSpec) => Promise<unknown>): (accessor: A, path: PathSpec) => Promise<boolean>;
export declare function makeTruncate<A>(read: (accessor: A, path: PathSpec) => Promise<Uint8Array>, write: (accessor: A, path: PathSpec, data: Uint8Array) => Promise<void>): (accessor: A, path: PathSpec, length: number, noCreate?: boolean) => Promise<void>;
//# sourceMappingURL=drive.d.ts.map