@struktoai/mirage-core/dist/cache/index/listing_memo.d.ts

A Unified Virtual Filesystem For AI Agents

import { FileStat } from '../../types.ts';
import type { Clock } from '../../utils/clock.ts';
import type { ListResult } from './config.ts';
/**
 * The listings one store read for the running commands.
 *
 * A read is served again only to the command that made it, only while no
 * listing write to the key prefix has finished since the read began, for
 * under LISTING_TRUST_WINDOW seconds, and never past the listing's own
 * expiry. Row reads batch at most ROW_READ_BATCH siblings and share this
 * lifetime, a row the batch did not find is left to a lookup of its own,
 * and a row-only write drops that row alone. Each fill drops the oldest
 * reads no command can be served any more, so a read stays held for about
 * one window. The key prefix's write count lives while an open memo holds
 * the prefix. On the fallback storage, while more than one command is live,
 * there is no sole stamp and every read goes to Redis.
 */
export declare class ListingMemo {
    private readonly keyPrefix;
    private readonly clock;
    private readonly reads;
    private closed;
    private readonly reference;
    /**
     * @param keyPrefix the store's key prefix, whose writes count.
     * @param clock the store's clock, whose wall time a listing's expiry is
     *   compared with.
     */
    constructor(keyPrefix: string, clock: Clock);
    private written;
    private live;
    /** Whether this command's live listings already name every observed child key. */
    allows(paths: readonly string[]): boolean;
    /** Whether a live listing any open memo on this prefix keeps leaves out an observed child key. */
    contradicts(paths: readonly string[]): boolean;
    /**
     * A folder's listing, read from Redis at most once per command.
     *
     * @param folder the listed folder's key.
     * @param fetch reads the listing from Redis and answers it with its
     *   expiry, or with null when there is no live listing to keep.
     * @param child the one key a lookup asks about, to narrow the entries to.
     */
    read(folder: string, fetch: () => Promise<[ListResult, number | null]>, child?: string): Promise<ListResult>;
    /** Batch a listed row with its siblings within the listing's lifetime. */
    row(path: string, fetch: (paths: readonly string[]) => Promise<Map<string, FileStat>>): Promise<FileStat | null>;
    /** Count a finished write of one row, keeping its siblings' reads. */
    rowWrote(path: string): void;
    /** Runs `fn` and counts a listing write once it is over, whether it threw or not. */
    writing<T>(fn: () => Promise<T>): Promise<T>;
    /** Counts a finished listing write to the key prefix. */
    wrote(): void;
    /**
     * Drops the kept listings and releases the key prefix. The last open memo
     * on a prefix drops its write count, so a host that cycles through
     * prefixes keeps none it no longer uses.
     */
    close(): void;
}
//# sourceMappingURL=listing_memo.d.ts.map