@lapis-notes/api 0.1.0

package/dist/cache.svelte.d.ts

@@ -0,0 +1,569 @@
+import type { App } from "./context.svelte";
+import { EventDispatcher } from "./events";
+import {
+    TFile,
+    type AppDatabaseChangeSet,
+    type AppDatabaseIndexedMetadataPage,
+    type AppDatabaseIndexedMetadataPageQuery,
+    type AppDatabaseIndexedMetadataQuery,
+    type AppDatabaseIndexedMetadataRow,
+    type AppDatabaseLinkRecord,
+    type AppDatabaseMetadataFacetQuery,
+    type AppDatabaseMetadataFacetRow,
+    type AppDatabaseMetadataLinkQuery,
+    type MetadataCacheSnapshot,
+} from "./storage";
+export declare const METADATA_CACHE_BACKUP_PATH = ".lapis/cache/metadata-cache.json";
+export declare const METADATA_CACHE_HOT_LIMIT = 512;
+/**
+ * Location within a Markdown document
+ *
+ * @public
+ */
+export interface Loc {
+    /**
+     * Line number. 0-based.
+     *
+     * @public
+     */
+    line: number;
+    /**
+     * Column number.
+     *
+     * @public
+     */
+    col: number;
+    /**
+     * Number of characters from the beginning of the file.
+     *
+     * @public
+     */
+    offset: number;
+}
+/**
+ * Describes a text range in a Markdown document.
+ *
+ * @public
+ */
+export interface Pos {
+    /**
+     * Starting location.
+     *
+     * @public
+     */
+    start: Loc;
+    /**
+     * End location.
+     *
+     * @public
+     */
+    end: Loc;
+}
+export interface CacheItem {
+    /**
+     * Position of this item in the note.
+     *
+     * @public
+     */
+    position: Pos;
+}
+export interface HeadingCache extends CacheItem {
+    /** @public */
+    heading: string;
+    /**
+     * Number between 1 and 6.
+     *
+     * @public
+     */
+    level: number;
+}
+export interface TagCache extends CacheItem {
+    /** @public */
+    tag: string;
+}
+export interface FootnoteCache extends CacheItem {
+    /** @public */
+    id: string;
+}
+export interface BlockCache extends CacheItem {
+    /** @public */
+    id: string;
+}
+/**
+ * Base interface for items that point to a different location.
+ *
+ * @public
+ */
+export interface Reference {
+    /**
+     * Link destination.
+     *
+     * @public
+     */
+    link: string;
+    /**
+     * Contains the text as it's written in the document. Not available on
+     * Publish.
+     *
+     * @public
+     */
+    original: string;
+    /**
+     * Available if title is different from link text, in the case of `[[page
+     * name|display name]]` this will return `display name`
+     *
+     * @public
+     */
+    displayText?: string;
+}
+export interface ReferenceCache extends Reference, CacheItem {
+}
+export interface LinkCache extends ReferenceCache {
+    heading?: string;
+}
+export interface EmbedCache extends ReferenceCache {
+}
+export interface SectionCache extends CacheItem {
+    /**
+     * The block ID of this section, if defined.
+     *
+     * @public
+     */
+    id?: string | undefined;
+    /**
+     * The type string generated by the parser. Typing is non-exhaustive, more
+     * types can be available than are documented here.
+     *
+     * @public
+     */
+    type: "blockquote" | "callout" | "code" | "element" | "footnoteDefinition" | "heading" | "html" | "list" | "paragraph" | "table" | "text" | "thematicBreak" | "yaml" | string;
+}
+export interface ListItemCache extends CacheItem {
+    /**
+     * The block ID of this list item, if defined.
+     *
+     * @public
+     */
+    id?: string | undefined;
+    /**
+     * A single character indicating the checked status of a task. The space
+     * character `' '` is interpreted as an incomplete task. An other character is
+     * interpreted as completed task. `undefined` if this item isn't a task.
+     *
+     * @public
+     */
+    task?: string | undefined;
+    /**
+     * Line number of the parent list item (position.start.line). If this item has
+     * no parent (e.g. it's a root level list), then this value is the negative of
+     * the line number of the first list item (start of the list).
+     *
+     * Can be used to deduce which list items belongs to the same group
+     * (item1.parent === item2.parent). Can be used to reconstruct hierarchy
+     * information (parentItem.position.start.line === childItem.parent).
+     *
+     * @public
+     */
+    parent: number;
+}
+export interface FootnoteRefCache extends CacheItem {
+    /** @public */
+    id: string;
+}
+export interface ReferenceLinkCache extends CacheItem {
+    /** @public */
+    id: string;
+    /** @public */
+    link: string;
+}
+export interface FrontMatterCache {
+    /** @public */
+    [key: string]: any;
+}
+export interface FrontMatterInfo {
+    /** @public Whether this file has a frontmatter block */
+    exists: boolean;
+    /** @public String representation of the frontmatter */
+    frontmatter: string;
+    /** @public Start of the frontmatter contents (excluding the ---) */
+    from: number;
+    /** @public End of the frontmatter contents (excluding the ---) */
+    to: number;
+    /** @public Offset where the frontmatter block ends (including the ---) */
+    contentStart: number;
+}
+export declare function getFrontMatterInfo(content: string): FrontMatterInfo;
+export declare function parseFrontMatterTags(frontmatter: any | null): string[] | null;
+export declare function parseFrontMatterStringArray(frontmatter: any | null, key: string): string[] | null;
+export declare function parseFrontMatterAliases(frontmatter: any | null): string[] | null;
+export declare function parseFrontMatterEntry(frontmatter: any | null, key: string): any | null;
+export interface FrontmatterLinkCache extends Reference {
+    /** @public */
+    key: string;
+}
+export interface CachedMetadata {
+    /**
+     * Position of the frontmatter in the file.
+     *
+     * @public
+     */
+    frontmatterPosition?: Pos;
+    links?: LinkCache[];
+    embeds?: EmbedCache[];
+    tags?: TagCache[];
+    /**
+     * Sections are root level markdown blocks, which can be used to divide the
+     * document up.
+     *
+     * @public
+     */
+    sections?: SectionCache[];
+    listItems?: ListItemCache[];
+    frontmatter?: FrontMatterCache;
+    headings?: HeadingCache[];
+    footnotes?: FootnoteCache[];
+    footnoteRefs?: FootnoteRefCache[];
+    referenceLinks?: ReferenceLinkCache[];
+    blocks?: Record<string, BlockCache>;
+}
+export interface SubpathResult {
+    start: Loc;
+    end: Loc | null;
+}
+export interface HeadingSubpathResult extends SubpathResult {
+    type: "heading";
+    current: HeadingCache;
+    next: HeadingCache | null;
+}
+export interface BlockSubpathResult extends SubpathResult {
+    type: "block";
+    block: BlockCache;
+    list?: ListItemCache;
+}
+export interface FootnoteSubpathResult extends SubpathResult {
+    type: "footnote";
+    footnote: FootnoteCache;
+}
+export declare function iterateRefs(refs: Reference[], cb: (ref: Reference) => boolean | void): boolean;
+export declare function iterateCacheRefs(cache: CachedMetadata, cb: (ref: ReferenceCache) => boolean | void): boolean;
+export declare function resolveSubpath(cache: CachedMetadata, subpath: string): HeadingSubpathResult | BlockSubpathResult | FootnoteSubpathResult | null;
+export type MetadataProcessor = {
+    read: (data: string, context: {
+        cache: CachedMetadata;
+        file: TFile;
+    }) => Promise<CachedMetadata>;
+    write: (cache: CachedMetadata) => string;
+};
+export type IndexedProjectionContribution = {
+    task?: import("./storage/task-projection").AppDatabaseTaskRecord | null;
+};
+export type IndexedProjectionContributor = {
+    project(input: {
+        file: TFile;
+        content: string;
+        cache: CachedMetadata;
+    }): IndexedProjectionContribution | null | Promise<IndexedProjectionContribution | null>;
+};
+export interface MetadataCacheSnapshotLease {
+    readonly snapshot: MetadataCacheSnapshot;
+    release(): void;
+}
+export interface MetadataCacheQueryWatch<T> {
+    dispose(): void;
+    refresh(): Promise<void>;
+    readonly current: T | undefined;
+}
+/**
+ * Indexes parsed markdown metadata, tags, headings, and resolved links for the
+ * active vault.
+ *
+ * @public
+ */
+export declare class MetadataCache extends EventDispatcher<{
+    /**
+     * Called when a file has been indexed, and its (updated) cache is now
+     * available.
+     *
+     * Note: This is not called when a file is renamed for performance reasons.
+     * You must hook the vault rename event for those.
+     *
+     * @public
+     */
+    changed: [file: TFile, data: string, cache: CachedMetadata];
+    /**
+     * Called when a file has been deleted. A best-effort previous version of the
+     * cached metadata is presented, but it could be null in case the file was not
+     * successfully cached previously.
+     *
+     * @public
+     */
+    deleted: [file: TFile, prevCache: CachedMetadata | null];
+    /** Called once the persisted metadata index is queryable. */
+    loaded: [];
+    /** Called after an indexed database mutation commits. */
+    "index-changed": [change: AppDatabaseChangeSet];
+}> {
+    #private;
+    readonly app: App;
+    processors: Map<string, Set<MetadataProcessor>>;
+    projectionContributors: Set<IndexedProjectionContributor>;
+    readonly logger: import("./logging").Logger;
+    private readonly saveSnapshotDebounced;
+    constructor(app: App);
+    get metadataCache(): Record<string, CachedMetadata>;
+    get resolvedLinks(): Record<string, Record<string, number>>;
+    get unresolvedLinks(): Record<string, Record<string, number>>;
+    get fileCache(): Record<string, {
+        mtime: number;
+        size: number;
+        hash: string;
+    }>;
+    get initialized(): boolean;
+    getAllItems(): Map<TFile, CachedMetadata>;
+    scheduleSnapshotSave(): void;
+    flushSnapshotSave(): Promise<void>;
+    dispose(options?: {
+        persist?: boolean;
+    }): Promise<void>;
+    saveSnapshotNow(options?: {
+        forceBackup?: boolean;
+    }): Promise<void>;
+    toJSON(): {
+        fileCache: {
+            [x: string]: {
+                mtime: number;
+                size: number;
+                hash: string;
+            };
+        };
+        metadataCache: {
+            [x: string]: {
+                frontmatterPosition?: {
+                    start: {
+                        line: number;
+                        col: number;
+                        offset: number;
+                    };
+                    end: {
+                        line: number;
+                        col: number;
+                        offset: number;
+                    };
+                } | undefined;
+                links?: {
+                    link: string;
+                    original: string;
+                    displayText?: string | undefined;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                embeds?: {
+                    link: string;
+                    original: string;
+                    displayText?: string | undefined;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                tags?: {
+                    tag: string;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                sections?: {
+                    id?: string | undefined | undefined;
+                    type: "blockquote" | "callout" | "code" | "element" | "footnoteDefinition" | "heading" | "html" | "list" | "paragraph" | "table" | "text" | "thematicBreak" | "yaml" | string;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                listItems?: {
+                    id?: string | undefined | undefined;
+                    task?: string | undefined | undefined;
+                    parent: number;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                frontmatter?: {
+                    [x: string]: any;
+                } | undefined;
+                headings?: {
+                    heading: string;
+                    level: number;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                footnotes?: {
+                    id: string;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                footnoteRefs?: {
+                    id: string;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                referenceLinks?: {
+                    id: string;
+                    link: string;
+                    position: {
+                        start: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                        end: {
+                            line: number;
+                            col: number;
+                            offset: number;
+                        };
+                    };
+                }[] | undefined;
+                blocks?: {
+                    [x: string]: {
+                        id: string;
+                        position: {
+                            start: {
+                                line: number;
+                                col: number;
+                                offset: number;
+                            };
+                            end: {
+                                line: number;
+                                col: number;
+                                offset: number;
+                            };
+                        };
+                    };
+                } | undefined;
+            };
+        };
+        resolvedLinks: {
+            [x: string]: {
+                [x: string]: number;
+            };
+        };
+        unresolvedLinks: {
+            [x: string]: {
+                [x: string]: number;
+            };
+        };
+    };
+    private applySnapshot;
+    private loadPortableBackupSnapshot;
+    private savePortableBackup;
+    private loadLegacySnapshot;
+    load(): Promise<void>;
+    private loadPrimarySnapshot;
+    private hydrateDatabaseFromSnapshot;
+    private reconcileSnapshotWithVault;
+    getReconciliationFingerprint(): string;
+    getFileCache(file: TFile): CachedMetadata | null;
+    getCache(path: string): CachedMetadata | null;
+    getFileCacheAsync(file: TFile | string): Promise<CachedMetadata | null>;
+    queryMetadataPage(query?: AppDatabaseIndexedMetadataPageQuery): Promise<AppDatabaseIndexedMetadataPage>;
+    queryMetadata(query?: AppDatabaseIndexedMetadataQuery): Promise<AppDatabaseIndexedMetadataRow[]>;
+    queryFacets(query: AppDatabaseMetadataFacetQuery): Promise<AppDatabaseMetadataFacetRow[]>;
+    queryLinks(query: AppDatabaseMetadataLinkQuery): Promise<AppDatabaseLinkRecord[]>;
+    watchQuery(query: AppDatabaseIndexedMetadataPageQuery, listener: (page: AppDatabaseIndexedMetadataPage) => void, onError?: (error: unknown) => void): MetadataCacheQueryWatch<AppDatabaseIndexedMetadataPage>;
+    acquireMetadataSnapshotLease(): Promise<MetadataCacheSnapshotLease>;
+    getDirectReferencePaths(sourcePath: string): string[];
+    pathDirectlyReferences(sourcePath: string, targetPath: string): boolean;
+    getDirectReferencingPaths(targetPath: string): string[];
+    isDirectlyAffectedByPathChange(watchedPath: string | null | undefined, changedPath: string | null | undefined): boolean;
+    getFirstLinkpathDest(linkpath: string, sourcePath: string): TFile | null;
+    fileToLinktext(file: TFile, sourcePath: string, omitMdExtension?: boolean): string;
+    rebuild(): Promise<void>;
+    addProcessor(ext: string, processor: MetadataProcessor): void;
+    removeProcessor(ext: string, processor: MetadataProcessor): boolean;
+    addIndexedProjectionContributor(contributor: IndexedProjectionContributor): void;
+    removeIndexedProjectionContributor(contributor: IndexedProjectionContributor): boolean;
+    private handleChange;
+    private handleRename;
+    private processFile;
+    private extractLink;
+    private processLink;
+    private toDatabaseRecord;
+    processFileCache(file: TFile | string | null): Promise<CachedMetadata | null>;
+    read(content: string, file: TFile): Promise<CachedMetadata | null>;
+    writeFrontmatter(file: TFile, data: FrontMatterCache): string;
+}
+export declare function getAllTags(cache: CachedMetadata): string[] | null;